@wordpress/components
Version:
UI components for WordPress.
130 lines (96 loc) • 3.87 kB
text/mdx
import { Markdown, Meta } from '@storybook/addon-docs/blocks';
import * as ToggleControlStories from './index.story';
<Meta of={ ToggleControlStories } name="Migration Guide" />
# Toggle family migration guide
Migrate from [`ToggleControl`](?path=/docs/components-togglecontrol--docs) in `@wordpress/components` to [`SwitchControl`](?path=/docs/design-system-components-form-switchcontrol--docs) in `@wordpress/ui`. For custom compositions, replace [`FormToggle`](?path=/docs/components-formtoggle--docs) with [`Switch`](?path=/docs/design-system-components-form-primitives-switch--docs).
## Basic migration
Rename the component, callback, and help props:
Before:
```jsx
import { ToggleControl } from '@wordpress/components';
<ToggleControl
label="Fixed background"
checked={ hasFixedBackground }
onChange={ setHasFixedBackground }
help="Keep the background fixed while scrolling."
/>;
```
After:
```jsx
import { SwitchControl } from '@wordpress/ui';
<SwitchControl
label="Fixed background"
checked={ hasFixedBackground }
onCheckedChange={ setHasFixedBackground }
description="Keep the background fixed while scrolling."
/>;
```
## Prop mapping
<Markdown>{ `
| \`ToggleControl\` | \`SwitchControl\` | Notes |
| --- | --- | --- |
| \`checked\` | \`checked\` | Continue passing the state for a controlled switch. |
| \`onChange\` | \`onCheckedChange\` | Receives the next checked state as a boolean. |
| \`help\` | \`description\` | Use plain text only. |
| \`help\` with links or other markup | \`details\` | Use when the help text needs semantic content. |
| \`label\` | \`label\` | The new control requires a plain string. See [Labels](#labels). |
` }</Markdown>
If `help` is a function, evaluate it with the current checked state and pass the result to `description` or `details`:
```jsx
<SwitchControl
label="Fixed background"
checked={ hasFixedBackground }
onCheckedChange={ setHasFixedBackground }
description={ getHelpText( hasFixedBackground ) }
/>
```
## Labels
`SwitchControl` requires a `label` prop with a plain `string` value. The legacy `ToggleControl` accepts a `ReactNode`.
When the label text is already visible elsewhere, pass a descriptive string and hide it visually:
```jsx
<SwitchControl
label="Fixed background"
hideLabelFromVision
checked={ hasFixedBackground }
onCheckedChange={ setHasFixedBackground }
/>
```
To customize the label typography, compose `Switch` with [`Field`](?path=/docs/design-system-components-form-primitives-field--docs):
```jsx
import { Field, Stack, Switch } from '@wordpress/ui';
<Field.Root render={ <Stack gap="sm" align="start" /> }>
<Switch
checked={ hasFixedBackground }
onCheckedChange={ setHasFixedBackground }
/>
<Field.Label
variant="plain"
style={ { fontFamily: 'var(--wpds-typography-font-family-mono)' } }
>
Fixed background
</Field.Label>
</Field.Root>;
```
## FormToggle
`FormToggle.onChange` receives an input change event. `Switch.onCheckedChange` receives the next checked state as a boolean, so remove any `event.target.checked` access:
Before:
```jsx
import { FormToggle } from '@wordpress/components';
<FormToggle
aria-label="Fixed background"
checked={ hasFixedBackground }
onChange={ ( event ) => setHasFixedBackground( event.target.checked ) }
/>;
```
After:
```jsx
import { Switch } from '@wordpress/ui';
<Switch
aria-label="Fixed background"
checked={ hasFixedBackground }
onCheckedChange={ setHasFixedBackground }
/>;
```
Prefer `SwitchControl` for a standard labeled switch. Use `Field.Label` for a visible label in custom compositions.
## Refs and semantics
The legacy components forward refs to an `HTMLInputElement`. The new components forward refs to an `HTMLSpanElement` with switch semantics. Update ref types and any code that reads input properties such as `ref.current.checked` to use the controlled state instead.