@wordpress/components
Version:
UI components for WordPress.
202 lines (155 loc) • 7.86 kB
text/mdx
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.