> 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: FillPreview Component

## Article: FillPreview Component

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

## Article Content:

# FillPreview

_Components/Form_

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

## Overview

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

  return (
    <Box align="center">
      <FormField label="Product color:" stretchContent={false}>
        <Box height="24px">
          <Layout cols={7} gap="12px">
            <FillPreview
              fill="#ffbc42"
              selected={selectedIndex === 1}
              onClick={() => setSelectedIndex(1)}
            />
            <FillPreview
              fill="#d81159"
              selected={selectedIndex === 2}
              onClick={() => setSelectedIndex(2)}
            />
            <FillPreview
              fill="#8f2d56"
              selected={selectedIndex === 3}
              onClick={() => setSelectedIndex(3)}
            />
            <FillPreview
              fill="#218380"
              selected={selectedIndex === 4}
              onClick={() => setSelectedIndex(4)}
            />
            <FillPreview
              fill="#73d2de"
              selected={selectedIndex === 5}
              onClick={() => setSelectedIndex(5)}
            />
            <FillPreview
              fill="#3399ff"
              selected={selectedIndex === 6}
              onClick={() => setSelectedIndex(6)}
            />
          </Layout>
        </Box>
      </FormField>
    </Box>
  );
};
```

A clickable preview for colors, gradients, images and vector graphics. Mainly used as a building part for `<Swatches/>` component, but can be used as a standalone item too.

### Do

- Use it to create a swatch of selectable colors, gradients or images.
- Use it to list available style options for the fill.

### Don't

- Don't use it to make large swatches. When a big preview is required, use `<Thumbnail/>` instead.

### Feature examples

#### Fill

Render preview content with `fill` prop. It accepts:

- colors
- gradients
- colors with opacity
- images
- SVGs

```jsx
<StorybookComponents.Stack width="24px">
  <FillPreview size="medium" fill="#3399ff" />
  <FillPreview
    size="medium"
    fill="linear-gradient(to right top, #3399ff, #ffffff)"
  />
  <FillPreview
    size="medium"
    fill={['rgba(0, 0, 0, 0.2)', 'rgba(0, 0, 0, 1)']}
  />
  <FillPreview
    size="medium"
    fill="https://images.unsplash.com/photo-1559825481-12a05cc00344?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxzZWFyY2h8Mnx8b2NlYW58ZW58MHx8MHx8&auto=format&fit=crop&w=500&q=60"
  />
  <FillPreview size="medium" fill={<Icons.HomeSmall />} />
</StorybookComponents.Stack>;
```

#### Multiple colors

Display up to four selected colors in the fill preview. Use the `fill` prop to pass definitions for up to four colors, including those with opacity. This feature is useful for visualizing selections that involve semi-transparent colors.

**Note**: Each color segment is not individually interactive, the entire element is a single clickable area to ensure a sufficient hit target.

```jsx
<StorybookComponents.Stack width="24px">
  <FillPreview aspectRatio={1} fill="#3399ff" size="medium" />
  <FillPreview
    aspectRatio={1}
    fill={['rgba(51, 153, 255, 0.4)', '#3399ff']}
    size="medium"
  />
  <FillPreview
    aspectRatio={1}
    fill={['rgb(0, 0, 0, 0.3)', 'rgb(0, 0, 0, 1)', '#59A96A']}
    size="medium"
  />
  <FillPreview
    aspectRatio={1}
    fill={['#E1F0C4', '#9BDEAC', '#636940', '#59A96A']}
    size="medium"
  />
</StorybookComponents.Stack>;
```

#### Size

Control the component size with the size prop. The component supports **five sizes**:

- `extraTiny`, use in very dense layouts for display purposes only. Keep in mind that this size does not provide a sufficient clickable area, so use it sparingly.
- `tiny`, use in tight layouts where space is limited.
- `small`, use to display rows of color selections. This size is also used in other components, such as `<ColorPicker/>`.
- `medium`, use in design settings panels.
- `large`, use in spacious layouts, especially when only a few `<FillPreview/>` components are present.

```jsx
<StorybookComponents.Stack width="24px">
  <FillPreview size="extraTiny" fill="#3399ff" />
  <FillPreview size="tiny" fill="#3399ff" />
  <FillPreview size="small" fill="#3399ff" />
  <FillPreview size="medium" fill="#3399ff" />
  <FillPreview size="large" fill="#3399ff" />
