UNPKG

@wordpress/components

Version:
130 lines (96 loc) • 3.87 kB
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.