OTP Field

A one-time code in a row of single-character slots that moves along as you type and fills from a paste.

Full screen

01Preview

Verification code

Sent to your phone ending 42. Paste works too.

02Installation

npx shadcn@latest add https://aiellie.app/r/otp-field.json

03API reference

From the Base UI documentation

Groups all OTP field parts and manages their state. Renders a <div> element.

Props

Prop	Type	Default	Description
name	string	-	Identifies the field when a form is submitted.
defaultValue	string	-	The uncontrolled OTP value when the component is initially rendered.
value	string	-	The OTP value.
onValueChange	((value: string, eventDetails: OTPField.Root.ChangeEventDetails) => void)	-	Callback fired when the OTP value changes. The `eventDetails.reason` indicates what triggered the change: `'input-change'` for typing or autofill`'input-clear'` when a character is removed by text input`'input-paste'` for paste interactions`'keyboard'` for keyboard interactions that change the value
autoComplete	string	'one-time-code'	The input autocomplete attribute. Applied to the first slot and hidden validation input.
autoSubmit	boolean	false	Whether to submit the owning form when the OTP becomes complete.
form	string	-	A string specifying the `form` element with which the hidden input is associated. This string's value must match the id of a `form` element in the same document.
inputMode	'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'	-	The virtual keyboard hint applied to the slot inputs and hidden validation input. Built-in validation modes provide sensible defaults, but you can override them when needed.
length\*	number	-	The number of OTP input slots. Required so the root can clamp values, detect completion, and generate consistent validation markup before all slots hydrate.
mask	boolean	false	Whether the slot inputs should mask entered characters. Pass `type` directly to individual `<OTPField.Input>` parts to use a custom input type.
normalizeValue	((value: string) => string)	-	Function that normalizes the OTP value after whitespace and `validationType` filtering. It runs whenever OTP Field normalizes a value, including initial/default values, controlled values, and user edits. The returned value is filtered by `validationType` again, then clamped to `length`. It should be idempotent because OTP Field may normalize the same value more than once while handling edits, storing state, and rendering controlled or uncontrolled values. Non-idempotent normalizers can compound across those normalization passes. Characters rejected while normalizing typed or pasted text are reported through `onValueInvalid`.
onValueComplete	((value: string, eventDetails: OTPField.Root.CompleteEventDetails) => void)	-	Callback function that is fired when the OTP value becomes complete, or when a complete value is pasted while the OTP is already complete. When the value changes, it runs later than `onValueChange`, after the internal value update is applied. If a complete pasted value matches the current value, `onValueChange` does not fire. If `autoSubmit` is enabled, it runs immediately before the owning form is submitted.
onValueInvalid	((value: string, eventDetails: OTPField.Root.InvalidEventDetails) => void)	-	Callback fired when entered text contains characters that are rejected by validation or normalization before the OTP value updates. The `value` argument is the attempted user-entered string before normalization.
validationType	OTPField.Root.ValidationType	'numeric'	The type of input validation to apply to the OTP value.
disabled	boolean	false	Whether the component should ignore user interaction.
readOnly	boolean	false	Whether the user should be unable to change the field value.
required	boolean	false	Whether the user must enter a value before submitting a form.
id	string	-	The id of the first input element. Subsequent inputs derive their ids from it (`{id}-2`, `{id}-3`, and so on).
className	string \| ((state: OTPField.Root.State) => string \| undefined)	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	React.CSSProperties \| ((state: OTPField.Root.State) => React.CSSProperties \| undefined)	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	ReactElement \| ((props: HTMLProps, state: OTPField.Root.State) => ReactElement)	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Data Attributes

Attribute	Type	Description
data-disabled	-	Present when the OTP field is disabled.
data-readonly	-	Present when the OTP field is readonly.
data-required	-	Present when the OTP field is required.
data-valid	-	Present when the OTP field is in a valid state (when wrapped in Field.Root).
data-invalid	-	Present when the OTP field is in an invalid state (when wrapped in Field.Root).
data-dirty	-	Present when the OTP field's value has changed (when wrapped in Field.Root).
data-touched	-	Present when the OTP field has been touched (when wrapped in Field.Root).
data-complete	-	Present when all slots are filled.
data-filled	-	Present when the OTP field contains at least one character.
data-focused	-	Present when one of the OTP field inputs is focused.