> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: FillButton Component

## Article: FillButton Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/swatches/fill-button-component.md

## Article Content:

# FillButton

_Components/Form/Swatches/FillButton_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/fillbutton>

## Overview

```jsx
() => {
  const [selectedIndex, setSelectedIndex] = React.useState(0);
  const [shown, setShown] = React.useState(false);
  const [colors, setColors] = React.useState([
    '#ffbc42',
    '#d81159',
    '#8f2d56',
    '#218380',
  ]);

  return (
    <FormField label="T-shirt color:">
      <Box height="24px">
        <Layout cols={7} gap="12px">
          <Popover shown={shown} showArrow>
            <Popover.Element>
              <FillButton
                tooltipContent="Order custom color"
                onClick={() => setShown(!shown)}
              />
            </Popover.Element>
            <Popover.Content>
              <ColorPicker
                value="#86c6e5"
                showConverter={false}
                onChange={() => {}}
                onConfirm={(color) => {
                  setShown(false);
                  setColors([...colors, color.hex()]);
                }}
                onCancel={() => setShown(false)}
              />
            </Popover.Content>
          </Popover>
          {colors.map((color, index) => (
            <FillPreview
              fill={color}
              selected={selectedIndex === index}
              onClick={() => setSelectedIndex(index)}
            />
          ))}
        </Layout>
      </Box>
    </FormField>
  );
};
```

Fill button allows to add a new color swatch to an existing list of options. It's used as a building part for `<Swatches/>` component.

### Do

- Use it to add a new swatch to the list of colors or gradients.
- Use it to call out the color picker popover.
- Use it to call out Media Manager to pick an image.

### Don't

- Don't use it as a standalone element. It should be accompanied by a list of `<FillPreview/>` elements or be a part of `<Swatches/>`.

### Feature examples

#### Icon size

Control plus icon size inside of a button:\
 - \`small\` (default) - use it when the button's width is 30 pixels or smaller.\
 - \`medium\` - use it when the button's width is larger than 30 pixels.

```jsx
<StorybookComponents.Stack gap="12px">
  <FillButton iconSize="small" tooltipContent="Small" />
  <FillButton iconSize="medium" tooltipContent="Medium" />
</StorybookComponents.Stack>;
```

#### Fill

Set the button's fill-in HEX color or linear gradient. Component allows control of the gradient direction.

```jsx
<StorybookComponents.Stack gap="24px">
  <FillButton tooltipContent="no fill" />
  <FillButton fill="#3399ff" tooltipContent="hex" />
  <FillButton
    fill="linear-gradient(#73d2de, #3399ff)"
    tooltipContent="linear gradient"
  />
  <FillButton
    fill="linear-gradient(to right top, #73d2de, #3399ff)"
    tooltipContent="to right top linear gradient"
  />
</StorybookComponents.Stack>;
```

#### Disabled

Restrict button interactions with \`disabled\` prop. This will prevent users from adding a new swatch.

```jsx
<StorybookComponents.Stack>
  <FillButton disabled />
</StorybookComponents.Stack>;
```

#### Tooltip

Explain the action with a message in a tooltip. Control the tooltip position and behaviour by passing relevant properties via \`tooltipProps\`.

```jsx
<StorybookComponents.Stack>
  <FillButton
    tooltipContent="Message explaining the action"
    tooltipProps={{
      placement: 'right',
      maxWidth: 400,
    }}
  />
</StorybookComponents.Stack>;
```

#### Icon

Display a custom icon inside of a button using icon prop.\
\
Default icon is a plus and is displayed all the time unless specified otherwise.\
\
Overridden icon size cannot be controlled using \`iconSize\` property. Size has to be controlled manually.

```jsx
<StorybookComponents.Stack gap="12px">
  <FillButton tooltipContent="Add" />
  <FillButton icon={<Icons.EditSmall />} tooltipContent="Edit" />
</StorybookComponents.Stack>;
```

### Common use case examples

#### Adding custom swatch

Use a fill button to add new fill options to the existing list. It's recommended to place it as the first item on the list, because it won't be moved down when new colors appear, letting the user always find it.\
\
It can be used with `<FileUpload/>` to open a native file picker to upload images.

```jsx
() => {
  const [selectedId, setSelectedId] = React.useState(0);

  return (
    <Layout gap="12px">
      <FileUpload multiple accept=".jpeg,.gif,.png" onChange={() => {}}>
        {({ openFileUploadDialog }) => (
          <FillButton
            iconSize="medium"
            tooltipContent="Upload image"
            onClick={openFileUploadDialog}
          />
        )}
      </FileUpload>
      <Tooltip content="Black & white geometric shapes" size="small">
        <FillPreview
          fill="PatternExample4.jpg"
          selected={selectedId === 1}
          onClick={() => setSelectedId(1)}
        />
      </Tooltip>
      <Tooltip content="Multicolored wallpaper" size="small">
        <FillPreview
          fill="PatternExample5.jpg"
          selected={selectedId === 2}
          onClick={() => setSelectedId(2)}
        />
      </Tooltip>
      <Tooltip content="Color twirl pattern" size="small">
        <FillPreview
          fill="PatternExample6.jpg"
          selected={selectedId === 3}
          onClick={() => setSelectedId(3)}
        />
      </Tooltip>
    </Layout>
  );
};
```

## Code

```jsx
import { FillButton } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — | Specify whether button should be disabled or not. |
| `fill` | `string` | — | Defines button fill value in string format. Accepts HEX colors and gradients. |
| `icon` | `ReactNode` | — | Overrides the default plus icon with any Wix Design System icon. This doesn't work together with `iconSize`, so control the icon size manually. |
| `iconSize` | `"small" \| "medium"` | `'small'` | Controls the size of a plus icon. |
| `onClick` | `MouseEventHandler` | — | Defines a callback handler. Handler is called whenever a button is clicked. |
| `tooltipContent` | `ReactNode` | — | Specifies a message to display on button hover. |
| `tooltipProps` | `TooltipCommonProps` | — | Allows to pass tooltip common props. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { FillButtonUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { FillButtonTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { FillButtonTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { FillButtonTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `click` | clicks on trigger element |
| `getTooltipText` | Gets the tooltip text |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.330.1** (2026-09-28) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.271.0** (2026-04-22) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.246.0** (2026-01-09) — maintenance release, no component-specific changes
- **1.243.0** (2025-12-23) — maintenance release, no component-specific changes
- **1.242.0** (2025-12-19) — maintenance release, no component-specific changes
- **1.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.220.0** (2025-09-29) — fix: add cursor:pointer to FillButton when enabled ([#15345](invalid-url))
- **1.216.0** (2025-09-01) — breaking: e3 tokenization ([#15252](invalid-url))
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.166.0** (2025-03-04) — maintenance release, no component-specific changes
- **1.145.0** (2024-12-09) — breaking: tokenize ([#14086](invalid-url))
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.104.0** (2024-05-06) — fix: fix submitting form on click ([#13687](invalid-url))
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes