OtpField

One-time password / PIN input with individual pin cells.

Introduction

Use OtpField for one-time passwords, PINs, and short verification codes. Each character gets its own pin cell with focus management, paste support, and optional masking.

Label, description, and error chrome sit above/below the pin group. Use TextField when you need a single continuous input instead of discrete cells.

Import

import { OtpField } from "@bridge-ui/vue/Components/OtpField";

import { OtpField } from "@bridge-ui/react/Components/OtpField";

Basic usage

Bind the concatenated string with value/onChange in React or v-model in Vue. Use onComplete (React) or @complete (Vue) when every pin is filled.

Length and type

Control the number of pins with length (default 6). Set type="alphanumeric" to accept letters (normalized to uppercase) as well as digits.

Variants

Pin cells support the same visual variants as other form fields: outline (default), filled, underlined, stacked, and notched.

Masked

Set mask to hide pin values with password-style dots.

Adornment slots

Use the start and end slots for inline adornments beside the pin group—icons, resend actions, or other controls.

Validation

Set error and errorMessage to show invalid styling and an error message below the pins.

TextField, NumberField, Slider, Rating

Accessibility

OtpField links label, description, and error text through controlId and aria-describedby.

Focus moves forward as characters are entered and backward on Backspace.
Pasted values are filtered and spread across pins from the caret.
When error is true, pins receive invalid styling and the error message is announced.

Anatomy

OtpField (root)
├── Header — label, optional corner text, required indicator
├── Pin row
│   ├── start slot (optional)
│   ├── Pin cells — one input per character
│   └── end slot (optional)
└── Footer — description or error message

API

Prop	Type	Default	Description
default-value	string	—	Initial value for uncontrolled usage (without v-model).
v-model	string	—	Two-way binding for the concatenated OTP value.

Prop	Type	Default	Description
defaultValue	string	—	Initial value for uncontrolled usage.
onChange	(value: string) => void	—	Called with the full OTP string when it changes.
onComplete	(value: string) => void	—	Called when every pin is filled.
value	string	—	Concatenated OTP value. Use with onChange for controlled state.

OtpField-specific

Prop	Type	Default	Description
autoFocus	boolean	false	Focus the first empty pin on mount.
classes	OtpFieldClasses	—	Classes for the field chrome and pin cells.
length	number	6	Number of pin slots.
mask	boolean	false	Mask pin values (password-style).
placeholder	string	—	Placeholder character in empty pins.
type	"numeric" \| "alphanumeric"	"numeric"	Character set accepted by each pin.
variant	OtpFieldVariant	"outline"	Visual variant applied to each pin cell.

Events

Event	Payload	Description
@change	string	Emitted when the OTP string changes.
@complete	string	Emitted when every pin is filled.

Prop	Payload	Description
onChange	string	Called when the OTP string changes.
onComplete	string	Called when every pin is filled.

Field chrome

Prop	Type	Default	Description
color	OtpFieldColor	"primary"	Focus color on each pin.
controlId	string	auto	Id for the pin group and related labels.
corner	string	—	Secondary header text.
customProps	object	—	Extra props for internal parts.
description	string	—	Helper text below the pins. Hidden when error and an error message are set, unless showDescriptionOnError.
disabled	boolean	false	Disables all pins.
error	boolean	false	Invalid styling. Hides description when an error message is shown, unless showDescriptionOnError.
errorMessage	string	—	Error message below the pins.
hideErrorMessage	boolean	false	Does not reserve the error row. That row is also omitted while a description is shown.
label	string	—	Primary label above the pins.
readonly	boolean	false	Makes all pins read-only.
required	boolean	false	Shows a required asterisk on the label.
rounded	OtpFieldRounded	"md"	Border radius of each pin.
showDescriptionOnError	boolean	false	Keeps the description visible while the field is invalid.
size	OtpFieldSize	"md"	Pin size and label typography.
slots	object	—	label, corner, description, errorMessage, start, end.