Chip Group | Calcite Design System

Chip Group provides consistent spacing, accessible keyboard navigation, and selection modes for multiple Chips.

Overview

Chip Group supports workflows and patterns using more than one Chip. Chips are predictably spaced within the Chip Group, and opt-in selection modes can facilitate workflows with interactive Chips.

Sample

Usage

Selection workflows
Filtering patterns
Toggling of categorical data

Best practices

Group related Chips for selection, filtering, or categorical data.
Keep groups concise to support usability and accessibility.

Recommendations

A Chip Group used to filter content by geometry style with All, Points, Lines, and Polygons as filter options.

Do use Chip Groups for single-selection categorical filtering.

Active hazards Chip Group with Flood and Landslide selected and Wildfire and Earthquake unselected.

Do use Chip Groups for multi-selection data filtering.

Terrain type Chip Group with a blue selected Urban Chip and neutral unselected Suburban, Rural, and Wild Chips.

Do use a Chip's kind and appearance properties to provide emphasis between selected and unselected Chips when appropriate.

Urban features Chip Group displaying 12 Chips.

Avoid displaying too many Chips at once, which creates visual clutter and makes scanning difficult.

Accessibility

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

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 size of the component. Child `calcite-chip`s inherit the component's value.	`Scale`	`"m"`
selectedItemsread-only		Specifies the component's selected items.	`Chip[]`
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-chip`s.

Events

Name	Description	Behavior
calciteChipGroupSelect	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>`