Pin Input

Import

import { PinInput } from '@cerberus/react'

Usage

The PinInput component lets users enter fixed-length codes (such as verification codes or PINs) one character at a time. It manages focus movement between inputs and aggregates the value for you.

Loading example...

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.

Loading example...

Count

The count prop determines the number of individual input boxes rendered. This is useful for specifying the length of the PIN or code the user needs to enter.

Loading example...

Sizes

The PinInput component supports different sizes to accommodate various design requirements.

Failed to load code file: components/pin-input/sizes.demo.tsx

Customization

You can customize the PinInput component using style props or the primitive components.

Loading example...

Primitives

Component	Description
`PinInputRoot`	Root context provider for the family.
`PinInputLabel`	Accessible label element.
`PinInputControl`	Wraps the individual input boxes.
`PinInputInput`	A single character input field.
`PinInputHiddenInput`	Aggregated hidden input used in forms.

Parts

The PinInputParts API is an object containing the full family of components.

Name	Description
`Root`	The `PinInputRoot` component which is the provider for the family.
`Label`	The `PinInputLabel` component.
`Control`	The `PinInputControl` layout wrapper.
`Input`	The `PinInputInput` component.
`HiddenInput`	The `PinInputHiddenInput` component.

API

Root

Props

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

Data Attributes

Attribute	Description / Value
`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

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

HiddenInput

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Input

Props

Prop	Type	Required	Default	Description
`index`	`number`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

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

Label

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`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

Props

Prop	Type	Required	Default	Description
`value`	`UsePinInputReturn`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Context

API:

Property	Type	Description
`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

Import

import { PinInput } from '@cerberus/react'

Usage

The PinInput component lets users enter fixed-length codes (such as verification codes or PINs) one character at a time. It manages focus movement between inputs and aggregates the value for you.

Enter PIN

Loading example...

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.

Loading example...

Count

The count prop determines the number of individual input boxes rendered. This is useful for specifying the length of the PIN or code the user needs to enter.

5 Digits

Loading example...

Sizes

The PinInput component supports different sizes to accommodate various design requirements.

Failed to load code file: components/pin-input/sizes.demo.tsx

Customization

You can customize the PinInput component using style props or the primitive components.

Loading example...

Primitives

Component	Description
`PinInputRoot`	Root context provider for the family.
`PinInputLabel`	Accessible label element.
`PinInputControl`	Wraps the individual input boxes.
`PinInputInput`	A single character input field.
`PinInputHiddenInput`	Aggregated hidden input used in forms.

Parts

The PinInputParts API is an object containing the full family of components.

Name	Description
`Root`	The `PinInputRoot` component which is the provider for the family.
`Label`	The `PinInputLabel` component.
`Control`	The `PinInputControl` layout wrapper.
`Input`	The `PinInputInput` component.
`HiddenInput`	The `PinInputHiddenInput` component.

API

Root

Props

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

Data Attributes

Attribute	Description / Value
`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

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

HiddenInput

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Input

Props

Prop	Type	Required	Default	Description
`index`	`number`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

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

Label

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`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

Props

Prop	Type	Required	Default	Description
`value`	`UsePinInputReturn`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Context

API:

Property	Type	Description
`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