Color Swatches

A collection of color samples to present color options for products.

Use Color Swatches...

  • To provide a visual representation of available colors for selection.
  • To allow users to compare and make more informed color decisions.
  • To help users with color blindness to make accurate color choices by including textual labels.

Don't use Color Swatches...

  • When color choice is not critical to the task as it can add clutter.
  • As is when there is a large set of Color Swatches. Use Accordion with skin="color-swatches" instead.

The preview has been updated.

Sizes

The default size is ”standard”. Use when displaying swatches in a small container, such as a Tile. Use size=”large” or size="super" to display a bigger swatch, such as in filters or on a product page. Use size=”xlarge” in editing experiences or when a user may need to differentiate between similar shades of a color.

The preview has been updated.

Fill

By default, color swatches have a checkered background to represent transparency. Passing no color or the transparent keyword will render a checkered background. This works with other props, excluding gradient.

The preview has been updated.

Primary Color

Use primaryColor to display a one-tone swatch.

The preview has been updated.

Passing no color or the transparent keyword will render no visible color.

The preview has been updated.

Secondary Color

Use both primaryColor and secondaryColor to display a two-tone swatch.

The preview has been updated.

Tertiary Color

Use all three primaryColor and secondaryColor and tertiaryColor to display a three-tone swatch.

The preview has been updated.

Gradient

Use either gradient="linear" or gradient="radial" to display a two-tone or three-tone swatch as a gradient, rather than as two distinct color zones.

The preview has been updated.

Background Image

Use backgroundImage to display an image instead of a color.

The preview has been updated.

Label position

Color Swatches More

Use ColorSwatchesMore, filling it with a + sign and a number, to indicate how many swatches are available, if there is not enough space to show them all.

The preview has been updated.

With a Selection Set

Use a Selection Set to present a collection of color samples the customer can choose from.

  • In the React API, add as="span" to each swatch.
  • In the Vanilla API, use a span tags for a valid HTML, since the swatches are inside label tags.

Refer to the Selection Set’s Accessibility documentation.

Radio Buttons

Use with variant="single-select" to prompt users to choose from a set of mutually-exclusive choices (Radio Button behavior).

The preview has been updated.

Checkboxes

Use with variant="multi-select" to prompt users to select more than one option (Checkbox behavior).

The preview has been updated.

With an Accordion

Refer to Accordion with skin="color-swatches" to wrap a large set of Color Swatches, to avoid making the content excessively tall.

Disabled

Use disabled on a ColorSwatch to prevent a color swatch from being selected. When a color swatch is temporarily unavailable or out of stock, to show that the option exists but cannot be selected at this time.

The preview has been updated.

With a Selection Set

The preview has been updated.

Accessibility

  • Use the accessibleText prop (for color-blind users) on each color swatch. Its value is a localized description of the color choice, such as accessibleText="Light Blue"

Content

Color value

Use one of the following format to input a color value for each swatch:

Background image

  • Use a square image for the backgroundImage property.

Label

  • Capitalize each word of a color name: Court Green, Oxford Blue, Tarmac Grey Heather.
  • In a two-tone swatch, separate the two color names with a slash: True Blue / White.
  • Localize each color name.

Remove color action

Use IconButton for actions that remove colors.

The preview has been updated.

Props

See core props for additional props that can be applied to each of these components. Each component also accepts the React-equivalent native HTML attributes of the element it renders, unless a listed prop replaces one or a note says otherwise.
ColorSwatches
Renders <div>.
proptyperequireddefaultdeprecation notes
size
The size of the color swatches
"standard""xlarge""large"⚠️ "super"null
false
standard
Deprecated values:
  • super: Use size="large" instead.
⚠️ Deprecated
labelPosition
Where to position the label tooltips relative to its swatch @deprecated Tooltip now automatically selects the optimal placement.
"left""right""bottom""top"null
false
top
Tooltip now automatically selects the optimal placement.
ColorSwatch
Renders <span>.
proptyperequireddefaultdeprecation notes
primaryColor
The main color of the swatch. Accepts a css color value. Passing `transparent` displays a custom checkerboard visual, when not used in a gradient.
ColorSwatchColornull
false
transparent
secondaryColor
The optional secondary color of the swatch. Accepts a css color value. Passing `transparent` displays a custom checkerboard visual, when not used in a gradient.
ColorSwatchColornull
false
null
tertiaryColor
The optional tertiary color of the swatch. Accepts a css color value. Passing `transparent` displays a custom checkerboard visual, when not used in a gradient.
ColorSwatchColornull
false
null
backgroundImage
URL for a background image for the swatch.
stringnull
false
null
disabled
Whether or not the underlying input for the swatch should be enabled.
booleannull
false
false
accessibleText
A text representation of the color value. Used in the hover tooltip and as a hidden label for accessibility
stringnull
false
null
⚠️ Deprecated
labelPosition
Where to position the label tooltip relative to the swatch. Overrides the position setting of the ColorSwatches component. @deprecated Tooltip now automatically selects the optimal placement.
"left""right""bottom""top"null
false
null
Tooltip now automatically selects the optimal placement.
gradient
Configures a gradient between the primary and secondary colors. By default shows the two colors stacked but separate
"linear""radial"null
false
null
Other components
These components have no props beyond core props and native HTML attributes.
ComponentRendersNotes
ColorSwatchesMore<span>

Related