docs / core / toggle-chip
ToggleChip
pressable chips for choosing what a view shows, when a checkbox list is too heavy and a dropdown would hide the choices.
intensity · recedesrsc · client
provenance
authored in usvalayer
core / primitivesintensity
recedes · safe anywhere, including dense surfacescomposition
dashboard headers and filter rows, picking visible stats or panelssingle mode where a view must always have one panel selectednot a form field. submitting data is Checkbox or RadioGroupnot navigation between views. that is SegmentedControl or Tabsa11y
each chip is a button carryingaria-pressed · the group is a fieldset named by ariaLabel or a string label · no roving focus, chips sit in the normal Tab orderjest-axelive demo · try it out
customize
typemulti-select or one-of-many
labelmono eyebrow before the chips
minmultiple only. floor selection locks
maxmultiple only. ceiling selection locks
disabledthe fieldset disables every chip
usage
import { ToggleChip, ToggleChipGroup } from "@usva-ui/react/primitives/toggle-chip";
<ToggleChipGroup value={stats} onValueChange={setStats} label="Visible stats" min={2} max={4}>
<ToggleChip value="grade-avg">Grade avg.</ToggleChip>
<ToggleChip value="active-courses">Active courses</ToggleChip>
<ToggleChip value="credits-left">Credits left</ToggleChip>
</ToggleChipGroup>ToggleChipGroup
| prop | type | default | notes |
|---|---|---|---|
| type | "multiple" | "single" | "multiple" | single keeps exactly one chip pressed. the last chip cannot be deselected. |
| value | string | string[] | — | the pressed ids. controlled; there is no uncontrolled mode. |
| onValueChange | (value) => void | — | hands back a string[] in multiple mode, a bare id in single mode. |
| min | number | — | multiple only. selected chips lock once the count falls to it. |
| max | number | — | multiple only. unselected chips lock once the count reaches it. |
| label | ReactNode | — | mono eyebrow before the chips. names the group when it is a string. |
| ariaLabel | string | — | names the group when label is not a string. |
| disabled | boolean | false | the fieldset disables every chip at once. |
ToggleChip
| prop | type | default | notes |
|---|---|---|---|
| value | string | — | the chip's id. must be unique inside the group. |
| disabled | boolean | false | disables this chip on top of whatever the group decides. |
get it
bun add @usva-ui/reactusage
import { ToggleChip, ToggleChipGroup } from "@usva-ui/react/primitives/toggle-chip";
<ToggleChipGroup value={stats} onValueChange={setStats} min={2} max={4} ariaLabel="Visible stats">
<ToggleChip value="grade-avg">Grade avg.</ToggleChip>
<ToggleChip value="active-courses">Active courses</ToggleChip>
</ToggleChipGroup>