</StorybookComponents.Stack>;
```

#### Preview ratio

Control preview ratio with the `aspectRatio` prop. By default, the component maintains a 1:1 ratio when the width of parent container is defined.

```jsx
<StorybookComponents.Stack width="24px">
  <FillPreview aspectRatio={1 / 4} fill="#3399ff" />
  <FillPreview aspectRatio={1 / 3} fill="#3399ff" />
  <FillPreview aspectRatio={1 / 2} fill="#3399ff" />
  <FillPreview aspectRatio={1} fill="#3399ff" />
</StorybookComponents.Stack>;
```

#### States

Control the component state with:

- `selected` - use to highlight active selection.
- `disabled` - use to highlight unavailable option.

```jsx
<StorybookComponents.Stack gap="18px">
  <StorybookComponents.Stack gap="24px" flexDirection="column">
    <FillPreview />
    <FillPreview fill="#3399ff" />
    <FillPreview fill="#3399ff" selected />
    <FillPreview fill="#3399ff" disabled />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack gap="24px" flexDirection="column">
    <StorybookComponents.Stack height="24px" alignItems="center">
      No value
    </StorybookComponents.Stack>
    <StorybookComponents.Stack height="24px" alignItems="center">
      Filled
    </StorybookComponents.Stack>
    <StorybookComponents.Stack height="24px" alignItems="center">
      Selected
    </StorybookComponents.Stack>
    <StorybookComponents.Stack height="24px" alignItems="center">
      Disabled
    </StorybookComponents.Stack>
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Render as

Render the preview as another component or DOM tag.

```jsx
<StorybookComponents.Stack gap="18px">
  <StorybookComponents.Stack gap="24px" flexDirection="column">
    <FillPreview fill="#73d2de" as="a" />
    <FillPreview fill="#3399ff" as="button" />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack gap="24px" flexDirection="column">
    <StorybookComponents.Stack height="24px" alignItems="center">
      <p>Rendered as &lt;a/&gt; tag</p>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack height="24px" alignItems="center">
      <p>Rendered as native &lt;button/&gt; tag</p>
    </StorybookComponents.Stack>
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Image fit

When `fill` is an image, `imageFit` controls how it is sized inside the preview:

- `cover` fills the preview and crops the overflow, keeping the image proportions.
- `contain` fits the whole image inside the preview, keeping its proportions.

With `imageFit` unset the image is stretched to the preview shape, which distorts it whenever the two ratios differ. The example below puts a wide image in a square preview, so each value is easy to tell apart.

```jsx
<StorybookComponents.Stack>
  <Box direction="vertical" gap="6px" align="center">
    <FillPreview
      size="large"
      aspectRatio={1}
      fill="https://images.unsplash.com/photo-1559825481-12a05cc00344?auto=format&fit=crop&w=600&h=200&q=60"
    />
    <Text size="tiny" secondary>
      unset (stretched)
    </Text>
  </Box>
  <Box direction="vertical" gap="6px" align="center">
    <FillPreview
      size="large"
      aspectRatio={1}
      imageFit="cover"
      fill="https://images.unsplash.com/photo-1559825481-12a05cc00344?auto=format&fit=crop&w=600&h=200&q=60"
    />
    <Text size="tiny" secondary>
      cover
    </Text>
  </Box>
  <Box direction="vertical" gap="6px" align="center">
    <FillPreview
      size="large"
      aspectRatio={1}
      imageFit="contain"
      fill="https://images.unsplash.com/photo-1559825481-12a05cc00344?auto=format&fit=crop&w=600&h=200&q=60"
    />
    <Text size="tiny" secondary>
      contain
    </Text>
  </Box>
