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.
