Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat: XDSCheckboxList + XDSCheckboxListItem (#1127) (#1133)

Cindy Zhange71a59b71090
diff --git a/apps/storybook/stories/CheckboxList.stories.tsx b/apps/storybook/stories/CheckboxList.stories.tsx
new file mode 100644
index 0000000000..bbd6b7ebb9
--- /dev/null
+++ b/apps/storybook/stories/CheckboxList.stories.tsx
@@ -0,0 +1,416 @@
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList';
+import {XDSList} from '@xds/core/List';
+import {XDSCard} from '@xds/core/Card';
+
+const meta: Meta<typeof XDSCheckboxList> = {
+ title: 'Form/XDSCheckboxList',
+ component: XDSCheckboxList,
+ tags: ['autodocs'],
+ argTypes: {
+ label: {
+ control: 'text',
+ description: 'Label text (required)',
+ },
+ isLabelHidden: {
+ control: 'boolean',
+ description:
+ 'Visually hide the label (still accessible to screen readers)',
+ },
+ description: {
+ control: 'text',
+ description: 'Description text displayed below the label',
+ },
+ density: {
+ control: 'select',
+ options: ['compact', 'balanced', 'spacious'],
+ description: 'Spacing density for list items',
+ },
+ hasDividers: {
+ control: 'boolean',
+ description: 'Whether to show dividers between items',
+ },
+ isDisabled: {
+ control: 'boolean',
+ description: 'Whether all checkbox items are disabled',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSCheckboxList>;
+
+export const Default: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>(args.value ?? []);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+ <XDSCheckboxListItem label="Push notification" value="push" />
+ </XDSCheckboxList>
+ );
+ },
+ args: {
+ label: 'Notification preferences',
+ },
+};
+
+export const WithDescriptions: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>(args.value ?? []);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>
+ <XDSCheckboxListItem
+ label="Email"
+ value="email"
+ description="Receive notifications via email"
+ />
+ <XDSCheckboxListItem
+ label="SMS"
+ value="sms"
+ description="Standard messaging rates apply"
+ />
+ <XDSCheckboxListItem
+ label="Push notification"
+ value="push"
+ description="Instant alerts on your device"
+ />
+ </XDSCheckboxList>
+ );
+ },
+ args: {
+ label: 'Notification preferences',
+ description: 'Choose how you would like to be notified',
+ hasDividers: true,
+ },
+};
+
+export const DynamicItems: Story = {
+ render: args => {
+ const items = [
+ {id: 'react', label: 'React'},
+ {id: 'vue', label: 'Vue'},
+ {id: 'angular', label: 'Angular'},
+ {id: 'svelte', label: 'Svelte'},
+ ];
+ const [value, setValue] = useState<string[]>(['react']);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>
+ {items.map(item => (
+ <XDSCheckboxListItem
+ key={item.id}
+ label={item.label}
+ value={item.id}
+ />
+ ))}
+ </XDSCheckboxList>
+ );
+ },
+ args: {
+ label: 'Frameworks',
+ },
+};
+
+export const StandaloneMode: Story = {
+ render: () => {
+ const [accepted, setAccepted] = useState(false);
+ const [subscribed, setSubscribed] = useState(true);
+ const [marketing, setMarketing] = useState(false);
+ return (
+ <XDSList>
+ <XDSCheckboxListItem
+ label="Accept terms and conditions"
+ isChecked={accepted}
+ onCheck={setAccepted}
+ />
+ <XDSCheckboxListItem
+ label="Subscribe to newsletter"
+ description="Weekly updates about new features"
+ isChecked={subscribed}
+ onCheck={setSubscribed}
+ />
+ <XDSCheckboxListItem
+ label="Receive marketing emails"
+ isChecked={marketing}
+ onCheck={setMarketing}
+ />
+ </XDSList>
+ );
+ },
+};
+
+export const ReadOnly: Story = {
+ render: () => (
+ <XDSList>
+ <XDSCheckboxListItem label="Completed task" isChecked={true} />
+ <XDSCheckboxListItem label="Pending task" isChecked={false} />
+ <XDSCheckboxListItem label="In progress" isChecked="indeterminate" />
+ </XDSList>
+ ),
+};
+
+export const SelectAllWithIndeterminate: Story = {
+ render: () => {
+ const allItems = ['email', 'sms', 'push'];
+ const [selected, setSelected] = useState<string[]>(['email']);
+
+ const allChecked = allItems.every(item => selected.includes(item));
+ const noneChecked = selected.length === 0;
+ const selectAllState = allChecked
+ ? true
+ : noneChecked
+ ? false
+ : ('indeterminate' as const);
+
+ const handleSelectAll = (checked: boolean) => {
+ if (checked) {
+ setSelected([...allItems]);
+ } else {
+ setSelected([]);
+ }
+ };
+
+ return (
+ <XDSCheckboxList label="Notifications" hasDividers>
+ <XDSCheckboxListItem
+ label="Select all"
+ isChecked={selectAllState}
+ onCheck={handleSelectAll}
+ />
+ {allItems.map(item => (
+ <XDSCheckboxListItem
+ key={item}
+ label={item.charAt(0).toUpperCase() + item.slice(1)}
+ isChecked={selected.includes(item)}
+ onCheck={checked => {
+ setSelected(prev =>
+ checked ? [...prev, item] : prev.filter(v => v !== item),
+ );
+ }}
+ />
+ ))}
+ </XDSCheckboxList>
+ );
+ },
+};
+
+export const Disabled: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>(['email']);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+ <XDSCheckboxListItem label="Push notification" value="push" />
+ </XDSCheckboxList>
+ );
+ },
+ args: {
+ label: 'Notification preferences',
+ isDisabled: true,
+ },
+};
+
+export const DisabledItem: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>([]);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" isDisabled />
+ <XDSCheckboxListItem label="Push notification" value="push" />
+ </XDSCheckboxList>
+ );
+ },
+ args: {
+ label: 'Notification preferences',
+ },
+};
+
+export const WithErrorStatus: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>([]);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+ <XDSCheckboxListItem label="Push notification" value="push" />
+ </XDSCheckboxList>
+ );
+ },
+ args: {
+ label: 'Notification preferences',
+ status: {
+ type: 'error',
+ message: 'Please select at least one notification method',
+ },
+ },
+};
+
+export const WithEndContent: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>(['free']);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>
+ <XDSCheckboxListItem
+ label="Free tier"
+ value="free"
+ description="Basic features included"
+ endContent={<span style={{color: '#0D8626'}}>$0/mo</span>}
+ />
+ <XDSCheckboxListItem
+ label="Pro tier"
+ value="pro"
+ description="Advanced features"
+ endContent={<span style={{color: '#0064E0'}}>$9/mo</span>}
+ />
+ <XDSCheckboxListItem
+ label="Enterprise"
+ value="enterprise"
+ description="Custom solutions"
+ endContent={<span style={{color: '#5B08D8'}}>Custom</span>}
+ />
+ </XDSCheckboxList>
+ );
+ },
+ args: {
+ label: 'Add-on packages',
+ hasDividers: true,
+ },
+};
+
+export const AllVariations: Story = {
+ render: () => {
+ const [value1, setValue1] = useState<string[]>([]);
+ const [value2, setValue2] = useState<string[]>(['email']);
+ const [standalone1, setStandalone1] = useState(false);
+ const [standalone2, setStandalone2] = useState(true);
+ return (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '24px',
+ maxWidth: '400px',
+ }}>
+ <XDSCheckboxList label="Unselected" value={value1} onChange={setValue1}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+ </XDSCheckboxList>
+ <XDSCheckboxList
+ label="Pre-selected"
+ value={value2}
+ onChange={setValue2}>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+ </XDSCheckboxList>
+ <XDSCheckboxList
+ label="Disabled group"
+ value={['a']}
+ onChange={() => {}}
+ isDisabled>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+ </XDSCheckboxList>
+ <XDSCheckboxList
+ label="With descriptions"
+ value={value1}
+ onChange={setValue1}
+ hasDividers>
+ <XDSCheckboxListItem
+ label="Email"
+ value="email"
+ description="Delivered to your inbox"
+ />
+ <XDSCheckboxListItem
+ label="SMS"
+ value="sms"
+ description="Standard rates apply"
+ />
+ </XDSCheckboxList>
+ <XDSCheckboxList
+ label="With error"
+ value={[]}
+ onChange={() => {}}
+ status={{
+ type: 'error',
+ message: 'Please select at least one option',
+ }}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+ </XDSCheckboxList>
+ <div>
+ <h4 style={{margin: '0 0 8px'}}>Standalone mode</h4>
+ <XDSList>
+ <XDSCheckboxListItem
+ label="Accept terms"
+ isChecked={standalone1}
+ onCheck={setStandalone1}
+ />
+ <XDSCheckboxListItem
+ label="Subscribe"
+ isChecked={standalone2}
+ onCheck={setStandalone2}
+ />
+ </XDSList>
+ </div>
+ </div>
+ );
+ },
+};
+
+export const InsideCard: Story = {
+ render() {
+ const [selected, setSelected] = useState<string[]>(['email']);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSCard>
+ <XDSCheckboxList
+ label="Notifications"
+ description="Choose how to be notified"
+ value={selected}
+ onChange={setSelected}>
+ <XDSCheckboxListItem
+ value="email"
+ label="Email"
+ description="Weekly digest"
+ />
+ <XDSCheckboxListItem value="push" label="Push notifications" />
+ <XDSCheckboxListItem value="sms" label="SMS" isDisabled />
+ </XDSCheckboxList>
+ </XDSCard>
+ </div>
+ );
+ },
+};
+
+export const InsideCardWithDividers: Story = {
+ render() {
+ const [selected, setSelected] = useState<string[]>(['admin']);
+ return (
+ <div style={{maxWidth: 400}}>
+ <XDSCard>
+ <XDSCheckboxList
+ label="Assign Roles"
+ value={selected}
+ onChange={setSelected}
+ hasDividers>
+ <XDSCheckboxListItem value="admin" label="Admin" />
+ <XDSCheckboxListItem value="editor" label="Editor" />
+ <XDSCheckboxListItem value="viewer" label="Viewer" />
+ <XDSCheckboxListItem value="guest" label="Guest" />
+ </XDSCheckboxList>
+ </XDSCard>
+ </div>
+ );
+ },
+};
diff --git a/packages/core/package.json b/packages/core/package.json
index c5afc03800..018897e28c 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -94,6 +94,12 @@
"import": "./dist/CheckboxInput/index.mjs",
"require": "./dist/CheckboxInput/index.js"
},
+ "./CheckboxList": {
+ "source": "./src/CheckboxList/index.ts",
+ "types": "./dist/CheckboxList/index.d.ts",
+ "import": "./dist/CheckboxList/index.mjs",
+ "require": "./dist/CheckboxList/index.js"
+ },
"./CodeBlock": {
"source": "./src/CodeBlock/index.ts",
"types": "./dist/CodeBlock/index.d.ts",
diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
index a1be6b22b0..7046cc4603 100644
--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
@@ -130,16 +130,15 @@ const styles = stylex.create({
'@media (hover: hover)': colorVars['--color-border'],
},
},
+ },
+ checkboxDisabledUnchecked: {
backgroundColor: {
- default: 'unset',
+ default: colorVars['--color-background-muted'],
[stylex.when.ancestor(':hover')]: {
- '@media (hover: hover)': 'unset',
+ '@media (hover: hover)': colorVars['--color-background-muted'],
},
},
},
- checkboxDisabledUnchecked: {
- backgroundColor: colorVars['--color-background-muted'],
- },
checkmark: {
display: 'none',
color: colorVars['--color-on-accent'],
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
new file mode 100644
index 0000000000..565e3c6b29
--- /dev/null
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -0,0 +1,576 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CheckboxList',
+ description:
+ 'A checkbox group component for multi-value selection from a list of options. Supports collection mode (parent-managed state) and standalone mode (per-item state).',
+ keywords: ["checkboxlist","checkbox","checkboxgroup","multichoice","multiselect","checklist"],
+ features: [
+ 'Accessible — uses native <input type="checkbox"> with proper ARIA attributes',
+ 'Collection mode — parent manages selected values as string[], items derive checked state',
+ 'Standalone mode — individual items use isChecked/onCheck for independent control',
+ 'Density — compact, balanced, spacious via XDSList integration',
+ 'Dividers — optional border dividers between items',
+ 'Indeterminate — supports three-state checkbox (true, false, indeterminate) in standalone mode',
+ 'Descriptions — optional secondary text per item',
+ 'End content — slot for badges, actions, or other content after the label',
+ 'Disabled state — supports disabling the entire group or individual items',
+ 'Async actions — onChangeAction with optimistic updates and busy state',
+ 'Full-row click — clicking anywhere on the row toggles the checkbox',
+ 'Field integration — uses XDSField for label, description, and status messaging',
+ ],
+ examples: [
+ {
+ label: 'Basic collection mode',
+ code: `<XDSCheckboxList
+ label="Notifications"
+ value={selected}
+ onChange={setSelected}
+>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+ <XDSCheckboxListItem label="Push" value="push" />
+</XDSCheckboxList>`,
+ },
+ {
+ label: 'With descriptions',
+ code: `<XDSCheckboxList
+ label="Preferences"
+ value={selected}
+ onChange={setSelected}
+ hasDividers
+>
+ <XDSCheckboxListItem
+ label="Email"
+ value="email"
+ description="Receive notifications via email"
+ />
+ <XDSCheckboxListItem
+ label="SMS"
+ value="sms"
+ description="Standard messaging rates apply"
+ />
+</XDSCheckboxList>`,
+ },
+ {
+ label: 'Standalone mode',
+ code: `<XDSList>
+ <XDSCheckboxListItem
+ label="Accept terms"
+ isChecked={accepted}
+ onCheck={setAccepted}
+ />
+ <XDSCheckboxListItem
+ label="Subscribe to newsletter"
+ isChecked={subscribed}
+ onCheck={setSubscribed}
+ />
+</XDSList>`,
+ },
+ {
+ label: 'With status',
+ code: `<XDSCheckboxList
+ label="Required selections"
+ value={selected}
+ onChange={setSelected}
+ status={{ type: 'error', message: 'Please select at least one option' }}
+>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+</XDSCheckboxList>`,
+ },
+ {
+ label: 'Disabled group',
+ code: `<XDSCheckboxList
+ label="Locked selections"
+ value={['email']}
+ onChange={() => {}}
+ isDisabled
+>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+</XDSCheckboxList>`,
+ },
+ ],
+ theming: {
+ targets: [
+ {className: 'xds-checkbox-list-item'},
+ ],
+ },
+ notes: [
+ 'XDSCheckboxList composes XDSField (label, description, status) and XDSList (density, dividers)',
+ 'XDSCheckboxListItem can be used inside XDSCheckboxList (collection mode) or XDSList (standalone mode)',
+ 'In collection mode, XDSCheckboxListItem requires a `value` prop — throws if missing',
+ 'Uses XDSCheckboxInput internally with isLabelHidden for the checkbox visual',
+ 'Full-row click target with guard against interactive endContent children',
+ 'Async actions use useOptimistic + useTransition for immediate visual feedback',
+ 'Density maps to checkbox size: compact → sm, balanced/spacious → md',
+ ],
+ components: [
+ {
+ name: 'XDSCheckboxList',
+ description:
+ 'Checkbox group container with field integration for label, description, and status.',
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSCheckboxList label="Notifications" value={selected} onChange={setSelected}>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+</XDSCheckboxList>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Label text for the checkbox group (always rendered for accessibility).',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSCheckboxListItem elements.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string[]',
+ description: 'The currently selected values (collection mode).',
+ },
+ {
+ name: 'onChange',
+ type: '(values: string[]) => void',
+ description: 'Callback fired when the selected values change.',
+ },
+ {
+ name: 'onChangeAction',
+ type: '(values: string[]) => void | Promise<void>',
+ description: 'Async action on change with optimistic updates.',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description: 'External loading state.',
+ default: 'false',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Whether to visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Spacing density for list items.',
+ default: "'balanced'",
+ },
+ {
+ name: 'hasDividers',
+ type: 'boolean',
+ description: 'Whether to show dividers between items.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether all checkbox items are disabled.',
+ default: 'false',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description: 'Status indicator ({ type, message }).',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+ },
+ {
+ name: 'XDSCheckboxListItem',
+ description:
+ 'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside XDSCheckboxList) or standalone mode (inside XDSList).',
+ examples: [
+ {
+ label: 'Collection mode',
+ code: `<XDSCheckboxListItem label="Email" value="email" />`,
+ },
+ {
+ label: 'Standalone mode',
+ code: `<XDSCheckboxListItem
+ label="Accept terms"
+ isChecked={accepted}
+ onCheck={setAccepted}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Primary text label for the item.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Identity key (required inside XDSCheckboxList).',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Secondary text below the label.',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Content rendered after the label area.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether this individual item is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'isChecked',
+ type: "boolean | 'indeterminate'",
+ description: 'Direct checked state (standalone mode only).',
+ },
+ {
+ name: 'onCheck',
+ type: '(checked: boolean) => void',
+ description: 'Direct check handler (standalone mode only).',
+ },
+ ],
+ },
+ ],
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+ name: 'CheckboxList',
+ description:
+ '用于从选项列表中进行多值选择的复选框组组件。支持集合模式(父组件管理状态)和独立模式(逐项状态)。',
+ features: [
+ '无障碍 - 使用原生 <input type="checkbox">,配合正确的 ARIA 属性',
+ '集合模式 - 父组件将选中值管理为 string[],子项派生选中状态',
+ '独立模式 - 各项使用 isChecked/onCheck 进行独立控制',
+ '密度 - 通过 XDSList 集成支持紧凑、平衡、宽敞三种密度',
+ '分隔线 - 列表项之间的可选边框分隔线',
+ '不确定状态 - 独立模式下支持三态复选框(true、false、indeterminate)',
+ '描述 - 每个选项可选的辅助文本',
+ '尾部内容 - 标签后的徽章、操作或其他内容插槽',
+ '禁用状态 - 支持禁用整个组或单个选项',
+ '异步操作 - onChangeAction 配合乐观更新和忙碌状态',
+ '全行点击 - 点击行中任意位置均可切换复选框',
+ '字段集成 - 使用 XDSField 提供标签、描述和状态消息',
+ ],
+ examples: [
+ {
+ label: '基础集合模式',
+ code: `<XDSCheckboxList
+ label="Notifications"
+ value={selected}
+ onChange={setSelected}
+>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+ <XDSCheckboxListItem label="Push" value="push" />
+</XDSCheckboxList>`,
+ },
+ {
+ label: '带描述',
+ code: `<XDSCheckboxList
+ label="Preferences"
+ value={selected}
+ onChange={setSelected}
+ hasDividers
+>
+ <XDSCheckboxListItem
+ label="Email"
+ value="email"
+ description="Receive notifications via email"
+ />
+ <XDSCheckboxListItem
+ label="SMS"
+ value="sms"
+ description="Standard messaging rates apply"
+ />
+</XDSCheckboxList>`,
+ },
+ {
+ label: '独立模式',
+ code: `<XDSList>
+ <XDSCheckboxListItem
+ label="Accept terms"
+ isChecked={accepted}
+ onCheck={setAccepted}
+ />
+</XDSList>`,
+ },
+ {
+ label: '带状态',
+ code: `<XDSCheckboxList
+ label="Required selections"
+ value={selected}
+ onChange={setSelected}
+ status={{ type: 'error', message: 'Please select at least one option' }}
+>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+</XDSCheckboxList>`,
+ },
+ {
+ label: '禁用组',
+ code: `<XDSCheckboxList
+ label="Locked selections"
+ value={['email']}
+ onChange={() => {}}
+ isDisabled
+>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+</XDSCheckboxList>`,
+ },
+ ],
+ theming: {
+ targets: [
+ {className: 'xds-checkbox-list-item'},
+ ],
+ },
+ notes: [
+ 'XDSCheckboxList 组合 XDSField(标签、描述、状态)和 XDSList(密度、分隔线)',
+ 'XDSCheckboxListItem 可在 XDSCheckboxList(集合模式)或 XDSList(独立模式)内使用',
+ '在集合模式下,XDSCheckboxListItem 需要 `value` 属性——缺失时会抛出错误',
+ '内部使用带 isLabelHidden 的 XDSCheckboxInput 作为复选框视觉元素',
+ '全行点击目标,带有对交互式尾部内容子元素的防护',
+ '异步操作使用 useOptimistic + useTransition 实现即时视觉反馈',
+ '密度映射到复选框尺寸:compact → sm,balanced/spacious → md',
+ ],
+ components: [
+ {
+ name: 'XDSCheckboxList',
+ description:
+ '复选框组容器,集成字段功能,支持标签、描述和状态。',
+ examples: [
+ {
+ label: '基础用法',
+ code: `<XDSCheckboxList label="Notifications" value={selected} onChange={setSelected}>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+</XDSCheckboxList>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ '复选框组的标签文本(始终渲染以确保无障碍可访问性)。',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSCheckboxListItem 元素。',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string[]',
+ description: '当前选中的值(集合模式)。',
+ },
+ {
+ name: 'onChange',
+ type: '(values: string[]) => void',
+ description: '选中值变更时触发的回调函数。',
+ },
+ {
+ name: 'onChangeAction',
+ type: '(values: string[]) => void | Promise<void>',
+ description: '变更时的异步操作,配合乐观更新。',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description: '外部加载状态。',
+ default: 'false',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: '是否在视觉上隐藏标签。',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: '显示在标签下方的描述文本。',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: '列表项的间距密度。',
+ default: "'balanced'",
+ },
+ {
+ name: 'hasDividers',
+ type: 'boolean',
+ description: '是否在选项之间显示分隔线。',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '是否禁用所有复选框选项。',
+ default: 'false',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description: '状态指示器({ type, message })。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
+ },
+ ],
+ },
+ {
+ name: 'XDSCheckboxListItem',
+ description:
+ '单个复选框选项,包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',
+ examples: [
+ {
+ label: '集合模式',
+ code: `<XDSCheckboxListItem label="Email" value="email" />`,
+ },
+ {
+ label: '独立模式',
+ code: `<XDSCheckboxListItem
+ label="Accept terms"
+ isChecked={accepted}
+ onCheck={setAccepted}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '选项的主要文本标签。',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: '标识键(在 XDSCheckboxList 内为必填)。',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: '标签下方的辅助文本。',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '在标签区域后渲染的内容。',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '是否禁用此单个选项。',
+ default: 'false',
+ },
+ {
+ name: 'isChecked',
+ type: "boolean | 'indeterminate'",
+ description: '直接选中状态(仅独立模式)。',
+ },
+ {
+ name: 'onCheck',
+ type: '(checked: boolean) => void',
+ description: '直接选中处理器(仅独立模式)。',
+ },
+ ],
+ },
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description:
+ 'Checkbox group component for multi-value selection. Collection mode (parent state) + standalone mode (per-item state).',
+ features: [
+ 'Accessible; uses native <input type="checkbox"> w/ proper ARIA attributes',
+ 'Collection mode; parent manages selected values as string[]',
+ 'Standalone mode; items use isChecked/onCheck independently',
+ 'Density; compact, balanced, spacious via XDSList',
+ 'Dividers; optional border dividers between items',
+ 'Indeterminate; three-state checkbox in standalone mode',
+ 'End content; slot for badges/actions after label',
+ 'Disabled state; group-level or individual',
+ 'Async actions; onChangeAction w/ optimistic updates + busy state',
+ 'Full-row click; toggles checkbox, guards interactive endContent',
+ 'Field integration; XDSField for label, description, status',
+ ],
+ notes: [
+ 'XDSCheckboxList composes XDSField (label, description, status) + XDSList (density, dividers)',
+ 'XDSCheckboxListItem works inside XDSCheckboxList (collection) or XDSList (standalone)',
+ 'Collection mode requires `value` prop on items; throws if missing',
+ 'Uses XDSCheckboxInput w/ isLabelHidden for checkbox visual',
+ 'Full-row click target w/ guard against interactive endContent children',
+ 'Async uses useOptimistic + useTransition for immediate feedback',
+ 'Density maps to checkbox size: compact → sm, balanced/spacious → md',
+ ],
+ components: [
+ {
+ name: 'XDSCheckboxList',
+ description:
+ 'Checkbox group container w/ field integration for label, description, status.',
+ propDescriptions: {
+ label: 'Label text for checkbox group (always rendered for accessibility).',
+ children: 'XDSCheckboxListItem elements.',
+ value: 'Currently selected values (collection mode).',
+ onChange: 'Callback fired when selected values change.',
+ onChangeAction: 'Async action on change w/ optimistic updates.',
+ isLoading: 'External loading state.',
+ isLabelHidden: 'Whether to visually hide label.',
+ description: 'Description text below label.',
+ density: 'Spacing density for list items.',
+ hasDividers: 'Whether to show dividers between items.',
+ isDisabled: 'Whether all checkbox items disabled.',
+ status: 'Status indicator ({ type, message }).',
+ xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
+ },
+ },
+ {
+ name: 'XDSCheckboxListItem',
+ description:
+ 'Individual checkbox item w/ label, description, end content slot.',
+ propDescriptions: {
+ label: 'Primary text label for item.',
+ value: 'Identity key (required inside XDSCheckboxList).',
+ description: 'Secondary text below label.',
+ endContent: 'Content rendered after label area.',
+ isDisabled: 'Whether this individual item disabled.',
+ isChecked: 'Direct checked state (standalone mode only).',
+ onCheck: 'Direct check handler (standalone mode only).',
+ },
+ },
+ ],
+};
diff --git a/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx b/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
new file mode 100644
index 0000000000..81a0ae533f
--- /dev/null
+++ b/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
@@ -0,0 +1,417 @@
+/**
+ * @file XDSCheckboxList.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSCheckboxList, XDSCheckboxListItem
+ * @output Unit tests for XDSCheckboxList and XDSCheckboxListItem behavior
+ * @position Testing; validates XDSCheckboxList.tsx and XDSCheckboxListItem.tsx implementation
+ *
+ * SYNC: When XDSCheckboxList.tsx or XDSCheckboxListItem.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSCheckboxList} from './XDSCheckboxList';
+import {XDSCheckboxListItem} from './XDSCheckboxListItem';
+import {XDSList} from '../List/XDSList';
+
+describe('XDSCheckboxList', () => {
+ it('renders with label', () => {
+ render(
+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+ expect(screen.getByText('Preferences')).toBeInTheDocument();
+ });
+
+ it('renders checkbox items', () => {
+ render(
+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+ <XDSCheckboxListItem label="Option C" value="c" />
+ </XDSCheckboxList>,
+ );
+ expect(screen.getAllByRole('checkbox')).toHaveLength(3);
+ });
+
+ it('checks the correct items based on value prop', () => {
+ render(
+ <XDSCheckboxList
+ label="Preferences"
+ value={['a', 'c']}
+ onChange={() => {}}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+ <XDSCheckboxListItem label="Option C" value="c" />
+ </XDSCheckboxList>,
+ );
+ const checkboxes = screen.getAllByRole('checkbox');
+ expect(checkboxes[0]).toBeChecked();
+ expect(checkboxes[1]).not.toBeChecked();
+ expect(checkboxes[2]).toBeChecked();
+ });
+
+ it('calls onChange with added value when checking an item', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+ render(
+ <XDSCheckboxList
+ label="Preferences"
+ value={['a']}
+ onChange={handleChange}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+ </XDSCheckboxList>,
+ );
+
+ await user.click(screen.getByRole('checkbox', {name: 'Option B'}));
+ expect(handleChange).toHaveBeenCalledTimes(1);
+ expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
+ });
+
+ it('calls onChange with removed value when unchecking an item', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+ render(
+ <XDSCheckboxList
+ label="Preferences"
+ value={['a', 'b']}
+ onChange={handleChange}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+ </XDSCheckboxList>,
+ );
+
+ await user.click(screen.getByRole('checkbox', {name: 'Option A'}));
+ expect(handleChange).toHaveBeenCalledWith(['b']);
+ });
+
+ it('disables all checkboxes when group isDisabled is true', () => {
+ render(
+ <XDSCheckboxList
+ label="Preferences"
+ value={[]}
+ onChange={() => {}}
+ isDisabled>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+ </XDSCheckboxList>,
+ );
+ const checkboxes = screen.getAllByRole('checkbox');
+ expect(checkboxes[0]).toBeDisabled();
+ expect(checkboxes[1]).toBeDisabled();
+ });
+
+ it('does not call onChange when group is disabled', () => {
+ const handleChange = vi.fn();
+ render(
+ <XDSCheckboxList
+ label="Preferences"
+ value={[]}
+ onChange={handleChange}
+ isDisabled>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+
+ // Use fireEvent since userEvent correctly blocks pointer-events: none
+ fireEvent.click(screen.getByRole('checkbox', {name: 'Option A'}));
+ expect(handleChange).not.toHaveBeenCalled();
+ });
+
+ it('disables individual item when item isDisabled is true', () => {
+ render(
+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" isDisabled />
+ </XDSCheckboxList>,
+ );
+ const checkboxes = screen.getAllByRole('checkbox');
+ expect(checkboxes[0]).not.toBeDisabled();
+ expect(checkboxes[1]).toBeDisabled();
+ });
+
+ it('throws when item has no value prop inside collection-mode XDSCheckboxList', () => {
+ // Suppress console.error for expected error
+ const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+ expect(() => {
+ render(
+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <XDSCheckboxListItem label="No value" />
+ </XDSCheckboxList>,
+ );
+ }).toThrow(
+ 'XDSCheckboxListItem requires a `value` prop when used inside XDSCheckboxList with a value array.',
+ );
+ spy.mockRestore();
+ });
+
+ it('renders error status message', () => {
+ render(
+ <XDSCheckboxList
+ label="Preferences"
+ value={[]}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Select at least one'}}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+ expect(screen.getByText('Select at least one')).toBeInTheDocument();
+ });
+
+ it('renders description on items', () => {
+ render(
+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <XDSCheckboxListItem
+ label="Option A"
+ value="a"
+ description="This is option A"
+ />
+ </XDSCheckboxList>,
+ );
+ expect(screen.getByText('This is option A')).toBeInTheDocument();
+ });
+
+ it('renders description on the checkbox list group', () => {
+ render(
+ <XDSCheckboxList
+ label="Preferences"
+ description="Choose your preferences"
+ value={[]}
+ onChange={() => {}}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+ expect(screen.getByText('Choose your preferences')).toBeInTheDocument();
+ });
+
+ it('supports data-testid on CheckboxList', () => {
+ render(
+ <XDSCheckboxList
+ label="Preferences"
+ value={[]}
+ onChange={() => {}}
+ data-testid="my-checkbox-list">
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+ expect(screen.getByTestId('my-checkbox-list')).toBeInTheDocument();
+ });
+
+ it('supports data-testid on CheckboxListItem', () => {
+ render(
+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <XDSCheckboxListItem
+ label="Option A"
+ value="a"
+ data-testid="my-checkbox-item"
+ />
+ </XDSCheckboxList>,
+ );
+ expect(screen.getByTestId('my-checkbox-item')).toBeInTheDocument();
+ });
+
+ it('renders endContent', () => {
+ render(
+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <XDSCheckboxListItem
+ label="Option A"
+ value="a"
+ endContent={<span data-testid="end">Badge</span>}
+ />
+ </XDSCheckboxList>,
+ );
+ expect(screen.getByTestId('end')).toBeInTheDocument();
+ });
+
+ it('does not toggle when clicking interactive endContent', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+ render(
+ <XDSCheckboxList label="Preferences" value={[]} onChange={handleChange}>
+ <XDSCheckboxListItem
+ label="Option A"
+ value="a"
+ endContent={<button data-testid="end-btn">Action</button>}
+ />
+ </XDSCheckboxList>,
+ );
+
+ await user.click(screen.getByTestId('end-btn'));
+ expect(handleChange).not.toHaveBeenCalled();
+ });
+
+ it('allows standalone items inside XDSCheckboxList without parent value (select-all pattern)', async () => {
+ const user = userEvent.setup();
+ const handleSelectAll = vi.fn();
+ const handleCheck = vi.fn();
+ render(
+ <XDSCheckboxList label="Columns" hasDividers>
+ <XDSCheckboxListItem
+ label="Select all"
+ isChecked={false}
+ onCheck={handleSelectAll}
+ />
+ <XDSCheckboxListItem
+ label="Name"
+ isChecked={true}
+ onCheck={handleCheck}
+ />
+ <XDSCheckboxListItem
+ label="Email"
+ isChecked={false}
+ onCheck={handleCheck}
+ />
+ </XDSCheckboxList>,
+ );
+
+ // All items render without throwing
+ expect(screen.getAllByRole('checkbox')).toHaveLength(3);
+
+ // Select all triggers its own handler
+ await user.click(screen.getByRole('checkbox', {name: 'Select all'}));
+ expect(handleSelectAll).toHaveBeenCalledWith(true);
+ expect(handleCheck).not.toHaveBeenCalled();
+ });
+});
+
+describe('XDSCheckboxListItem standalone mode', () => {
+ it('uses isChecked/onCheck for standalone control', async () => {
+ const user = userEvent.setup();
+ const handleCheck = vi.fn();
+ render(
+ <XDSList>
+ <XDSCheckboxListItem
+ label="Accept terms"
+ isChecked={false}
+ onCheck={handleCheck}
+ />
+ </XDSList>,
+ );
+
+ await user.click(screen.getByRole('checkbox', {name: 'Accept terms'}));
+ expect(handleCheck).toHaveBeenCalledWith(true);
+ });
+
+ it('renders checked state from isChecked prop', () => {
+ render(
+ <XDSList>
+ <XDSCheckboxListItem label="Checked item" isChecked={true} />
+ </XDSList>,
+ );
+ expect(screen.getByRole('checkbox')).toBeChecked();
+ });
+
+ it('renders unchecked when no isChecked provided', () => {
+ render(
+ <XDSList>
+ <XDSCheckboxListItem label="Default item" />
+ </XDSList>,
+ );
+ expect(screen.getByRole('checkbox')).not.toBeChecked();
+ });
+
+ it('does not throw without value prop in standalone mode', () => {
+ expect(() => {
+ render(
+ <XDSList>
+ <XDSCheckboxListItem label="No value needed" />
+ </XDSList>,
+ );
+ }).not.toThrow();
+ });
+
+ it('renders indeterminate state', () => {
+ render(
+ <XDSList>
+ <XDSCheckboxListItem label="Partial" isChecked="indeterminate" />
+ </XDSList>,
+ );
+ const checkbox = screen.getByRole('checkbox');
+ expect(checkbox).toHaveAttribute('aria-checked', 'mixed');
+ });
+
+ it('calls onCheck with true when clicking indeterminate item', async () => {
+ const user = userEvent.setup();
+ const handleCheck = vi.fn();
+ render(
+ <XDSList>
+ <XDSCheckboxListItem
+ label="Partial"
+ isChecked="indeterminate"
+ onCheck={handleCheck}
+ />
+ </XDSList>,
+ );
+
+ await user.click(screen.getByRole('checkbox', {name: 'Partial'}));
+ expect(handleCheck).toHaveBeenCalledWith(true);
+ });
+});
+
+describe('XDSCheckboxListItem ARIA props', () => {
+ it('sets aria-checked on the list item in collection mode', () => {
+ render(
+ <XDSCheckboxList label="Prefs" value={['a']} onChange={() => {}}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ <XDSCheckboxListItem label="Option B" value="b" />
+ </XDSCheckboxList>,
+ );
+ const items = screen.getAllByRole('listitem');
+ // Item A is checked
+ expect(items[0]).toHaveAttribute('aria-checked', 'true');
+ // Item B is not checked
+ expect(items[1]).toHaveAttribute('aria-checked', 'false');
+ });
+
+ it('sets aria-checked on the list item in standalone mode', () => {
+ render(
+ <XDSList>
+ <XDSCheckboxListItem label="Done" isChecked={true} />
+ <XDSCheckboxListItem label="Todo" isChecked={false} />
+ </XDSList>,
+ );
+ const items = screen.getAllByRole('listitem');
+ expect(items[0]).toHaveAttribute('aria-checked', 'true');
+ expect(items[1]).toHaveAttribute('aria-checked', 'false');
+ });
+
+ it('sets aria-checked="mixed" for indeterminate items', () => {
+ render(
+ <XDSList>
+ <XDSCheckboxListItem label="Partial" isChecked="indeterminate" />
+ </XDSList>,
+ );
+ const item = screen.getByRole('listitem');
+ expect(item).toHaveAttribute('aria-checked', 'mixed');
+ });
+
+ it('sets aria-busy during async actions', () => {
+ // Render with a pending async action by providing onChangeAction
+ // that returns a promise that never resolves
+ render(
+ <XDSCheckboxList label="Prefs" value={['a']} onChange={() => {}}>
+ <XDSCheckboxListItem label="Option A" value="a" />
+ </XDSCheckboxList>,
+ );
+ // By default isBusy is false, so aria-busy should not be present
+ const item = screen.getByRole('listitem');
+ expect(item).not.toHaveAttribute('aria-busy');
+ });
+
+ it('forwards arbitrary aria attributes to the list item DOM element', () => {
+ render(
+ <XDSList>
+ <XDSCheckboxListItem
+ label="Custom aria"
+ aria-describedby="help-text"
+ aria-label="custom label"
+ />
+ </XDSList>,
+ );
+ const item = screen.getByRole('listitem');
+ expect(item).toHaveAttribute('aria-describedby', 'help-text');
+ expect(item).toHaveAttribute('aria-label', 'custom label');
+ });
+});
diff --git a/packages/core/src/CheckboxList/XDSCheckboxList.tsx b/packages/core/src/CheckboxList/XDSCheckboxList.tsx
new file mode 100644
index 0000000000..e7ecbf2a7d
--- /dev/null
+++ b/packages/core/src/CheckboxList/XDSCheckboxList.tsx
@@ -0,0 +1,210 @@
+'use client';
+
+/**
+ * @file XDSCheckboxList.tsx
+ * @input Uses React, useId, useOptimistic, useTransition, XDSField, XDSList, XDSCheckboxListContext
+ * @output Exports XDSCheckboxList component, XDSCheckboxListProps
+ * @position Core implementation; consumed by index.ts, tested by XDSCheckboxList.test.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/CheckboxList/CheckboxList.doc.mjs
+ * - /packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
+ * - /packages/core/src/CheckboxList/index.ts
+ * - /apps/storybook/stories/CheckboxList.stories.tsx
+ */
+
+import {useId, useOptimistic, useTransition, type ReactNode} from 'react';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {XDSField} from '../Field/XDSField';
+import type {XDSInputStatus} from '../Field/types';
+import {XDSList} from '../List/XDSList';
+import type {XDSListDensity} from '../List/XDSListContext';
+import {
+ XDSCheckboxListContext,
+ type XDSCheckboxListContextValue,
+} from './XDSCheckboxListContext';
+
+const EMPTY_ARRAY: string[] = [];
+
+export interface XDSCheckboxListProps {
+ /**
+ * Label text for the checkbox group (always rendered for accessibility).
+ */
+ label: string;
+ /**
+ * Whether to visually hide the label (still accessible to screen readers).
+ * @default false
+ */
+ isLabelHidden?: boolean;
+ /**
+ * Description text displayed below the label.
+ */
+ description?: string;
+ /**
+ * Status indicator for the checkbox group.
+ * When set with a message, displays a colored message box below the group.
+ */
+ status?: XDSInputStatus;
+ /**
+ * The currently selected values (collection mode).
+ */
+ value?: string[];
+ /**
+ * Callback fired when the selected values change (collection mode).
+ */
+ onChange?: (values: string[]) => void;
+ /**
+ * Async action on change. Fires after onChange.
+ * While pending, items show reduced opacity and aria-busy.
+ */
+ onChangeAction?: (values: string[]) => void | Promise<void>;
+ /**
+ * Whether the checkbox group is in an external loading state.
+ * @default false
+ */
+ isLoading?: boolean;
+ /**
+ * Spacing density for list items.
+ * @default 'balanced'
+ */
+ density?: XDSListDensity;
+ /**
+ * Whether to show dividers between list items.
+ * @default false
+ */
+ hasDividers?: boolean;
+ /**
+ * Whether all checkbox items are disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+ /**
+ * Checkbox list items to render.
+ */
+ children: ReactNode;
+ /** Ref forwarded to the root element */
+ ref?: React.Ref<HTMLDivElement>;
+ /**
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
+ */
+ xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
+ /**
+ * Test ID for the outer container.
+ */
+ 'data-testid'?: string;
+}
+
+/**
+ * A checkbox group component for multi-value selection.
+ *
+ * Composes XDSField (for label, description, status) and XDSList
+ * (for density, dividers) with a context provider for collection mode.
+ *
+ * @example
+ * ```
+ * <XDSCheckboxList
+ * label="Notifications"
+ * value={selected}
+ * onChange={setSelected}>
+ * <XDSCheckboxListItem label="Email" value="email" />
+ * <XDSCheckboxListItem label="SMS" value="sms" />
+ * <XDSCheckboxListItem label="Push" value="push" />
+ * </XDSCheckboxList>
+ * ```
+ */
+export function XDSCheckboxList({
+ label,
+ isLabelHidden = false,
+ description,
+ status,
+ value,
+ onChange,
+ onChangeAction,
+ isLoading = false,
+ density = 'balanced',
+ hasDividers = false,
+ isDisabled = false,
+ children,
+ ref,
+ xstyle,
+ className,
+ style,
+ 'data-testid': dataTestId,
+}: XDSCheckboxListProps) {
+ const inputID = useId();
+ const descriptionID = useId();
+ const statusMessageID = useId();
+
+ const [, startTransition] = useTransition();
+ const isCollectionMode = value !== undefined;
+ const effectiveValue = value ?? EMPTY_ARRAY;
+ const [optimisticValue, setOptimisticValue] = useOptimistic(effectiveValue);
+ const isBusy = isLoading || optimisticValue !== effectiveValue;
+
+ const handleChange = (newValues: string[]) => {
+ onChange?.(newValues);
+ if (onChangeAction) {
+ startTransition(async () => {
+ setOptimisticValue(newValues);
+ await onChangeAction(newValues);
+ });
+ }
+ };
+
+ const contextValue: XDSCheckboxListContextValue = {
+ value: isCollectionMode ? optimisticValue : undefined,
+ onChange: isCollectionMode ? handleChange : undefined,
+ isDisabled,
+ isBusy,
+ };
+
+ return (
+ <XDSField
+ ref={ref}
+ data-testid={dataTestId}
+ label={label}
+ isLabelHidden={isLabelHidden}
+ description={description}
+ inputID={inputID}
+ descriptionID={description ? descriptionID : undefined}
+ isDisabled={isDisabled}
+ status={
+ status
+ ? {
+ type: status.type,
+ message: status.message,
+ messageID: status.message ? statusMessageID : undefined,
+ }
+ : undefined
+ }
+ statusVariant="detached"
+ xstyle={xstyle}
+ className={className}
+ style={style}>
+ <XDSCheckboxListContext.Provider value={contextValue}>
+ <XDSList density={density} hasDividers={hasDividers}>
+ {children}
+ </XDSList>
+ </XDSCheckboxListContext.Provider>
+ </XDSField>
+ );
+}
+
+XDSCheckboxList.displayName = 'XDSCheckboxList';
diff --git a/packages/core/src/CheckboxList/XDSCheckboxListContext.tsx b/packages/core/src/CheckboxList/XDSCheckboxListContext.tsx
new file mode 100644
index 0000000000..8b0aacb776
--- /dev/null
+++ b/packages/core/src/CheckboxList/XDSCheckboxListContext.tsx
@@ -0,0 +1,20 @@
+'use client';
+
+/**
+ * @file XDSCheckboxListContext.tsx
+ * @input Uses React createContext
+ * @output Exports XDSCheckboxListContext for parent-child communication
+ * @position Internal context; consumed by XDSCheckboxList.tsx and XDSCheckboxListItem.tsx
+ */
+
+import {createContext} from 'react';
+
+export interface XDSCheckboxListContextValue {
+ value?: string[];
+ onChange?: (values: string[]) => void;
+ isDisabled: boolean;
+ isBusy: boolean;
+}
+
+export const XDSCheckboxListContext =
+ createContext<XDSCheckboxListContextValue | null>(null);
diff --git a/packages/core/src/CheckboxList/XDSCheckboxListItem.tsx b/packages/core/src/CheckboxList/XDSCheckboxListItem.tsx
new file mode 100644
index 0000000000..1672f3f0bf
--- /dev/null
+++ b/packages/core/src/CheckboxList/XDSCheckboxListItem.tsx
@@ -0,0 +1,203 @@
+'use client';
+
+/**
+ * @file XDSCheckboxListItem.tsx
+ * @input Uses React, XDSCheckboxInput, XDSListItem, XDSCheckboxListContext
+ * @output Exports XDSCheckboxListItem component, XDSCheckboxListItemProps
+ * @position Core implementation; consumed by index.ts, tested by XDSCheckboxList.test.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/CheckboxList/CheckboxList.doc.mjs
+ * - /packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
+ * - /packages/core/src/CheckboxList/index.ts
+ * - /apps/storybook/stories/CheckboxList.stories.tsx
+ */
+
+import {useContext, useState, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import type {XDSBaseProps} from '../XDSBaseProps';
+import {XDSCheckboxInput} from '../CheckboxInput/XDSCheckboxInput';
+import {XDSListItem} from '../List/XDSListItem';
+import {XDSListContext} from '../List/XDSListContext';
+import {XDSCheckboxListContext} from './XDSCheckboxListContext';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ selected: {
+ backgroundColor: colorVars['--color-accent-muted'],
+ },
+});
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSCheckboxListItemProps extends XDSBaseProps<HTMLLIElement> {
+ /**
+ * Primary text label for the item.
+ */
+ label: string;
+ /**
+ * Identity key for collection mode (REQUIRED inside XDSCheckboxList).
+ * Throws a runtime error if missing when used inside XDSCheckboxList.
+ */
+ value?: string;
+ /**
+ * Secondary text below the label.
+ */
+ description?: string;
+ /**
+ * Content rendered after the label area.
+ */
+ endContent?: ReactNode;
+ /**
+ * Whether this individual item is disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+ /**
+ * Direct checked state (standalone mode only).
+ * Ignored when inside XDSCheckboxList.
+ */
+ isChecked?: boolean | 'indeterminate';
+ /**
+ * Direct check handler (standalone mode only).
+ * Ignored when inside XDSCheckboxList.
+ */
+ onCheck?: (checked: boolean) => void;
+ /** Ref forwarded to the root element */
+ ref?: React.Ref<HTMLLIElement>;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A checkbox item for use within XDSCheckboxList (collection mode)
+ * or XDSList (standalone mode).
+ *
+ * In collection mode, checked state is derived from the parent's value array.
+ * In standalone mode, uses isChecked/onCheck props directly.
+ *
+ * Composes XDSListItem internally — gets density, dividers, hover/press,
+ * focus, and container alignment for free.
+ *
+ * @example
+ * ```
+ * <XDSCheckboxListItem label="Email" value="email" />
+ * <XDSCheckboxListItem
+ * label="Accept terms"
+ * isChecked={accepted}
+ * onCheck={setAccepted}
+ * />
+ * ```
+ */
+export function XDSCheckboxListItem({
+ label,
+ value,
+ description,
+ endContent,
+ isDisabled: isItemDisabled = false,
+ isChecked,
+ onCheck,
+ ref,
+ xstyle,
+ className,
+ style,
+ ...restProps
+}: XDSCheckboxListItemProps) {
+ const ctx = useContext(XDSCheckboxListContext);
+
+ if (ctx && ctx.value !== undefined && value === undefined) {
+ throw new Error(
+ 'XDSCheckboxListItem requires a `value` prop when used inside XDSCheckboxList with a value array.',
+ );
+ }
+
+ const [isFocused, setIsFocused] = useState(false);
+
+ // Density from list context for checkbox sizing
+ const listCtx = useContext(XDSListContext);
+ const density = listCtx?.density ?? 'balanced';
+ const checkboxSize = density === 'compact' ? 'sm' : 'md';
+
+ // Disabled: parent-level OR item-level
+ const effectiveDisabled = (ctx?.isDisabled ?? false) || isItemDisabled;
+ const isBusy = ctx?.isBusy ?? false;
+
+ // Resolve checked state:
+ // 1. Collection mode (inside XDSCheckboxList with value[])
+ // 2. Standalone mode (isChecked prop)
+ // 3. Neither → unchecked
+ let resolvedChecked: boolean | 'indeterminate' = false;
+ if (ctx && ctx.value !== undefined) {
+ resolvedChecked = ctx.value.includes(value!);
+ } else if (isChecked !== undefined) {
+ resolvedChecked = isChecked;
+ }
+
+ // Whether this item is interactive (has a toggle handler)
+ const isInteractive = ctx != null || onCheck != null;
+
+ const handleToggle = () => {
+ if (effectiveDisabled || isBusy) return;
+
+ if (ctx && ctx.value !== undefined) {
+ // Collection mode
+ const currentlyChecked = ctx.value.includes(value!);
+ if (currentlyChecked) {
+ ctx.onChange?.(ctx.value.filter(v => v !== value));
+ } else {
+ ctx.onChange?.([...ctx.value, value!]);
+ }
+ } else {
+ // Standalone mode
+ const shouldCheck = resolvedChecked === true ? false : true;
+ onCheck?.(shouldCheck);
+ }
+ };
+
+ return (
+ <XDSListItem
+ {...restProps}
+ ref={ref}
+ label={label}
+ description={description}
+ endContent={endContent}
+ isDisabled={effectiveDisabled}
+ onClick={isInteractive ? handleToggle : undefined}
+ aria-checked={
+ resolvedChecked === 'indeterminate' ? 'mixed' : resolvedChecked
+ }
+ aria-busy={isBusy || undefined}
+ xstyle={
+ [
+ resolvedChecked === true && !effectiveDisabled && styles.selected,
+ xstyle,
+ ] as StyleXStyles
+ }
+ className={className}
+ style={style}
+ startContent={
+ <XDSCheckboxInput
+ label={label}
+ isLabelHidden
+ value={resolvedChecked}
+ onChange={() => handleToggle()}
+ onFocus={() => setIsFocused(true)}
+ onBlur={() => setIsFocused(false)}
+ isDisabled={effectiveDisabled}
+ size={checkboxSize}
+ />
+ }
+ />
+ );
+}
+
+XDSCheckboxListItem.displayName = 'XDSCheckboxListItem';
diff --git a/packages/core/src/CheckboxList/index.ts b/packages/core/src/CheckboxList/index.ts
new file mode 100644
index 0000000000..79d21249fe
--- /dev/null
+++ b/packages/core/src/CheckboxList/index.ts
@@ -0,0 +1,15 @@
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports XDSCheckboxList, XDSCheckboxListItem components and types
+ * @output Exports XDSCheckboxList, XDSCheckboxListProps, XDSCheckboxListItem, XDSCheckboxListItemProps
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header
+ */
+
+export {XDSCheckboxList} from './XDSCheckboxList';
+export type {XDSCheckboxListProps} from './XDSCheckboxList';
+export {XDSCheckboxListItem} from './XDSCheckboxListItem';
+export type {XDSCheckboxListItemProps} from './XDSCheckboxListItem';
diff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsx
index 601818dad2..9cc05a9f5f 100644
--- a/packages/core/src/List/XDSList.tsx
+++ b/packages/core/src/List/XDSList.tsx
@@ -102,6 +102,12 @@ const styles = stylex.create({
margin: 0,
paddingInlineStart: 0,
listStyleType: 'none',
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-0-5'],
+ },
+ withDividers: {
+ gap: 0,
},
withCounter: {
counterReset: 'xds-list',
@@ -170,6 +176,7 @@ export function XDSList({
xdsClassName('list', {density, listStyle}),
stylex.props(
styles.list,
+ hasDividers && styles.withDividers,
listStyle !== 'none' && styles.withCounter,
xstyle,
),
diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsx
index 461aedeaa0..213cd6f710 100644
--- a/packages/core/src/List/XDSListItem.tsx
+++ b/packages/core/src/List/XDSListItem.tsx
@@ -25,6 +25,7 @@ import {
typeScaleVars,
borderVars,
} from '../theme/tokens.stylex';
+import type {XDSBaseProps} from '../XDSBaseProps';
import {XDSListContext} from './XDSListContext';
import {xdsClassName, mergeProps} from '../utils';
@@ -32,7 +33,7 @@ import {xdsClassName, mergeProps} from '../utils';
// Types
// =============================================================================
-export interface XDSListItemProps {
+export interface XDSListItemProps extends XDSBaseProps<HTMLLIElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLLIElement>;
/**
@@ -88,33 +89,6 @@ export interface XDSListItemProps {
* @default false
*/
isSelected?: boolean;
-
- /**
- * StyleX styles created via `stylex.create()`. Merged with the component's
- * base styles inside a single `stylex.props()` call for optimal deduplication.
- *
- * @example
- * ```
- * const overrides = stylex.create({ root: { marginBottom: 8 } });
- * <Component xstyle={overrides.root} />
- * ```
- */
- xstyle?: StyleXStyles;
- /**
- * CSS class name(s) appended to the root element.
- * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
- */
- className?: string;
- /**
- * Inline styles to apply to the root element. Spread after StyleX
- * inline styles, so these values take priority.
- */
- style?: React.CSSProperties;
-
- /**
- * Test ID for testing frameworks.
- */
- 'data-testid'?: string;
}
// =============================================================================
@@ -175,9 +149,11 @@ const styles = stylex.create({
},
disabled: {
cursor: 'not-allowed',
- opacity: 0.5,
pointerEvents: 'none' as const,
},
+ disabledContent: {
+ opacity: 0.5,
+ },
selected: {
backgroundColor: colorVars['--color-accent-muted'],
},
@@ -352,8 +328,8 @@ export function XDSListItem({
xstyle,
className,
style,
- 'data-testid': testId,
ref,
+ ...restProps
}: XDSListItemProps) {
const ctx = useContext(XDSListContext);
const density = ctx?.density ?? 'balanced';
@@ -400,7 +376,10 @@ export function XDSListItem({
target={target}
aria-disabled={isDisabled || undefined}
tabIndex={isDisabled ? -1 : undefined}
- {...stylex.props(styles.invisibleAnchor)}>
+ {...stylex.props(
+ styles.invisibleAnchor,
+ isDisabled && styles.disabledContent,
+ )}>
{labelAndDescription}
</a>
) : onClick != null ? (
@@ -408,15 +387,30 @@ export function XDSListItem({
type="button"
onClick={onClick}
disabled={isDisabled}
- {...stylex.props(styles.invisibleButton)}>
+ {...stylex.props(
+ styles.invisibleButton,
+ isDisabled && styles.disabledContent,
+ )}>
{labelAndDescription}
</button>
) : (
- <span {...stylex.props(styles.content)}>{labelAndDescription}</span>
+ <span
+ {...stylex.props(
+ styles.content,
+ isDisabled && styles.disabledContent,
+ )}>
+ {labelAndDescription}
+ </span>
)}
{endContent != null && (
- <span {...stylex.props(styles.endContent)}>{endContent}</span>
+ <span
+ {...stylex.props(
+ styles.endContent,
+ isDisabled && styles.disabledContent,
+ )}>
+ {endContent}
+ </span>
)}
</>
);
@@ -437,9 +431,9 @@ export function XDSListItem({
return (
<li
ref={ref}
- data-testid={testId}
aria-selected={isSelected || undefined}
aria-disabled={isDisabled || undefined}
+ {...restProps}
{...mergeProps(
xdsClassName('list-item'),
stylex.props(
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 24a068af59..667b2daa15 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -26,6 +26,7 @@ export * from './Center';
export * from './CodeBlock';
export * from './CommandPalette';
export * from './CheckboxInput';
+export * from './CheckboxList';
export * from './Collapsible';
export * from './RadioList';
export * from './Divider';