XDS — Design System

CheckboxList@xds/core v0.0.13 · XDSCheckboxList

Usage

CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox — like "I agree to the terms" — use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.

ts
import {XDSCheckboxList} from '@xds/core/CheckboxList'

Best practices

Guidance	Practices
Do	Keep the list short — three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.
Do	Turn on dividers (hasDividers) when items have helper text underneath — without them the labels and descriptions blur together.
Do	Write a group label that says what the choices represent — "Export formats" tells users more than "Options".
Don't	Show a CheckboxList when the user can only pick one thing — that is what RadioList is for.
Don't	Put buttons or links inside the trailing slot (endContent) — the whole row is already tappable, so a nested button creates two competing click targets.

Sub-components

CheckboxList is a compound component with 2 sub-components.

XDSCheckboxList

Checkbox group container with field integration for label, description, and status.

Prop	Type	Description
labelrequired	string	Label text for the checkbox group (always rendered for accessibility).
childrenrequired	ReactNode	XDSCheckboxListItem elements.
value	string[]	The currently selected values (collection mode).
onChange	(values: string[]) => void	Callback fired when the selected values change.
changeAction	(values: string[]) => void \| Promise<void>	Async action on change with optimistic updates.
isLoading	boolean (default: false)	External loading state.
isLabelHidden	boolean (default: false)	Whether to visually hide the label.
description	string	Description text displayed below the label.
density	'compact' \| 'balanced' \| 'spacious' (default: 'balanced')	Spacing density for list items.
hasDividers	boolean (default: false)	Whether to show dividers between items.
isDisabled	boolean (default: false)	Whether all checkbox items are disabled.
status	XDSInputStatus	Status indicator ({ type, message }).
xstyle	StyleXStyles	StyleX styles for layout customization. Must be a stylex.create() value.

XDSCheckboxListItem

Individual checkbox item with label, description, and end content slot. Works in collection mode (inside XDSCheckboxList) or standalone mode (inside XDSList).

Prop	Type	Description
labelrequired	string	Primary text label for the item.
value	string	Identity key (required inside XDSCheckboxList).
description	string	Secondary text below the label.
endContent	ReactNode	Content rendered after the label area.
isDisabled	boolean (default: false)	Whether this individual item is disabled.
isChecked	boolean \| 'indeterminate'	Direct checked state (standalone mode only).
onCheck	(checked: boolean) => void	Direct check handler (standalone mode only).

Examples

Common configurations, variations, and states.

CheckboxList — Select All With Indeterminate

CheckboxList — With End Content

Badges in the trailing slot show contextual info — like a price or status — next to each option without cluttering the label, so users can compare choices at a glance.

Usage

import {XDSCheckboxList} from '@xds/core/CheckboxList'

Best practices

Guidance	Practices
Do	Keep the list short — three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.
Do	Turn on dividers (hasDividers) when items have helper text underneath — without them the labels and descriptions blur together.
Do	Write a group label that says what the choices represent — "Export formats" tells users more than "Options".
Don't	Show a CheckboxList when the user can only pick one thing — that is what RadioList is for.
Don't	Put buttons or links inside the trailing slot (endContent) — the whole row is already tappable, so a nested button creates two competing click targets.

Prop

Type

Description

labelrequired

string

Label text for the checkbox group (always rendered for accessibility).

childrenrequired

ReactNode

XDSCheckboxListItem elements.

value

string[]

The currently selected values (collection mode).

onChange

(values: string[]) => void

Callback fired when the selected values change.

changeAction

(values: string[]) => void | Promise<void>

Async action on change with optimistic updates.

isLoading

boolean (default: false)

External loading state.

isLabelHidden

boolean (default: false)

Whether to visually hide the label.

description

string

Description text displayed below the label.

density

'compact' | 'balanced' | 'spacious' (default: 'balanced')

Spacing density for list items.

hasDividers

boolean (default: false)

Whether to show dividers between items.

isDisabled

boolean (default: false)

Whether all checkbox items are disabled.

status

XDSInputStatus

Status indicator ({ type, message }).

xstyle

StyleXStyles

StyleX styles for layout customization. Must be a stylex.create() value.

Prop

Type

Description

labelrequired

string

Primary text label for the item.

value

string

Identity key (required inside XDSCheckboxList).

description

string

Secondary text below the label.

endContent

ReactNode

Content rendered after the label area.

isDisabled

boolean (default: false)

Whether this individual item is disabled.

isChecked

boolean | 'indeterminate'

Direct checked state (standalone mode only).

onCheck

(checked: boolean) => void

Direct check handler (standalone mode only).