sp-swatch

NPM 1.11.2

View Storybook
Overview API Changelog

Overview

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

Usage

See it on NPM! How big is this package in your project?

yarn add @spectrum-web-components/swatch

Import the side effectful registration of <sp-swatch> via:

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:

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

Options

Sizes

Extra Small 
<sp-swatch-group selects="multiple">
  <sp-swatch color="rgb(255 0 0 / 0.7)" size="xs"></sp-swatch>
  <sp-swatch rounding="none" color="rgb(255 0 0 / 0.7)" size="xs"></sp-swatch>
  <sp-swatch rounding="full" color="rgb(255 0 0 / 0.7)" size="xs"></sp-swatch>
  <sp-swatch border="light" color="rgb(255 0 0 / 0.7)" size="xs"></sp-swatch>
  <sp-swatch border="none" color="rgb(255 0 0 / 0.7)" size="xs"></sp-swatch>
  <sp-swatch nothing size="xs"></sp-swatch>
  <sp-swatch shape="rectangle" color="rgb(255 0 0 / 0.7)" size="xs"></sp-swatch>
  <sp-swatch
    shape="rectangle"
    disabled
    color="rgb(255 0 0 / 0.7)"
    size="xs"
  ></sp-swatch>
  <sp-swatch
    rounding="full"
    shape="rectangle"
    mixed-value
    size="xs"
  ></sp-swatch>
</sp-swatch-group>
 Small 
<sp-swatch-group selects="multiple">
  <sp-swatch color="rgb(255 0 0 / 0.7)" size="s"></sp-swatch>
  <sp-swatch rounding="none" color="rgb(255 0 0 / 0.7)" size="s"></sp-swatch>
  <sp-swatch rounding="full" color="rgb(255 0 0 / 0.7)" size="s"></sp-swatch>
  <sp-swatch border="light" color="rgb(255 0 0 / 0.7)" size="s"></sp-swatch>
  <sp-swatch border="none" color="rgb(255 0 0 / 0.7)" size="s"></sp-swatch>
  <sp-swatch nothing size="s"></sp-swatch>
  <sp-swatch shape="rectangle" color="rgb(255 0 0 / 0.7)" size="s"></sp-swatch>
  <sp-swatch
    shape="rectangle"
    disabled
    color="rgb(255 0 0 / 0.7)"
    size="s"
  ></sp-swatch>
  <sp-swatch rounding="full" shape="rectangle" mixed-value size="s"></sp-swatch>
</sp-swatch-group>
 Medium 
<sp-swatch-group selects="multiple">
  <sp-swatch color="rgb(255 0 0 / 0.7)" size="m"></sp-swatch>
  <sp-swatch rounding="none" color="rgb(255 0 0 / 0.7)" size="m"></sp-swatch>
  <sp-swatch rounding="full" color="rgb(255 0 0 / 0.7)" size="m"></sp-swatch>
  <sp-swatch border="light" color="rgb(255 0 0 / 0.7)" size="m"></sp-swatch>
  <sp-swatch border="none" color="rgb(255 0 0 / 0.7)" size="m"></sp-swatch>
  <sp-swatch nothing size="m"></sp-swatch>
  <sp-swatch shape="rectangle" color="rgb(255 0 0 / 0.7)" size="m"></sp-swatch>
  <sp-swatch
    shape="rectangle"
    disabled
    color="rgb(255 0 0 / 0.7)"
    size="m"
  ></sp-swatch>
  <sp-swatch rounding="full" shape="rectangle" mixed-value size="m"></sp-swatch>
</sp-swatch-group>
 Large 
<sp-swatch-group selects="multiple">
  <sp-swatch color="rgb(255 0 0 / 0.7)" size="l"></sp-swatch>
  <sp-swatch rounding="none" color="rgb(255 0 0 / 0.7)" size="l"></sp-swatch>
  <sp-swatch rounding="full" color="rgb(255 0 0 / 0.7)" size="l"></sp-swatch>
  <sp-swatch border="light" color="rgb(255 0 0 / 0.7)" size="l"></sp-swatch>
  <sp-swatch border="none" color="rgb(255 0 0 / 0.7)" size="l"></sp-swatch>
  <sp-swatch nothing size="l"></sp-swatch>
  <sp-swatch shape="rectangle" color="rgb(255 0 0 / 0.7)" size="l"></sp-swatch>
  <sp-swatch
    shape="rectangle"
    disabled
    color="rgb(255 0 0 / 0.7)"
    size="l"
  ></sp-swatch>
  <sp-swatch rounding="full" shape="rectangle" mixed-value size="l"></sp-swatch>
</sp-swatch-group>

Variants

An <sp-swatch> 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.

<sp-swatch-group selects="multiple">
  <sp-swatch color="rgb(255 0 0 / 0.7)"></sp-swatch>
  <sp-swatch color="rgb(255 0 0 / 0.7)" border="light"></sp-swatch>
  <sp-swatch color="rgb(255 0 0 / 0.7)" border="none"></sp-swatch>
</sp-swatch-group>
 Color

