XDS — Design System

CheckboxListItem@xds/core · XDSCheckboxListItem 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 {XDSCheckboxListItem} 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.

Showcase source

tsx
'use client';
import {useState} from 'react';
import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList';
export default function CheckboxListItemShowcase() {
  const [value, setValue] = useState<string[]>(['updates', 'security']);
  return (
    <XDSCheckboxList
      label="Email preferences"
      value={value}
      onChange={setValue}
      hasDividers>
      <XDSCheckboxListItem
        label="Product updates"
        value="updates"
        description="New features and improvements"
      />
      <XDSCheckboxListItem
        label="Security alerts"
        value="security"
        description="Important account security notifications"
      />
      <XDSCheckboxListItem
        label="Marketing"
        value="marketing"
        description="Tips, offers, and promotions"
      />
      <XDSCheckboxListItem
        label="Beta program"
        value="beta"
        description="Currently closed to new members"
        isDisabled
      />
    </XDSCheckboxList>
  );
}

Usage

import {XDSCheckboxListItem} 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.

tsx

'use client'; import {useState} from 'react'; import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList'; export default function CheckboxListItemShowcase() { const [value, setValue] = useState<string[]>(['updates', 'security']); return ( <XDSCheckboxList label="Email preferences" value={value} onChange={setValue} hasDividers> <XDSCheckboxListItem label="Product updates" value="updates" description="New features and improvements" /> <XDSCheckboxListItem label="Security alerts" value="security" description="Important account security notifications" /> <XDSCheckboxListItem label="Marketing" value="marketing" description="Tips, offers, and promotions" /> <XDSCheckboxListItem label="Beta program" value="beta" description="Currently closed to new members" isDisabled /> </XDSCheckboxList> ); }