Skip to content

UI: Recommend Checkbox family components #83771

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mirka merged 10 commits into from
Sep 30, 2026
Merged

UI: Recommend Checkbox family components #83771

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
4f149b5
UI: Recommend Checkbox family components
mirka Sep 29, 2026
eb3ac32
Add Checkbox recommendation changelog entries
mirka Sep 29, 2026
f5e8aaa
Add CheckboxControl migration guide
mirka Sep 30, 2026
a28383b
Remove legacy checkbox heading guidance
mirka Sep 30, 2026
08ef7c3
Document checkbox group migration
mirka Sep 30, 2026
6eb1ef0
Remove redundant checkbox lint examples
mirka Sep 30, 2026
587136f
Merge trunk into recommend-checkbox-family
mirka Sep 30, 2026
d1f6652
Docs: Clarify CheckboxControl form value migration
mirka Sep 30, 2026
5c2c7d7
Merge origin/trunk into recommend-checkbox-family
mirka Sep 30, 2026
b06bc5e
Merge remote-tracking branch 'origin/trunk' into HEAD
mirka Sep 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Document checkbox group migration
  • Loading branch information
@mirka
mirka committed Sep 30, 2026
commit 08ef7c3efb83cfb8d4764b218686fdc6ffaa46ff
31 changes: 30 additions & 1 deletion packages/components/src/checkbox-control/stories/migration-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@ import { CheckboxControl } from '@wordpress/ui';
| \`help\` | \`description\` | Use plain text only. |
| \`help\` with links or other markup | \`details\` | Use when the help text needs semantic content. |
| \`checked\` | \`checked\` | Continue passing the state for a controlled checkbox. |

@ciampo ciampo Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we document the default form value change from "1" to "on" and show value="1" when preserving the legacy payload? A named checkbox migrated using these steps otherwise submits a different value.

@mirka mirka Sep 30, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, added in d1f6652.

| \`indeterminate\` | \`indeterminate\` | Continue passing the indeterminate state when needed. |
` }</Markdown>

## Labels
Expand All @@ -59,3 +58,33 @@ The new `CheckboxControl` requires a `label` prop with a plain `string` value. T
```

For a custom label layout, compose the [`Checkbox`](?path=/docs/design-system-components-form-primitives-checkbox--docs) and [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) primitives.

## Checkbox groups

If a legacy checkbox uses `indeterminate` to show that only some items are selected, move the selected items into a `CheckboxGroup` instead of calculating the parent checkbox state yourself. Pass the child values to `allValues` and mark the select-all checkbox with `parent`. The group updates the parent checkbox when children change and selects or clears all children when the parent is clicked.

```jsx
import { useState } from '@wordpress/element';
import { CheckboxControl, CheckboxGroup } from '@wordpress/ui';

function FruitCheckboxes() {
const [ selectedFruits, setSelectedFruits ] = useState( [ 'apple' ] );

return (
<CheckboxGroup
value={ selectedFruits }
onValueChange={ setSelectedFruits }
allValues={ [ 'apple', 'orange' ] }
aria-label="Fruit"
>
<CheckboxControl parent value="fruit" label="Select all fruit" />
<CheckboxGroup.NestedItems>
<CheckboxControl value="apple" label="Apple" />
<CheckboxControl value="orange" label="Orange" />
</CheckboxGroup.NestedItems>
</CheckboxGroup>
);
}
```

See the [Checkbox Groups stories](?path=/docs/design-system-components-form-checkbox-groups--docs) for other grouping patterns.
Loading