sp-swatch-group

Examples API

Attributes and Properties #

Property Attribute Type Default Description border border SwatchBorder density density 'compact' | 'spacious' | undefined rounding rounding SwatchRounding selected selected string[] selects selects SwatchSelects shape shape SwatchShape

Slots #

Name Description default slot Swatch elements to manage as a group

Events #

Name Type Description change Event

Description #

An <sp-swatch-group> group is a grouping of <sp-swatch> elements that are related to each other.

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-group> via:

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

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

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

Sizes #

Extra Small
<sp-swatch-group size="xs">
    <sp-swatch color="var(--spectrum-gray-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-red-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-orange-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-yellow-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-chartreuse-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-celery-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-green-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-seafoam-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-blue-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-indigo-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-purple-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-fuchsia-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-magenta-500)"></sp-swatch>
</sp-swatch-group>
Small
<sp-swatch-group size="s">
    <sp-swatch color="var(--spectrum-gray-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-red-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-orange-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-yellow-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-chartreuse-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-celery-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-green-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-seafoam-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-blue-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-indigo-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-purple-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-fuchsia-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-magenta-500)"></sp-swatch>
</sp-swatch-group>
Medium
<sp-swatch-group size="m">
    <sp-swatch color="var(--spectrum-gray-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-red-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-orange-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-yellow-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-chartreuse-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-celery-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-green-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-seafoam-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-blue-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-indigo-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-purple-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-fuchsia-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-magenta-500)"></sp-swatch>
</sp-swatch-group>
Large
<sp-swatch-group size="l">
    <sp-swatch color="var(--spectrum-gray-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-red-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-orange-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-yellow-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-chartreuse-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-celery-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-green-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-seafoam-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-blue-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-indigo-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-purple-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-fuchsia-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-magenta-500)"></sp-swatch>
</sp-swatch-group>

Density #

The density attribute/property is not required and when applied accepts the values of compact or spacious.

Compact #

<sp-swatch-group density="compact">
    <sp-swatch color="var(--spectrum-blue-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-indigo-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-purple-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-fuchsia-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-magenta-500)"></sp-swatch>
</sp-swatch-group>

Spacious #

<sp-swatch-group density="spacious">
    <sp-swatch color="var(--spectrum-blue-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-indigo-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-purple-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-fuchsia-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-magenta-500)"></sp-swatch>
</sp-swatch-group>

Selection #

An <sp-swatch-group> element can carry a selection of a single swatch or of multiple swatches. Then the selects property is set to one of these values, the selected property will surface an array the represents the string values that have been selected in the UI.

When the value of selected is updated via user input, the change event will be dispatched on the <sp-swatch-group> element to announce that interaction. Calling preventDefault() on the chagne event will prevent both the <sp-swatch-group> and the <sp-swatch> that initiated the change interaction from updating their selected values.

The value of selected can also be provided directly from the <sp-swatch> children. Child <sp-swatch> elements with their own selected attribute will be gathered and merged with any other selection data on the <sp-swatch-group> parent to populate selected.

Single #

The selected property is always represented as an array, and as such an application leveraging an <sp-swatch-group> element can apply more than one selection, regardless of the vaue of selects, however all future interactions will force the interace to a single selection.

<sp-swatch-group
    selects="single"
    onchange="this.nextElementSibling.textContent = `Selected: ${JSON.stringify(this.selected, null, ' ')}`"
>
    <sp-swatch color="var(--spectrum-blue-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-indigo-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-purple-500)" selected></sp-swatch>
    <sp-swatch color="var(--spectrum-fuchsia-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-magenta-500)" selected></sp-swatch>
</sp-swatch-group>
<div>
    Selected: [ "var(--spectrum-purple-500)", "var(--spectrum-magenta-500)" ]
</div>

Multiple #

<sp-swatch> children of an <sp-swatch-group selects="mutiple"> parent will toggle their selection.

<sp-swatch-group
    selects="multiple"
    onchange="this.nextElementSibling.textContent = `Selected: ${JSON.stringify(this.selected, null, ' ')}`"
>
    <sp-swatch color="var(--spectrum-blue-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-indigo-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-purple-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-fuchsia-500)"></sp-swatch>
    <sp-swatch color="var(--spectrum-magenta-500)"></sp-swatch>
</sp-swatch-group>
<div>Selected: [ ]</div>

Value #

When available, the value of selected will be constructed from the value attributes/properties of the child <sp-swatch> elements. This can be useful when you would like the swatch data needs to correlate to a hash rather than the raw color string.

<sp-swatch-group
    selects="multiple"
    selected='["color-2"]'
    onchange="this.nextElementSibling.textContent = `Selected: ${JSON.stringify(this.selected, null, ' ')}`"
>
    <sp-swatch color="var(--spectrum-blue-500)" value="color-0"></sp-swatch>
    <sp-swatch
        color="var(--spectrum-indigo-500)"
        value="color-1"
        selected
    ></sp-swatch>
    <sp-swatch color="var(--spectrum-purple-500)" value="color-2"></sp-swatch>
    <sp-swatch
        color="var(--spectrum-fuchsia-500)"
        value="color-3"
        selected
    ></sp-swatch>
    <sp-swatch color="var(--spectrum-magenta-500)" value="color-4"></sp-swatch>
</sp-swatch-group>
<div>Selected: [ "color-2", "color-1", "color-3" ]</div>

Swatch modifying attributes #

An <sp-swatch-group> element can be modified by the following attributes/properties to customize its delivery as desired for your use case: border, disabled, mixedValue (accepted as the mixed-value attribute), nothing, rounding, shape, and size. Use these in concert with each other for a variety of final visual deliveries. Applying a value for one of these attributes/properties to an <sp-swatch-group> element will have it forward the value to all of the <sp-swatch> elements that are a direct child of the group, overriding any value that may be applied directly to those children.