Skip to content

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

TypeScript

Improve CheckboxInput docs page and block examples (#1559)

rubyycheung419e4f603ae7
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.doc.mjs
new file mode 100644
index 0000000000..1b94e3aac2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'CheckboxInput — States',
+ description: 'Checkboxes with labels and descriptions in checked, unchecked, and disabled states. Each checkbox controls a single on/off setting. Add a description to explain what the setting does.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CheckboxInput', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.tsx
new file mode 100644
index 0000000000..dc1503fee7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.tsx
@@ -0,0 +1,44 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSCheckboxInput} from '@xds/core/CheckboxInput';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function CheckboxInputBasic() {
+ const [checked, setChecked] = useState<boolean | 'indeterminate'>(true);
+ const [unchecked, setUnchecked] = useState<boolean | 'indeterminate'>(false);
+ const [disabled, setDisabled] = useState<boolean | 'indeterminate'>(false);
+ const [indeterminate, setIndeterminate] = useState<boolean | 'indeterminate'>(
+ 'indeterminate',
+ );
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSCheckboxInput
+ label="Checked"
+ description="This checkbox is currently on."
+ value={checked}
+ onChange={setChecked}
+ />
+ <XDSCheckboxInput
+ label="Unchecked"
+ description="This checkbox is currently off."
+ value={unchecked}
+ onChange={setUnchecked}
+ />
+ <XDSCheckboxInput
+ label="Disabled"
+ description="This checkbox cannot be changed."
+ value={disabled}
+ onChange={setDisabled}
+ isDisabled
+ />
+ <XDSCheckboxInput
+ label="Indeterminate"
+ description="This checkbox represents a partial selection."
+ value={indeterminate}
+ onChange={setIndeterminate}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.doc.mjs
deleted file mode 100644
index 7f50f9ebcf..0000000000
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'CheckboxInput — Disabled Checkbox',
- description:
- 'Disabled checkbox with a description explaining why the option is unavailable.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['CheckboxInput'],
-};
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.tsx
deleted file mode 100644
index 12c5f26259..0000000000
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSCheckboxInput} from '@xds/core/CheckboxInput';
-
-export default function CheckboxInputDisabledCheckbox() {
- const [value, setValue] = useState<boolean | 'indeterminate'>(false);
- return (
- <XDSCheckboxInput
- label="Premium feature"
- description="Upgrade to enable this option"
- value={value}
- onChange={setValue}
- isDisabled
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.doc.mjs
index ddc88ee6eb..28ad8c1409 100644
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.doc.mjs
+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'CheckboxInput — Indeterminate State',
- description:
- 'Checkbox in the indeterminate state, useful for "select all" patterns with partial selection.',
+ name: 'CheckboxInput — Indeterminate',
+ description: 'A "select all" checkbox that controls a group of options. When only some options are checked, it shows a dash instead of a checkmark. Clicking it checks or unchecks everything.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['CheckboxInput'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CheckboxInput', 'Divider', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.tsx
index 45b79085b8..4687770355 100644
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.tsx
+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.tsx
@@ -2,15 +2,61 @@
import {useState} from 'react';
import {XDSCheckboxInput} from '@xds/core/CheckboxInput';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSDivider} from '@xds/core/Divider';
export default function CheckboxInputIndeterminateState() {
- const [value, setValue] = useState<boolean | 'indeterminate'>('indeterminate');
+ const [items, setItems] = useState({
+ email: true,
+ push: false,
+ sms: true,
+ slack: false,
+ });
+
+ const checkedCount = Object.values(items).filter(Boolean).length;
+ const totalCount = Object.keys(items).length;
+ const selectAllValue =
+ checkedCount === 0
+ ? false
+ : checkedCount === totalCount
+ ? true
+ : ('indeterminate' as const);
+
+ const handleSelectAll = (checked: boolean) => {
+ setItems({email: checked, push: checked, sms: checked, slack: checked});
+ };
+
return (
- <XDSCheckboxInput
- label="Select all items"
- description="Some items are selected"
- value={value}
- onChange={setValue}
- />
+ <XDSStack direction="vertical" gap={3}>
+ <XDSCheckboxInput
+ label="Select all notifications"
+ description={`${checkedCount} of ${totalCount} enabled`}
+ value={selectAllValue}
+ onChange={handleSelectAll}
+ />
+ <XDSDivider />
+ <XDSStack direction="vertical" gap={3}>
+ <XDSCheckboxInput
+ label="Email notifications"
+ value={items.email}
+ onChange={v => setItems(prev => ({...prev, email: v}))}
+ />
+ <XDSCheckboxInput
+ label="Push notifications"
+ value={items.push}
+ onChange={v => setItems(prev => ({...prev, push: v}))}
+ />
+ <XDSCheckboxInput
+ label="SMS alerts"
+ value={items.sms}
+ onChange={v => setItems(prev => ({...prev, sms: v}))}
+ />
+ <XDSCheckboxInput
+ label="Slack messages"
+ value={items.slack}
+ onChange={v => setItems(prev => ({...prev, slack: v}))}
+ />
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.doc.mjs
index 277cc1749f..12f3bed4ae 100644
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.doc.mjs
+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'CheckboxInput — Status Variations',
- description:
- 'Multiple checkboxes showing error, warning, and success status messages.',
+ name: 'CheckboxInput — Status',
+ description: 'Checkboxes with error, warning, and success validation messages. Use the status prop to show feedback after form validation — errors block submission, warnings inform, and success confirms.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['CheckboxInput'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CheckboxInput', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.tsx
index 3469cc2789..a477faa197 100644
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.tsx
+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.tsx
@@ -2,32 +2,42 @@
import {useState} from 'react';
import {XDSCheckboxInput} from '@xds/core/CheckboxInput';
+import {XDSStack} from '@xds/core/Layout';
export default function CheckboxInputStatusVariations() {
- const [value1, setValue1] = useState<boolean | 'indeterminate'>(false);
- const [value2, setValue2] = useState<boolean | 'indeterminate'>(true);
- const [value3, setValue3] = useState<boolean | 'indeterminate'>(true);
+ const [error, setError] = useState<boolean | 'indeterminate'>(false);
+ const [warning, setWarning] = useState<boolean | 'indeterminate'>(true);
+ const [success, setSuccess] = useState<boolean | 'indeterminate'>(true);
+
return (
- <div style={{display: 'flex', flexDirection: 'column', gap: 24, maxWidth: 400}}>
+ <XDSStack direction="vertical" gap={4}>
<XDSCheckboxInput
- label="Accept terms and conditions"
- value={value1}
- onChange={setValue1}
- status={{type: 'error', message: 'You must accept the terms to continue'}}
+ label="Error"
+ description="Required field that has not been accepted."
+ value={error}
+ onChange={setError}
+ status={{
+ type: 'error',
+ message: 'You must accept the terms to continue',
+ }}
/>
<XDSCheckboxInput
- label="Share usage data"
- description="Help us improve by sharing anonymous usage statistics"
- value={value2}
- onChange={setValue2}
- status={{type: 'warning', message: 'This data may be shared with partners'}}
+ label="Warning"
+ description="Enabled setting with a side effect to be aware of."
+ value={warning}
+ onChange={setWarning}
+ status={{
+ type: 'warning',
+ message: 'This data may be shared with partners',
+ }}
/>
<XDSCheckboxInput
- label="Email verified"
- value={value3}
- onChange={setValue3}
+ label="Success"
+ description="Confirmed setting that has been verified."
+ value={success}
+ onChange={setSuccess}
status={{type: 'success', message: 'Your email has been verified'}}
/>
- </div>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.doc.mjs
deleted file mode 100644
index 1f9b744bfd..0000000000
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'CheckboxInput — With Description',
- description:
- 'Checkbox with a descriptive helper text below the label.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['CheckboxInput'],
-};
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.tsx
deleted file mode 100644
index f77a1f68a0..0000000000
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.tsx
+++ /dev/null
@@ -1,16 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSCheckboxInput} from '@xds/core/CheckboxInput';
-
-export default function CheckboxInputWithDescription() {
- const [value, setValue] = useState<boolean | 'indeterminate'>(false);
- return (
- <XDSCheckboxInput
- label="Subscribe to newsletter"
- description="Receive weekly updates about new features and announcements."
- value={value}
- onChange={setValue}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.doc.mjs
deleted file mode 100644
index f03e6ed0d6..0000000000
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'CheckboxInput — With Error Status',
- description:
- 'Checkbox displaying a validation error message.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['CheckboxInput'],
-};
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.tsx
deleted file mode 100644
index 668a4bbb06..0000000000
--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.tsx
+++ /dev/null
@@ -1,16 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSCheckboxInput} from '@xds/core/CheckboxInput';
-
-export default function CheckboxInputWithErrorStatus() {
- const [value, setValue] = useState<boolean | 'indeterminate'>(false);
- return (
- <XDSCheckboxInput
- label="Accept terms and conditions"
- value={value}
- onChange={setValue}
- status={{type: 'error', message: 'You must accept the terms to continue'}}
- />
- );
-}
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index c28c8012d4..35c42d1fcd 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -105,12 +105,19 @@ export const docs = {
],
},
usage: {
- description: 'CheckboxInput is a form control for toggling a single boolean value. Use it for standalone on/off settings, terms acceptance, or as a building block inside CheckboxList for multi-select groups.',
+ description: 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',
bestPractices: [
- { guidance: true, description: 'Always provide a visible label for context. Use isLabelHidden only when surrounding UI already makes the purpose clear.' },
- { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes that represent a partial selection.' },
- { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList or a toggle switch instead.' },
- { guidance: false, description: 'Hide the label without an equivalent accessible alternative nearby.' },
+ { guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },
+ { guidance: true, description: 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.' },
+ { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList when only one option can be selected.' },
+ { guidance: false, description: 'Use a checkbox for actions that take effect immediately — use a toggle switch or button instead.' },
+ ],
+ anatomy: [
+ { name: 'Checkbox', required: true, description: 'The check box itself — unchecked, checked, or indeterminate.' },
+ { name: 'Label', required: true, description: 'Text describing what the checkbox controls. Always present for accessibility.' },
+ { name: 'Description', required: false, description: 'Helper text below the label with additional context.' },
+ { name: 'Status message', required: false, description: 'An error, warning, or success message below the checkbox.' },
],
},
};
@@ -119,12 +126,13 @@ export const docs = {
export const docsZh = {
name: 'CheckboxInput',
usage: {
- description: 'CheckboxInput is a form control for toggling a single boolean value. Use it for standalone on/off settings, terms acceptance, or as a building block inside CheckboxList for multi-select groups.',
+ description: 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',
bestPractices: [
- { guidance: true, description: 'Always provide a visible label for context. Use isLabelHidden only when surrounding UI already makes the purpose clear.' },
- { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes that represent a partial selection.' },
- { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList or a toggle switch instead.' },
- { guidance: false, description: 'Hide the label without an equivalent accessible alternative nearby.' },
+ { guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },
+ { guidance: true, description: 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.' },
+ { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList when only one option can be selected.' },
+ { guidance: false, description: 'Use a checkbox for actions that take effect immediately — use a toggle switch or button instead.' },
],
},
props: [
@@ -169,14 +177,12 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'checkbox for toggling boolean values',
+ description: 'single on/off toggle for settings, terms, and opt-in choices',
usage: {
- description: 'CheckboxInput is a form control for toggling a single boolean value. Use it for standalone on/off settings, terms acceptance, or as a building block inside CheckboxList for multi-select groups.',
+ description: 'CheckboxInput toggles a single on/off value. Use for settings, terms acceptance, opt-in choices. Use CheckboxList for groups.',
bestPractices: [
- { guidance: true, description: 'Always provide a visible label for context. Use isLabelHidden only when surrounding UI already makes the purpose clear.' },
- { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes that represent a partial selection.' },
- { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList or a toggle switch instead.' },
- { guidance: false, description: 'Hide the label without an equivalent accessible alternative nearby.' },
+ { guidance: true, description: 'Always provide a visible label. Add description for context. Use indeterminate for partial "select all".' },
+ { guidance: false, description: 'Use for mutually exclusive choices (use RadioList). Use for immediate actions (use toggle/button).' },
],
},
propDescriptions: {