Swatch Group | Calcite Design System

Swatch Group provides consistent spacing, accessible keyboard navigation, and selection modes to multiple Swatches.

Overview

Swatch Group supports workflows and patterns using more than one Swatch. Use Swatch Group to facilitate selection, filtering, and toggling workflows.

Sample

Usage

Facilitate selection of colors or patterns
Filtering patterns
Toggling of categorical data

Best practices

Use Swatch Groups to enable users to select from multiple swatches. For display-only scenarios, use individual Swatches. When enabling selection, choose the selectionMode that best matches your workflow requirements.

Accessibility

Key	Function
`Tab`	Moves focus to the next `calcite-swatch`. If the current focus is the last `calcite-swatch`, focus will leave the component.
`Tab` and `Shift`	Moves focus to the previous `calcite-swatch`. If the current focus is the first `calcite-swatch`, focus will leave the component.
`Arrow left`	Moves focus to the previous `calcite-swatch`. If the current focus is the first `calcite-swatch`, focus will return to the last `calcite-swatch`.
`Arrow right`	Moves focus to the next `calcite-swatch`. If the current focus is the last `calcite-swatch`, focus will return to the first `calcite-swatch`.
`Space`	When `selectionMode` is not `"none"`, selects the focused `calcite-swatch`.
`Enter`	When `selectionMode` is not `"none"`, selects the focused `calcite-swatch`.
`Home`	Moves focus to the component's first `calcite-swatch`.
`End`	Moves focus to the component's last `calcite-swatch`.

API reference

Properties

Property	Attribute	Description	Type	Default
disabled	disabled	When `true`, interaction is prevented and the component is displayed with lower opacity.	`boolean`	`false`
labelrequired	label	Specifies an accessible label for the component.	`string`
scale	scale	Specifies the component's size. Child `calcite-swatch`s inherit the component's value.	`Scale`	`"m"`
selectedItemsread-only		Specifies the component's selected items.	`Swatch[]`
selectionMode	selection-mode	Specifies the selection mode of the component, where: `"multiple"` allows any number of selections, `"single"` allows only one selection, `"single-persist"` allows one selection and prevents de-selection, and `"none"` does not allow any selections.	`Extract<"multiple" \| "single" \| "single-persist" \| "none", SelectionMode>`	`"none"`

Slots

Name	Description
default (unnamed)	A slot for adding one or more `calcite-swatch`s.

Styles

Name	Description
--calcite-swatch-group-space	Specifies the space between slotted elements.

Events

Name	Description	Behavior
calciteSwatchGroupSelect	Fires when the component's selection changes.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component's first focusable element.	`setFocus(options?: FocusOptions): Promise<void>`