Pin Input
Enter and manage secure multi-character codes with the PinInput component.
1import { 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.
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.
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.
Sizes
The PinInput component supports different sizes to accommodate various design requirements.
Primitives
You can utilize the primitive components or the css prop to customize the PinInput component.
| 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. |
API
PinInput
The PinInput component is an abstraction over the primitive parts and exposes all Ark UI Root props. Below is a reference table for convenience (see the Ark UI Pin Input API for authoritative details).
| Name | Default | Description |
|---|---|---|
| asChild | Use the provided child element as the rendered element. | |
| autoFocus | Auto‑focus the first input on mount. | |
| blurOnComplete | Blur the last input when the value becomes complete. | |
| count | Number of inputs to render (improves SSR a11y; will become required in next major). | |
| defaultValue | Uncontrolled initial value array (e.g. ['1','2','3']). | |
| disabled | Disable the entire pin input. | |
| dir | ltr | Text direction; affects arrow key navigation. |
| form | Id of an external form to associate the hidden input with. | |
| id | Base id used to derive ids for parts. | |
| ids | Object of element id overrides for composition. | |
| invalid | Mark the pin input as invalid. Adds data-invalid. | |
| mask | Mask each input character similar to a password field. | |
| name | Name attribute for the hidden input (form submission). | |
| onValueChange | Fired whenever any input value changes. Provides { value, valueAsString }. | |
| onValueComplete | Fired when all inputs have valid values (typing or paste). | |
| onValueInvalid | Fired when an invalid value is entered (fails type or pattern). | |
| otp | Enables one‑time‑code autocomplete optimizations (autocomplete="one-time-code"). | |
| pattern | Regular expression the characters must satisfy. | |
| placeholder | "○" | Placeholder character shown in empty inputs. |
| readOnly | Make inputs read‑only. | |
| required | Mark the inputs as required. | |
| selectOnFocus | Select the existing character when an input gains focus. | |
| translations | Localized strings for accessibility / messages. | |
| type | "numeric" | Allowed character set: numeric, alphabetic, or alphanumeric. |
| value | Controlled value array (set length to number of inputs). |
The PinInput component also accepts standard DOM props for the root element and mirrors the Ark UI Root behavior.
The PinInput is an abstraction of the underlying Ark UI primitive Root component.
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. |
On this page