|
| 1 | +import { Markdown, Meta } from '@storybook/addon-docs/blocks'; |
| 2 | +import * as CheckboxControlStories from './index.story'; |
| 3 | + |
| 4 | +<Meta of={ CheckboxControlStories } name="Migration Guide" /> |
| 5 | + |
| 6 | +# CheckboxControl migration guide |
| 7 | + |
| 8 | +Migrate from [`CheckboxControl`](?path=/docs/components-checkboxcontrol--docs) in `@wordpress/components` to [`CheckboxControl`](?path=/docs/design-system-components-form-checkboxcontrol--docs) in `@wordpress/ui`. |
| 9 | + |
| 10 | +## Basic migration |
| 11 | + |
| 12 | +Update the import and replace the callback and help props: |
| 13 | + |
| 14 | +```jsx |
| 15 | +// Before |
| 16 | +import { CheckboxControl } from '@wordpress/components'; |
| 17 | + |
| 18 | +<CheckboxControl |
| 19 | + label="Is author" |
| 20 | + checked={ isChecked } |
| 21 | + onChange={ setChecked } |
| 22 | + help="Give this user author permissions." |
| 23 | +/>; |
| 24 | + |
| 25 | +// After |
| 26 | +import { CheckboxControl } from '@wordpress/ui'; |
| 27 | + |
| 28 | +<CheckboxControl |
| 29 | + label="Is author" |
| 30 | + checked={ isChecked } |
| 31 | + onCheckedChange={ setChecked } |
| 32 | + description="Give this user author permissions." |
| 33 | +/>; |
| 34 | +``` |
| 35 | + |
| 36 | +## Prop mapping |
| 37 | + |
| 38 | +<Markdown>{ ` |
| 39 | +| \`@wordpress/components\` | \`@wordpress/ui\` | Notes | |
| 40 | +| --- | --- | --- | |
| 41 | +| \`onChange\` | \`onCheckedChange\` | Receives the next checked state as a boolean. | |
| 42 | +| \`help\` | \`description\` | Use plain text only. | |
| 43 | +| \`help\` with links or other markup | \`details\` | Use when the help text needs semantic content. | |
| 44 | +| \`checked\` | \`checked\` | Continue passing the state for a controlled checkbox. | |
| 45 | +` }</Markdown> |
| 46 | + |
| 47 | +## Form values |
| 48 | + |
| 49 | +When a checked checkbox has a `name` but no `value`, the legacy component submits `"1"` with the form, while the new component submits `"on"`, the native default for checkboxes. If your form handler expects the legacy value, pass `value="1"` to the new component: |
| 50 | + |
| 51 | +```jsx |
| 52 | +<CheckboxControl |
| 53 | + name="isAuthor" |
| 54 | + value="1" |
| 55 | + label="Is author" |
| 56 | + checked={ isChecked } |
| 57 | + onCheckedChange={ setChecked } |
| 58 | +/> |
| 59 | +``` |
| 60 | + |
| 61 | +If the legacy component already has a custom `value`, keep that value instead. |
| 62 | + |
| 63 | +## Labels |
| 64 | + |
| 65 | +The new `CheckboxControl` requires a `label` prop with a plain `string` value. The legacy component treats `label` as optional. Give every checkbox a descriptive label, even when the text is already visible elsewhere: |
| 66 | + |
| 67 | +```jsx |
| 68 | +<CheckboxControl |
| 69 | + label="Receive notifications" |
| 70 | + hideLabelFromVision |
| 71 | + checked={ isChecked } |
| 72 | + onCheckedChange={ setChecked } |
| 73 | +/> |
| 74 | +``` |
| 75 | + |
| 76 | +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. |
| 77 | + |
| 78 | +## Checkbox groups |
| 79 | + |
| 80 | +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. |
| 81 | + |
| 82 | +```jsx |
| 83 | +import { useState } from '@wordpress/element'; |
| 84 | +import { CheckboxControl, CheckboxGroup } from '@wordpress/ui'; |
| 85 | + |
| 86 | +function FruitCheckboxes() { |
| 87 | + const [ selectedFruits, setSelectedFruits ] = useState( [ 'apple' ] ); |
| 88 | + |
| 89 | + return ( |
| 90 | + <CheckboxGroup |
| 91 | + value={ selectedFruits } |
| 92 | + onValueChange={ setSelectedFruits } |
| 93 | + allValues={ [ 'apple', 'orange' ] } |
| 94 | + aria-label="Fruit" |
| 95 | + > |
| 96 | + <CheckboxControl parent value="fruit" label="Select all fruit" /> |
| 97 | + <CheckboxGroup.NestedItems> |
| 98 | + <CheckboxControl value="apple" label="Apple" /> |
| 99 | + <CheckboxControl value="orange" label="Orange" /> |
| 100 | + </CheckboxGroup.NestedItems> |
| 101 | + </CheckboxGroup> |
| 102 | + ); |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | +See the [Checkbox Groups stories](?path=/docs/design-system-components-form-checkbox-groups--docs) for other grouping patterns. |
0 commit comments