FillPreview

Components/Form

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

Overview

Copy

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
Copy

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.

Copy

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.
Copy

Preview ratio

Control preview ratio with the aspectRatio prop. By default, the component maintains a 1

ratio when the width of parent container is defined.

Copy

States

Control the component state with:

  • selected - use to highlight active selection.
  • disabled - use to highlight unavailable option.
Copy

Render as

Render the preview as another component or DOM tag.

Copy

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.

Copy

Common use case examples

Fill type

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

Copy

Color selection

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
asstring | ComponentClass<any, any> | FunctionComponent<any>'button'Renders the component as a given HTML tag or React component.
aspectRatiostring | number—Control elements aspect ratio value.
childrenReactNode—
contentClassNamestring—Specifies a CSS class name to be appended to the content span element.
contentRefRefObject—React ref to be attached to the content span.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disabledboolean—Specify whether preview should be disabled or not.
fillReactNode—Specify a color, gradient, image URL, SVG or a list of colors to be rendered as a preview content.
hrefstring—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.
onBlurFocusEventHandler<unknown> & ((event: FocusEvent, triggers: Triggers) => void)—
onFocusFocusEventHandler<unknown> & ((event: FocusEvent, triggers: Triggers) => void)—
prefixIconReactElement—Accepts an icon or a component to display before the content.
refnull | 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).
selectedboolean—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.
suffixIconReactElement—Accepts an icon or a component to display after the content.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
clickclicks on button
isSelectedreturns true if item is selected
getButtonStylereturns the style attribute string of the button element
existsChecks whether the component found with the given data hook.
elementGets the component root element.
baseReturns 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) — 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) — 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) — 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)
  • 1.259.0 (2026-02-27) — feat: add conic gradient support (#15959)
  • 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)
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.207.0 (2025-07-24) — feat: multicolor (#15099)
  • 1.203.0 (2025-07-01) — feat: add size property (#14532)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.136.0 (2024-10-24) — feat: support css variable fill (#14235)
  • 1.133.0 (2024-10-14) — feat: add ref (#14215)
  • 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)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?