sp-swatch

NPM 1.0.1

View Storybook
Overview API Changelog

Description

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';

Sizes

Extra Small 
<div style="display: flex;gap: 5px;">
    <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>
</div>
 Small 
<div style="display: flex;gap: 5px;">
    <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>
</div>
 Medium 
<div style="display: flex;gap: 5px;">
    <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>
</div>
 Large 
<div style="display: flex;gap: 5px;">
    <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>
</div>

Modifying attributes

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

Disabled

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

<sp-swatch-group>
    <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>

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

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

Events

Name Type Description change Event

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)