Pin Input

For pin or verification codes with auto-focus transfer and masking options.

Pin Input

Anatomy

<PinInput.Root>
  <PinInput.Label />
  <PinInput.Control>
    <PinInput.Input />
  </PinInput.Control>
  <PinInput.HiddenInput />
</PinInput.Root>

Examples

Placeholder

To customize the default pin input placeholder ○ for each input, pass the placeholder prop and set it to your desired value.

Blur on Complete

By default, the last input maintains focus when filled, and we invoke the onValueComplete callback. To blur the last input when the user completes the input, set the prop blurOnComplete to true.

OTP Mode

To trigger smartphone OTP auto-suggestion, it is recommended to set the autocomplete attribute to "one-time-code". The pin input component provides support for this automatically when you set the otp prop to true.

Masking

When collecting private or sensitive information using the pin input, you might need to mask the value entered, similar to <input type="password"/>. Pass the mask prop to true.

Change Events

The pin input component invokes several callback functions when the user enters:

onValueChange — Callback invoked when the value is changed.
onValueComplete — Callback invoked when all fields have been completed (by typing or pasting).
onValueInvalid — Callback invoked when an invalid value is entered into the input. An invalid value is any value that doesn't match the specified "type".

Field

The Field component helps manage form-related state and accessibility attributes of a pin input. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

Root Provider

An alternative way to control the pin input is to use the RootProvider component and the usePinInput hook. This way you can access the state and methods from outside the component.

API Reference

Props

Root

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`autoFocus`		`boolean` Whether to auto-focus the first input.
`blurOnComplete`		`boolean` Whether to blur the input when the value is complete
`count`		`number` The number of inputs to render to improve SSR aria attributes. This will be required in next major version.
`defaultValue`		`string[]` The initial value of the the pin input when rendered. Use when you don't need to control the value of the pin input.
`disabled`		`boolean` Whether the inputs are disabled
`form`		`string` The associate form of the underlying input element.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string hiddenInput: string label: string control: string input: (id: string) => string }>` The ids of the elements in the pin input. Useful for composition.
`invalid`		`boolean` Whether the pin input is in the invalid state
`mask`		`boolean` If `true`, the input's value will be masked just like `type=password`
`name`		`string` The name of the input element. Useful for form submission.
`onValueChange`		`(details: ValueChangeDetails) => void` Function called on input change
`onValueComplete`		`(details: ValueChangeDetails) => void` Function called when all inputs have valid values
`onValueInvalid`		`(details: ValueInvalidDetails) => void` Function called when an invalid value is entered
`otp`		`boolean` If `true`, the pin input component signals to its fields that they should use `autocomplete="one-time-code"`.
`pattern`		`string` The regular expression that the user-entered input value is checked against.
`placeholder`	`'○'`	`string` The placeholder text for the input
`readOnly`		`boolean` Whether the pin input is in the valid state
`required`		`boolean` Whether the pin input is required
`selectOnFocus`		`boolean` Whether to select input value when input is focused
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`type`	`'numeric'`	`'numeric' \| 'alphanumeric' \| 'alphabetic'` The type of value the pin-input should allow
`value`		`string[]` The controlled value of the the pin input.

Attribute	Description
`[data-scope]`	pin-input
`[data-part]`	root
`[data-invalid]`	Present when invalid
`[data-disabled]`	Present when disabled
`[data-complete]`	Present when the pin-input value is complete
`[data-readonly]`	Present when read-only

Control

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

HiddenInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Input

Renders a <input> element.

Prop	Default	Type
`index`		`number`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	pin-input
`[data-part]`	input
`[data-disabled]`	Present when disabled
`[data-complete]`	Present when the input value is complete
`[data-index]`	The index of the item
`[data-invalid]`	Present when invalid

Label

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	pin-input
`[data-part]`	label
`[data-invalid]`	Present when invalid
`[data-disabled]`	Present when disabled
`[data-complete]`	Present when the label value is complete
`[data-required]`	Present when required
`[data-readonly]`	Present when read-only

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UsePinInputReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

API

Property	Type
`value`	`string[]` The value of the input as an array of strings.
`valueAsString`	`string` The value of the input as a string.
`complete`	`boolean` Whether all inputs are filled.
`count`	`number` The number of inputs to render
`items`	`number[]` The array of input values.
`setValue`	`(value: string[]) => void` Function to set the value of the inputs.
`clearValue`	`VoidFunction` Function to clear the value of the inputs.
`setValueAtIndex`	`(index: number, value: string) => void` Function to set the value of the input at a specific index.
`focus`	`VoidFunction` Function to focus the pin-input. This will focus the first input.

Accessibility

Keyboard Support

Key	Description
`ArrowLeft`	Moves focus to the previous input
`ArrowRight`	Moves focus to the next input
`Backspace`	Deletes the value in the current input and moves focus to the previous input
`Delete`	Deletes the value in the current input
`Control + V`	Pastes the value into the input fields