The color attribute/property determines the color value that the <sp-swatch> element will deliver.

<sp-swatch-group selects="multiple">
  <sp-swatch color="rgb(255 0 0 / 0.7)"></sp-swatch>
  <sp-swatch color="orange"></sp-swatch>
  <sp-swatch color="var(--spectrum-magenta-500)"></sp-swatch>
</sp-swatch-group>
 Mixed Value

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

<sp-swatch-group selects="multiple">
  <sp-swatch mixed-value></sp-swatch>
  <sp-swatch mixed-value rounding="full"></sp-swatch>
  <sp-swatch mixed-value shape="rectangle"></sp-swatch>
</sp-swatch-group>

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 <sp-swatch> represents no color or that it represents "transparent".

<sp-swatch-group selects="multiple">
  <sp-swatch nothing></sp-swatch>
  <sp-swatch nothing rounding="full"></sp-swatch>
  <sp-swatch nothing shape="rectangle"></sp-swatch>
</sp-swatch-group>
 Rounding

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

<sp-swatch-group selects="multiple">
  <sp-swatch color="rgb(255 0 0 / 0.7)"></sp-swatch>
  <sp-swatch color="rgb(255 0 0 / 0.7)" rounding="none"></sp-swatch>
  <sp-swatch color="rgb(255 0 0 / 0.7)" rounding="full"></sp-swatch>
</sp-swatch-group>
 Shape

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

<sp-swatch-group selects="multiple">
  <sp-swatch color="rgb(255 0 0 / 0.7)"></sp-swatch>
  <sp-swatch color="rgb(255 0 0 / 0.7)" shape="rectangle"></sp-swatch>
</sp-swatch-group>

States

Disabled

The disabled attribute/property determines prevents interaction on the <sp-swatch> element.

<sp-swatch-group selects="multiple">
  <sp-swatch disabled color="rgb(255 0 0 / 0.7)"></sp-swatch>
  <sp-swatch disabled color="orange"></sp-swatch>
  <sp-swatch disabled color="var(--spectrum-magenta-500)"></sp-swatch>
</sp-swatch-group>

Accessibility

Use the selects property for proper ARIA semantics

When swatches are intended to be selectable, set the selects property on <sp-swatch-group> 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.

<!-- Correct: selects property enables proper selection semantics -->
<sp-swatch-group selects="multiple" aria-label="Select colors">
  <sp-swatch color="red" label="Red"></sp-swatch>
  <sp-swatch color="blue" label="Blue"></sp-swatch>
</sp-swatch-group>

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

Attributes and Properties

Property Attribute Type Default Description border border SwatchBorder color color string '' disabled disabled boolean false Disable this control. It will not receive focus or events label label string '' mixedValue mixed-value boolean false nothing nothing boolean false role role string 'button' rounding rounding SwatchRounding selected selected boolean false shape shape SwatchShape tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property value value string

Events

Name Type Description change Event

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.11.2
    • @spectrum-web-components/shared@1.11.2
    • @spectrum-web-components/reactive-controllers@1.11.2
    • @spectrum-web-components/icon@1.11.2
    • @spectrum-web-components/icons-ui@1.11.2
    • @spectrum-web-components/opacity-checkerboard@1.11.2

1.11.1

Patch Changes

  • Updated dependencies [95e1c25]:
    • @spectrum-web-components/shared@1.11.1
    • @spectrum-web-components/base@1.11.1
    • @spectrum-web-components/icon@1.11.1
    • @spectrum-web-components/icons-ui@1.11.1
    • @spectrum-web-components/opacity-checkerboard@1.11.1
    • @spectrum-web-components/reactive-controllers@1.11.1

1.11.0

Patch Changes

  • Updated dependencies [b95e254, f8bdeec, 9cb816b]:
    • @spectrum-web-components/reactive-controllers@1.11.0
    • @spectrum-web-components/shared@1.11.0
    • @spectrum-web-components/base@1.11.0
    • @spectrum-web-components/icon@1.11.0
    • @spectrum-web-components/icons-ui@1.11.0
    • @spectrum-web-components/opacity-checkerboard@1.11.0

1.10.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.10.0
    • @spectrum-web-components/icon@1.10.0
    • @spectrum-web-components/icons-ui@1.10.0
    • @spectrum-web-components/opacity-checkerboard@1.10.0
    • @spectrum-web-components/shared@1.10.0
    • @spectrum-web-components/reactive-controllers@1.10.0

1.9.1

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/icon@1.9.1
    • @spectrum-web-components/icons-ui@1.9.1
    • @spectrum-web-components/base@1.9.1
    • @spectrum-web-components/opacity-checkerboard@1.9.1
    • @spectrum-web-components/reactive-controllers@1.9.1
    • @spectrum-web-components/shared@1.9.1

1.9.0

Patch Changes

  • Updated dependencies [7d23140]:
    • @spectrum-web-components/reactive-controllers@1.9.0
    • @spectrum-web-components/icon@1.9.0
    • @spectrum-web-components/icons-ui@1.9.0
    • @spectrum-web-components/base@1.9.0
    • @spectrum-web-components/opacity-checkerboard@1.9.0
    • @spectrum-web-components/shared@1.9.0

