@spectrum-web-components/swatch

Overview

An shows a small sample of a fill — such as a color, gradient, texture, or material — that is intended to be applied to an object.

$3


``bash
yarn add @spectrum-web-components/swatch
`

Import the side effectful registration of via:

`js
import '@spectrum-web-components/swatch/sp-swatch.js';
`

When looking to leverage the Swatch base class as a type and/or for extension purposes, do so via:

`js
import { Swatch } from '@spectrum-web-components/swatch';
`

$3

#### Sizes


Extra Small


`html







shape="rectangle"
color="rgb(255 0 0 / 0.7)"
size="xs"
>
shape="rectangle"
disabled
color="rgb(255 0 0 / 0.7)"
size="xs"
>
rounding="full"
shape="rectangle"
mixed-value
size="xs"
>

`


Small


`html







shape="rectangle"
color="rgb(255 0 0 / 0.7)"
size="s"
>
shape="rectangle"
disabled
color="rgb(255 0 0 / 0.7)"
size="s"
>
rounding="full"
shape="rectangle"
mixed-value
size="s"
>

`


Medium


`html







shape="rectangle"
color="rgb(255 0 0 / 0.7)"
size="m"
>
shape="rectangle"
disabled
color="rgb(255 0 0 / 0.7)"
size="m"
>
rounding="full"
shape="rectangle"
mixed-value
size="m"
>

`


Large


`html







shape="rectangle"
color="rgb(255 0 0 / 0.7)"
size="l"
>
shape="rectangle"
disabled
color="rgb(255 0 0 / 0.7)"
size="l"
>
rounding="full"
shape="rectangle"
mixed-value
size="l"
>

`

#### Variants

An element can be modified by the following attributes/properties to customize its delivery as desired for your use case: border, color, disabled, mixedValue (accepted as the mixed-value attribute), nothing, rounding, and shape. Use these in concert with each other for a variety of final visual deliveries.


Border


The border attribute/property is not required and when applied accepts the values of none or light.

`html





`


Color


The color attribute/property determines the color value that the element will deliver.

`html





`


Mixed Value


The mixed-value attribute and mixedValue property outline when an element represents more than one color.

`html





`

Please note that the aria-checked="mixed" value only applies when the swatch is in a group with selects="multiple"


Nothing


The nothing attribute/property outlines that the represents no color or that it represents "transparent".

`html





`


Rounding


The rounding attribute/property is not required and when applied accepts the values of none or full.

`html





`


Shape


The shape attribute/property is not required and when applied accepts the values of rectangle.

`html




`

$3

#### Disabled

The disabled attribute/property determines prevents interaction on the element.

`html





`

$3

#### Use the selects property for proper ARIA semantics

When swatches are intended to be selectable, set the selects property on to enable proper ARIA semantics:

- selects="single": Swatches have role="radio" and announce as radio buttons
- selects="multiple": Swatches have role="checkbox" and announce as checkboxes with checked/unchecked states

Without the selects property, swatches default to role="button" and the swatch-group stops propagation of change events, so selected and aria-pressed states won't update when clicked. This prevents screen readers from announcing selection state changes.

`html





`

#### Best practices

- Ensure swatches have sufficient color contrast for visibility.
- Verify that swatches are appropriately labeled for screen readers.
- Use the selects property when swatches represent a selection interface.

#### Keyboard navigation

- Tab: Move focus to the next focusable element
- Arrow keys: Navigate between swatches in the group and move the focus indicator
- Enter or Space`: Select the focused swatch