XDS — Design System

CheckboxList@xds/core · XDSCheckboxList v0.0.13

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 IndeterminateA

tsx
'use client';
import {useState} from 'react';
import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList';
import {XDSDivider} from '@xds/core/Divider';
const DOCUMENTS = [
  {id: 'transactions', label: 'Transaction history'},
  {id: 'statements', label: 'Account statements'},
  {id: 'tax', label: 'Tax documents'},
  {id: 'invoices', label: 'Invoices'},
];
const ALL_IDS = DOCUMENTS.map(d => d.id);
export default function CheckboxListSelectAllPattern() {
  const [selected, setSelected] = useState<string[]>(['transactions']);
  const allChecked = ALL_IDS.every(id => selected.includes(id));
  const noneChecked = selected.length === 0;
  const selectAllState = allChecked
    ? true
    : noneChecked
      ? false
      : ('indeterminate' as const);
  return (
    <XDSCheckboxList label="Include in export">
      <XDSCheckboxListItem
        label="Select all"
        isChecked={selectAllState}
        onCheck={checked => {
          setSelected(checked ? [...ALL_IDS] : []);
        }}
      />
      <XDSDivider />
      {DOCUMENTS.map(doc => (
        <XDSCheckboxListItem
          key={doc.id}
          label={doc.label}
          isChecked={selected.includes(doc.id)}
          onCheck={checked => {
            setSelected(prev =>
              checked ? [...prev, doc.id] : prev.filter(v => v !== doc.id),
            );
          }}
        />
      ))}
    </XDSCheckboxList>
  );
}

CheckboxList — With End ContentBadges 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.

tsx
'use client';
import {useState} from 'react';
import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList';
import {XDSBadge} from '@xds/core/Badge';
export default function CheckboxListWithEndContent() {
  const [value, setValue] = useState<string[]>(['free']);
  return (
    <XDSCheckboxList
      label="Add-on packages"
      value={value}
      onChange={setValue}
      hasDividers>
      <XDSCheckboxListItem
        label="Free tier"
        value="free"
        description="Basic features included"
        endContent={<XDSBadge variant="success" label="$0/mo" />}
      />
      <XDSCheckboxListItem
        label="Pro tier"
        value="pro"
        description="Advanced analytics and integrations"
        endContent={<XDSBadge variant="info" label="$9/mo" />}
      />
      <XDSCheckboxListItem
        label="Enterprise"
        value="enterprise"
        description="Custom solutions and dedicated support"
        endContent={<XDSBadge variant="purple" label="Custom" />}
      />
    </XDSCheckboxList>
  );
}

Showcase source

tsx
'use client';
import {useState} from 'react';
import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList';
export default function CheckboxListShowcase() {
  const [value, setValue] = useState<string[]>(['email']);
  return (
    <XDSCheckboxList
      label="Notification preferences"
      description="Choose how you would like to be notified"
      value={value}
      onChange={setValue}
      hasDividers>
      <XDSCheckboxListItem
        label="Email"
        value="email"
        description="Weekly digest every Monday"
      />
      <XDSCheckboxListItem
        label="Push notification"
        value="push"
        description="Instant alerts on your device"
      />
      <XDSCheckboxListItem
        label="SMS"
        value="sms"
        description="Standard messaging rates apply"
      />
    </XDSCheckboxList>
  );
}

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).

tsx

'use client'; import {useState} from 'react'; import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList'; import {XDSDivider} from '@xds/core/Divider'; const DOCUMENTS = [ {id: 'transactions', label: 'Transaction history'}, {id: 'statements', label: 'Account statements'}, {id: 'tax', label: 'Tax documents'}, {id: 'invoices', label: 'Invoices'}, ]; const ALL_IDS = DOCUMENTS.map(d => d.id); export default function CheckboxListSelectAllPattern() { const [selected, setSelected] = useState<string[]>(['transactions']); const allChecked = ALL_IDS.every(id => selected.includes(id)); const noneChecked = selected.length === 0; const selectAllState = allChecked ? true : noneChecked ? false : ('indeterminate' as const); return ( <XDSCheckboxList label="Include in export"> <XDSCheckboxListItem label="Select all" isChecked={selectAllState} onCheck={checked => { setSelected(checked ? [...ALL_IDS] : []); }} /> <XDSDivider /> {DOCUMENTS.map(doc => ( <XDSCheckboxListItem key={doc.id} label={doc.label} isChecked={selected.includes(doc.id)} onCheck={checked => { setSelected(prev => checked ? [...prev, doc.id] : prev.filter(v => v !== doc.id), ); }} /> ))} </XDSCheckboxList> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList'; import {XDSBadge} from '@xds/core/Badge'; export default function CheckboxListWithEndContent() { const [value, setValue] = useState<string[]>(['free']); return ( <XDSCheckboxList label="Add-on packages" value={value} onChange={setValue} hasDividers> <XDSCheckboxListItem label="Free tier" value="free" description="Basic features included" endContent={<XDSBadge variant="success" label="$0/mo" />} /> <XDSCheckboxListItem label="Pro tier" value="pro" description="Advanced analytics and integrations" endContent={<XDSBadge variant="info" label="$9/mo" />} /> <XDSCheckboxListItem label="Enterprise" value="enterprise" description="Custom solutions and dedicated support" endContent={<XDSBadge variant="purple" label="Custom" />} /> </XDSCheckboxList> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList'; export default function CheckboxListShowcase() { const [value, setValue] = useState<string[]>(['email']); return ( <XDSCheckboxList label="Notification preferences" description="Choose how you would like to be notified" value={value} onChange={setValue} hasDividers> <XDSCheckboxListItem label="Email" value="email" description="Weekly digest every Monday" /> <XDSCheckboxListItem label="Push notification" value="push" description="Instant alerts on your device" /> <XDSCheckboxListItem label="SMS" value="sms" description="Standard messaging rates apply" /> </XDSCheckboxList> ); }