1.8.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/icon@1.8.0
    • @spectrum-web-components/icons-ui@1.8.0
    • @spectrum-web-components/base@1.8.0
    • @spectrum-web-components/opacity-checkerboard@1.8.0
    • @spectrum-web-components/reactive-controllers@1.8.0
    • @spectrum-web-components/shared@1.8.0

1.7.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/icon@1.7.0
    • @spectrum-web-components/icons-ui@1.7.0
    • @spectrum-web-components/base@1.7.0
    • @spectrum-web-components/opacity-checkerboard@1.7.0
    • @spectrum-web-components/reactive-controllers@1.7.0
    • @spectrum-web-components/shared@1.7.0

1.6.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/icon@1.6.0
    • @spectrum-web-components/icons-ui@1.6.0
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/opacity-checkerboard@1.6.0
    • @spectrum-web-components/reactive-controllers@1.6.0
    • @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/icon@1.5.0
    • @spectrum-web-components/icons-ui@1.5.0
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/opacity-checkerboard@1.5.0
    • @spectrum-web-components/reactive-controllers@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/icon@1.4.0
    • @spectrum-web-components/icons-ui@1.4.0
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/opacity-checkerboard@1.4.0
    • @spectrum-web-components/reactive-controllers@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies [ea38ef0]:
    • @spectrum-web-components/reactive-controllers@1.3.0
    • @spectrum-web-components/icon@1.3.0
    • @spectrum-web-components/icons-ui@1.3.0
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/opacity-checkerboard@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Features

  • reactive-controllers: Migrate to Colorjs from Tinycolor (#4713) (9d740f0)

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/swatch

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/swatch

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.3 (2024-12-09)

Note: Version bump only for package @spectrum-web-components/swatch

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/swatch

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/swatch

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/swatch

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/swatch

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/swatch

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/swatch

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/swatch

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/swatch

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/swatch

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/swatch

0.44.0 (2024-07-15)

0.43.0 (2024-06-11)

Bug Fixes

  • swatch: sync aria-label with changes in label, color, and mixed state (#4519) (50aef31)

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/swatch

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/swatch

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/swatch

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/swatch

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/swatch

0.42.0 (2024-03-19)

Bug Fixes

  • styles, theme: surface exports that omit Spectrum Vars proactively (#4142) (5b524c1)
  • swatch: allow Swatch Group to manage selection through multiple slots (f333379)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/swatch

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/swatch

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/swatch

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/swatch

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/swatch

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/swatch

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/swatch

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/swatch

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/swatch

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/swatch

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/swatch

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/swatch

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/swatch

0.39.0 (2023-09-25)

Bug Fixes

  • alert-dialog: add Alert Dialog package (#3501) (1062847)
  • color-handle,color-loupe,swatch,thumbnail: use the Opacity Checkerboard package (47e1fc4)

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/swatch

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/swatch

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/swatch

0.35.0 (2023-07-31)

Bug Fixes

  • swatch: clear previously selected children when updating selected (ce1bd36)
  • swatch: warn when mixed-value used with selects !== 'multiple' (#3460) (89c288e)

0.34.0 (2023-07-11)

Bug Fixes

  • swatch: mixed-value state must be conveyed to screen readers using ARIA (#3330) (7711264)

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/swatch

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/swatch

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/swatch

0.31.0 (2023-05-17)

Bug Fixes

  • shared: allow "disabled" first to return to "tabindex=0" in "focusable" (160bc59)

0.30.0 (2023-05-03)

Bug Fixes

  • include all dependencies (c80d244)
  • support non-flat "color" application (efc0159)
  • swatch: normalize repeat selection of same item in "selects=single" (ee0fb0c)

Features

  • add swatch pattern (0cdc04b)
  • include all Dev Mode files in side effects (f70817c)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • swatch: use core tokens (821aebe)

0.3.10 (2023-04-24)

Bug Fixes

  • support non-flat "color" application (efc0159)

0.3.9 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/swatch

0.3.8 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/swatch

0.3.7 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/swatch

0.3.6 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/swatch

0.3.5 (2023-01-23)

Bug Fixes

  • swatch: normalize repeat selection of same item in "selects=single" (ee0fb0c)

0.3.4 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/swatch

0.3.3 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/swatch

0.3.2 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/swatch

0.3.1 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/swatch

0.3.0 (2022-10-28)

Features

  • swatch: use core tokens (821aebe)

0.2.2 (2022-10-17)

Note: Version bump only for package @spectrum-web-components/swatch

0.2.1 (2022-10-10)

Note: Version bump only for package @spectrum-web-components/swatch

0.2.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.1.3 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/swatch

0.1.2 (2022-07-20)

Bug Fixes

  • include all dependencies (c80d244)

0.1.1 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/swatch

0.1.0 (2022-06-29)

Features

  • add swatch pattern (0cdc04b)