</StorybookComponents.Stack>;
```

### Common use case examples

#### Fill type

Use fill preview to show the options of gradient fill types in forms.

```jsx
() => {
  const [inputValue, setInputValue] = React.useState('#ffffff');
  const [selected, setSelected] = React.useState(0);
  const [fillType, setFillType] = React.useState('gradient');

  const solidColors = ['#ffbc42', '#d81159', '#8f2d56', '#218380', '#73d2de'];
  const gradientColors = [
    'linear-gradient(45deg, rgba(14,0,255,1) 0%, rgba(0,212,255,1) 80%)',
    'linear-gradient(45deg, rgba(34,193,195,1) 0%, rgba(253,187,45,1) 100%)',
    'linear-gradient(to right top, #dbfd2d, #dd7c00)',
    'linear-gradient(to right, #00dd83, #22a0c3)',
    'linear-gradient(to right, #aa99ff, #aa11ff)',
  ];

  const renderFillPreview = ({ content, color, index }) => (
    <Tooltip appendTo="scrollParent" content={content}>
      <Box width="30px">
        <FillPreview
          selected={selected === index}
          onClick={() => setSelected(index)}
          fill={color}
        />
      </Box>
    </Tooltip>
  );

  return (
    <Card>
      <Card.Header title="Header style" />
      <Card.Divider />
      <Card.Content>
        <Layout>
          <Cell span={6}>
            <FormField label="Background fill type">
              <SegmentedToggle
                defaultSelected="gradient"
                selected={fillType}
                onClick={(_, value) => setFillType(value)}
              >
                <SegmentedToggle.Button value="solid">
                  Solid
                </SegmentedToggle.Button>
                <SegmentedToggle.Button value="gradient">
                  Gradient
                </SegmentedToggle.Button>
              </SegmentedToggle>
            </FormField>
          </Cell>
          <Cell span={6}>
            <FormField label="Background gradient">
              <Box gap="12px" height="36px" verticalAlign="middle">
                {fillType === 'solid'
                  ? solidColors.map((color, index) =>
                      renderFillPreview({
                        content: 'Solid color',
                        color,
                        index,
                      }),
                    )
                  : gradientColors.map((color, index) =>
                      renderFillPreview({
                        content: 'Gradient color',
                        color,
                        index,
                      }),
                    )}
              </Box>
            </FormField>
          </Cell>
          <Cell span={12}>
            <FormField label="Text color">
              <ColorInput value={inputValue} onConfirm={setInputValue} />
            </FormField>
          </Cell>
        </Layout>
      </Card.Content>
    </Card>
  );
};
```

#### Color selection

Use `<FillPreview/>` to let users select a color for different items.

```jsx
() => {
  const [value, setValue] = React.useState(50);
  const [opacity, setOpacity] = React.useState(100);

  return (
    <SidePanel
      skin="floating"
      width="420px"
      onCloseButtonClick={() => {}}
      onHelpButtonClick={() => {}}
    >
      <SidePanel.Header title="Wix Comments" />
      <Box height="480px">
        <VerticalTabs size="small" activeTabId={2} onChange={() => {}}>
          <VerticalTabs.TabItem id={0}>Display</VerticalTabs.TabItem>
          <VerticalTabs.TabItem id={1}>Layout</VerticalTabs.TabItem>
          <VerticalTabs.TabItem id={2}>Design</VerticalTabs.TabItem>
          <VerticalTabs.TabItem id={3}>Text</VerticalTabs.TabItem>
        </VerticalTabs>
        <Divider direction="vertical" />
        <SidePanel.Content noPadding>
          <SidePanel.Field>
            <Button
              priority="secondary"
              size="tiny"
              prefixIcon={<Icons.ChevronLeft />}
            >
              Back
            </Button>
          </SidePanel.Field>

          <SidePanel.Field>
            <FieldSet legend="Text font and color" columns="auto 30px">
              <SelectorButton size="small" suffixIcon={<Icons.ChevronDown />}>
                Wix Madefor Display
              </SelectorButton>
              <FillPreview fill="#839788" aspectRatio={1} />
            </FieldSet>
          </SidePanel.Field>

          <SidePanel.Field>
            <FieldSet gap="small" legend="Border width" columns="auto 72px">
              <Slider
                onChange={(nextValue) => setValue(Number(nextValue))}
                min={0}
                max={100}
                value={value}
                displayMarks={false}
              />
              <Input
                value={value}
                size="small"
                suffix={<Input.Affix>px</Input.Affix>}
                onChange={(e) => setValue(Number(e.target.value))}
              />
            </FieldSet>
          </SidePanel.Field>

          <SidePanel.Field>
            <FieldSet
              legend="Background color"
              legendSize="small"
              legendPlacement="top"
              alignment="center"
              columns="30px auto 67px"
            >
              <FillPreview fill="#000000" aspectRatio={1} />
              <Box margin="0 8px">
                <Slider
                  gradientColor="#000000"
                  min={0}
                  max={100}
                  displayMarks={false}
                  onChange={(nextOpacity) => setOpacity(Number(nextOpacity))}
                  value={opacity}
                />
              </Box>
              <NumberInput
                value={opacity}
                min={0}
                max={100}
                onChange={(nextOpacity) => setOpacity(nextOpacity)}
                suffix={<Input.Affix>%</Input.Affix>}
                size="small"
                hideStepper
              />
            </FieldSet>
          </SidePanel.Field>
        </SidePanel.Content>
      </Box>
    </SidePanel>
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `string \| ComponentClass<any, any> \| FunctionComponent<any>` | `'button'` | Renders the component as a given HTML tag or React component. |
| `aspectRatio` | `string \| number` | — | Control elements aspect ratio value. |
| `children` | `ReactNode` | — |  |
| `contentClassName` | `string` | — | Specifies a CSS class name to be appended to the content span element. |
| `contentRef` | `RefObject` | — | React ref to be attached to the content span. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — | Specify whether preview should be disabled or not. |
| `fill` | `ReactNode` | — | Specify a color, gradient, image URL, SVG or a list of colors to be rendered as a preview content. |
| `href` | `string` | — | URL of the page that link goes to. |
| `imageFit` | `"contain" \| "cover"` | — | Controls how an image `fill` is sized within the preview. When not set, the image stretches to fill the preview, which can distort its aspect ratio. |
| `onBlur` | `FocusEventHandler<unknown> & ((event: FocusEvent, triggers: Triggers) => void)` | — |  |
| `onFocus` | `FocusEventHandler<unknown> & ((event: FocusEvent, triggers: Triggers) => void)` | — |  |
| `prefixIcon` | `ReactElement` | — | Accepts an icon or a component to display before the content. |
| `ref` | `null \| string \| (instance: HTMLDivElement \| null) => void \| RefObject<HTMLDivElement>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `selected` | `boolean` | — | Specifies whether preview is selected or not. Selected item receives an outline border style. |
| `size` | `"small" \| "tiny" \| "medium" \| "large" \| "extraTiny"` | — | Controls the size of the element. |
| `suffixIcon` | `ReactElement` | — | Accepts an icon or a component to display after the content. |

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

| Method | Description |
| --- | --- |
| `click` | clicks on button |
| `isSelected` | returns true if item is selected |
| `getButtonStyle` | returns the style attribute string of the button element |
| `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.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.326.0** (2026-09-17) — 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.320.0** (2026-09-03) — feat: add an `imageFit` prop (`'cover' | 'contain'`, defaults to `'cover'`) to control how an image `fill` is sized within the preview. ([#16983](invalid-url)) — has visual 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.282.0** (2026-05-27) — fix: failing visual tests fix ([#16321](invalid-url)) — has visual changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.272.0** (2026-04-27) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.265.0** (2026-04-02) — fix: fix transparent background for radial gradients ([#16100](invalid-url)) — has visual changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.259.1** (2026-03-02) — fix: added mesh gradient support ([#15969](invalid-url))
- **1.259.0** (2026-02-27) — feat: add conic gradient support ([#15959](invalid-url))
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.228.0** (2025-11-18) — maintenance release, no component-specific changes
- **1.220.0** (2025-09-29) — breaking: e3 tokenization ([#15244](invalid-url))
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.207.0** (2025-07-24) — feat: multicolor ([#15099](invalid-url))
- **1.203.0** (2025-07-01) — feat: add size property ([#14532](invalid-url))
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.136.0** (2024-10-24) — feat: support css variable fill ([#14235](invalid-url))
- **1.133.0** (2024-10-14) — feat: add ref ([#14215](invalid-url))
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.103.1** (2024-04-24) — maintenance release, no component-specific changes
- **1.103.0** (2024-04-23) — fix: fix border rendering ([#13639](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