ChipGroup
A labelled set of chips, announced as one group rather than as loose controls.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/controls/ChipGroup/ChipGroup.stories.tsxExport FiltersImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A labelled set of chips, announced as one group rather than as loose controls.
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { ChipGroup } from '@cloakedinc/design-system';ChipGroupChipGroupProps
packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx:24
| Prop | Type | Presence | Notes |
|---|---|---|---|
children | React.ReactNode | Required | `Chip` children. Keep them one kind: all selectable, or all removable. |
label | string | Required | Accessible name for the group, announced before its chips. |
scroll | boolean | undefined | Optional | Scrolls horizontally on one line instead of wrapping onto several. |
className | string | undefined | Optional | |
testId | string | undefined | Optional | Selector for the group wrapper. Chips derive nothing from it; give each `Chip` its own. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A labelled set of chips. Without a group, a row of chips reads to assistive technology as loose controls with no relationship, and every call site ends up re-inventing the row layout.
Keep one kind per group
Chips carry their affordance in their shape, so a group holding both a selectable chip and a removable one gives two different behaviors the same appearance.
A marker that does nothing is a Tag. Keep it outside the group.
Selection stays with the caller
The group holds no selected state. Each Chip takes its own selected and onPress, so single
selection and multiple selection both work without a second component.
Wrap or scroll
Wrapping is the default, and it is the right choice when the count comes from data. Reach for
scroll only when the set is known and short.
For a fixed set of five or fewer mutually exclusive view modes, use SegmentedControl instead. The
boundary is the shape of the set: a segmented control is fixed, connected, and equal-width, while a
chip group grows and wraps.
Do and don’t
| Guidance | Example |
|---|---|
| Do | Fill a group with selectable chips, or fill it with removable chips. |
| Don’t | Mix the two, or make only some of the chips interactive. |
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- root
- Label
- Root
- Description
- Group container that owns the accessible name and the row layout.
- Required
- true
- Id
- chips
- Label
- Chips
- Description
- One kind of Chip: all selectable, or all removable.
- Required
- true
Allowed Design Choices
- Variants
- Wrap
- Label
- Wrap
- Description
- Chips flow onto more lines as the set grows.
- Scroll
- Label
- Scroll
- Description
- Chips stay on one line and the row scrolls horizontally.
- Sizes
- Tones
Variants
- Id
- wrap
- Label
- Wrap
- Description
- Default. Chips wrap onto more lines.
- Platforms
- ios
- android
- web
- Id
- scroll
- Label
- Scroll
- Description
- One line with a hidden scrollbar, for a long known set.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- chip-gap
- Label
- Chip gap
- Kind
- exact
- Token
- --cds-space-8
- Value
- 8
- Unit
- px
- Applies To
- root
Layout
- Alignment
- Chips share a center line and read in source order.
- Flow
- A wrapping row by default, or one scrolling line when
scrollis set. - Notes
- Keep one kind of chip in a group. Mixing selectable and removable chips gives two different affordances the same shape.
- Use Tag for a marker that does nothing, and keep it outside the group.
- Use SegmentedControl instead for a fixed set of 5 or fewer mutually exclusive view modes.
Typography And Color
- Typography
- Label
- Inherited
- Description
- ChipGroup sets no type; its chips own their text. Ramp noted for parity.
- Token
- --cds-type-body-small-size
- Colors
- Label
- Transparent
- Description
- ChipGroup paints no background; the surface behind shows through.
- Token
- --cds-bg-page
States
- Id
- wrap
- Label
- Wrap
- Description
- Chips flow onto more lines.
- Id
- scroll
- Label
- Scroll
- Description
- Chips stay on one line and scroll.
Behavior
- Label
- Selection lives with the caller
- Description
- The group does not own selected state. Each Chip receives its own
selectedandonPress, so single and multiple selection both work without a second component.
- Label
- One kind per group
- Description
- Do not mix selectable and removable chips in one group, and do not make only some of them interactive.
Accessibility
- Label
- Group name
- Description
labelis required and becomes the group's accessible name, so the set is announced before its chips.
- Label
- Focus stops
- Description
- Each chip keeps its own focus stop. The group adds no tab stop of its own.
Content Adaptation
- Label
- Growing sets
- Description
- Prefer wrapping when the count comes from data. Reach for
scrollonly when the set is known and short.
Motion Haptics
- Motion
- Label
- No group motion
- Description
- Adding or removing a chip reflows the row without an entrance animation.
- Haptics
- Label
- Owned by the chip
- Description
- The group requests no haptics. Each Chip fires
selectionon press.