UNPKG

@wordpress/components

Version:
202 lines (155 loc) • 7.86 kB
import { Markdown, Meta } from '@storybook/addon-docs/blocks'; import * as InputControlStories from './index.story'; <Meta of={ InputControlStories } name="Migration Guide" /> # InputControl migration guide Migrate from [`InputControl`](?path=/docs/components-inputcontrol--docs) in `@wordpress/components` to [`InputControl`](?path=/docs/design-system-components-form-inputcontrol--docs) in `@wordpress/ui`. The same guidance applies when replacing legacy [`TextControl`](?path=/docs/components-textcontrol--docs) and [`NumberControl`](?path=/docs/components-numbercontrol--docs) usages. ## Basic migration Update the import and swap the callback prop: ```jsx // Before import { __experimentalInputControl as InputControl } from '@wordpress/components'; <InputControl label="Width" value={ value } onChange={ ( nextValue ) => setValue( nextValue ?? '' ) } help="Enter a value in pixels." />; // After import { InputControl } from '@wordpress/ui'; <InputControl label="Width" value={ value } onValueChange={ ( nextValue ) => setValue( nextValue ) } description="Enter a value in pixels." />; ``` ## Prop mapping <Markdown>{ ` | \`@wordpress/components\` | \`@wordpress/ui\` | Notes | | --- | --- | --- | | \`onChange\` | \`onValueChange\` | Receives the next string value on every change. Legacy \`NumberControl\` also rewrites values to match \`min\`, \`max\`, and \`step\` on Enter and blur; see [Number inputs](#number-inputs). | | \`help\` | \`description\` | Use plain text only. | | \`help\` with links or other markup | \`details\` | Use when the help text needs semantic content. | | \`hideLabelFromVision\` | \`hideLabelFromVision\` | Same behavior. | | \`prefix\` / \`suffix\` | \`prefix\` / \`suffix\` | Wrap slot content in [\`InputLayout.Slot\`](?path=/docs/design-system-components-form-primitives-input--docs#with-prefix) instead of \`InputControlPrefixWrapper\` / \`InputControlSuffixWrapper\`. | | \`size\` | \`size\` | Supports \`default\` and \`compact\`. | | \`type\` | \`type\` | Same HTML input types, including \`number\`. | ` }</Markdown> ## Labels `InputControl` requires a `label` prop with a plain `string` value. Legacy `InputControl`, `TextControl`, and `NumberControl` accept an optional `label`, and the legacy `InputControl` `label` can be a `ReactNode`. When the visible label text already exists elsewhere, pass a descriptive string and hide it visually: ```jsx <InputControl label="Search" hideLabelFromVision value={ value } onValueChange={ setValue } />; ``` When the label is not a plain string, or you need a custom layout, compose the [`Input`](?path=/docs/design-system-components-form-primitives-input--docs) and [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) primitives instead of `InputControl`: ```jsx import { Field, Input } from '@wordpress/ui'; <Field.Root> <Field.Label> Custom <strong>label</strong> content </Field.Label> <Input value={ value } onValueChange={ setValue } /> </Field.Root> ``` See the [`Field` stories](?path=/docs/design-system-components-form-primitives-field--docs) for other association patterns, such as external labels with `aria-labelledby`. ## Prefix and suffix slots Replace the wrapper components with `InputLayout.Slot`: ```jsx // Before import { Icon } from '@wordpress/components'; import { __experimentalInputControl as InputControl, __experimentalInputControlPrefixWrapper as InputControlPrefixWrapper, } from '@wordpress/components'; import { link } from '@wordpress/icons'; <InputControl prefix={ <InputControlPrefixWrapper variant="icon"> <Icon icon={ link } /> </InputControlPrefixWrapper> } />; // After import { Icon, InputControl, InputLayout } from '@wordpress/ui'; import { link } from '@wordpress/icons'; <InputControl prefix={ <InputLayout.Slot padding="minimal"> <Icon icon={ link } /> </InputLayout.Slot> } />; ``` Use `padding="minimal"` for icons and controls. Omit it for text prefixes and suffixes such as `@` or `%`. ## Number inputs Replace `NumberControl` usages with `InputControl` and `type="number"`: ```jsx import { InputControl } from '@wordpress/ui'; <InputControl label="Quantity" type="number" min={ 1 } max={ 10 } step={ 1 } value={ value } onValueChange={ setValue } />; ``` ### Value clamping and step alignment Legacy `NumberControl` rewrites the value on Enter and blur: it clamps to `min`/`max` and aligns to `step`. `@wordpress/ui` `InputControl` passes these constraints to the native `<input type="number">` for validation, but does not rewrite invalid values when the field loses focus. If you relied on the legacy rewrite behavior, normalize the value yourself. A common pattern is to keep accepting edits in `onValueChange`, then clamp on blur: ```jsx import { InputControl } from '@wordpress/ui'; function constrainValue( value, min, max, step ) { const num = parseFloat( value ); if ( Number.isNaN( num ) ) { return value; } const clamped = Math.min( max, Math.max( min, num ) ); if ( step === 'any' ) { return String( clamped ); } const stepNum = parseFloat( step ); const aligned = min + Math.round( ( clamped - min ) / stepNum ) * stepNum; return String( aligned ); } <InputControl label="Quantity" type="number" min={ min } max={ max } step={ step } value={ value } onValueChange={ setValue } onBlur={ ( event ) => { setValue( constrainValue( event.target.value, min, max, step ) ); } } />; ``` Adapt the helper to match your product requirements. The legacy component also fires `onChange` while typing with unclamped values, then again with the clamped value on blur. ### Removed NumberControl features The `@wordpress/ui` `InputControl` does not support these `@wordpress/components` `NumberControl` features: - **`spinControls`** — When desired, use explicit controls in a `suffix` slot. See the [`NumberWithSteppers` story](?path=/story/design-system-components-form-inputcontrol--number-with-steppers). - **`isShiftStepEnabled` / `shiftStep`** — Apply larger increments in your stepper handlers or `onValueChange` logic. - **Mouse-drag value changes** — Not recommended, as they can be confusing and are not supported on touch devices. ## Removed features The `@wordpress/ui` `InputControl` does not support these `@wordpress/components` features: - **`labelPosition`** — Only top labels are recommended. If other layouts are necessary, compose using the [`Input`](?path=/docs/design-system-components-form-primitives-input--docs) and [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) primitives. - **`isPressEnterToChange`** — Keep a local draft value and commit to your state on `Enter` or `blur` if you need deferred updates. - **`onValidate`** — Run validation in your `onValueChange` handler instead. - **`isDragEnabled`, `dragDirection`, and related drag callbacks** — Not recommended, as they can be confusing and are not supported on touch devices. - **`__unstableInputWidth`** — If the label needs to be a different width from the input field, compose using the [`Input`](?path=/docs/design-system-components-form-primitives-input--docs) and [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) primitives. - **`__unstableStateReducer`** — This hook intercepted the internal state machine. Some workarounds for known patterns: - **Display formatting** (for example, zero-padded time segments): always pass a formatted `value`, or format in an `onBlur` handler if updates should be deferred until the field loses focus. - **Paste normalization**: normalize in `onValueChange`, or handle `onPaste` on `InputControl`. - **Custom step or spin behavior**: apply adjustments in `onValueChange`, in an `onBlur` handler, or with explicit controls in a `suffix` slot.