Otp

An OTP input component with segmented fields, paste support, and validation.

vu-otp · @velkin/react/otp

Copy page

Import

React

npm i @velkin/react

import { VuOtp } from "@velkin/react/otp";

Examples

API

Props

Prop	Type	Default	Description
name	`string`	—	Form field name for submit (`name` attr).
defaultvalue	`string`	—	Restored on `<form reset>` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks cell entry (`disabled` attr).
readonly	`boolean`	—	Focusable but cannot change cells (`readonly` attr).
required	`boolean`	—	Blocks valid submit when incomplete (`required` attr).
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
id	`string`	""	Host id for label `for` / `aria-*` wiring.
variant	VuOtpVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuOtpTone	"normal"	Neutral surface weight. Default: `"normal"`.
size	VuOtpSize	"md"	Cell scale. Default: `"md"`.
radius	VuOtpRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the cell row to the container width. Default: `false`.
compact	`boolean`	false	Tighter label/hint/error spacing. Default: `false`.
length	`number`	6	Number of OTP characters. Default: `6`.
alphanumeric	`boolean`	false	Allows letters in addition to digits. Default: `false`.
value	`string`	""	Canonical OTP string (unmasked). Default: `""`.
masked	`boolean`	false	Masks cell glyphs (`type="password"`). Default: `false`.
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
incompletemessage	`string`	—	Error when some cells are filled but not all; empty uses default.
arialabel	`string`	—	Names the row when no visible label is present.
incompleteMessage	`string`	""	Error when some cells are filled but not all; empty uses a default.
ariaLabel	`string`	""	Names the row when no visible label is present.
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-change	VuOtpChangeDetail	Committed value change (`detail.value`).
vu-invalid	VuOtpInvalidDetail	When validation messages are recomputed.
vu-clear	VuOtpClearDetail	After `reset()` syncs from `defaultValue`.

Slots

Slot	Description
label	Rich label markup; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.

CSS parts

Part	Description
field	Column stacking label, cells row, hint, and error.
label	Label element above the OTP row.
cells	Flex row wrapping all digit cells (`role="group"`).
cell	One OTP character input.
hint	Neutral helper text under the row.
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.
text	String `label` text when the `label` slot is empty.

Methods

Method	Description
reset	- Clears cells to `defaultValue` and dispatches `vu-clear`.
focusFirst	- Focuses the first OTP cell.
validateInput	- Runs validators and syncs validity.

Types

Name	Definition
VuOtpChangeDetail	`{ value: string; }`
VuOtpClearDetail	`{ value: string; }`
VuOtpInvalidDetail	`{ errors: string[]; }`
VuOtpRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuOtpSize	`"sm" \| "md" \| "lg"`
VuOtpTone	`"subtle" \| "normal" \| "strong"`
VuOtpVariant	`"outline" \| "default" \| "underline"`

Import

React

API

Props

Prop	Type	Default	Description
name	`string`	—	Form field name for submit (`name` attr).
defaultvalue	`string`	—	Restored on `<form reset>` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks cell entry (`disabled` attr).
readonly	`boolean`	—	Focusable but cannot change cells (`readonly` attr).
required	`boolean`	—	Blocks valid submit when incomplete (`required` attr).
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
id	`string`	""	Host id for label `for` / `aria-*` wiring.
variant	VuOtpVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuOtpTone	"normal"	Neutral surface weight. Default: `"normal"`.
size	VuOtpSize	"md"	Cell scale. Default: `"md"`.
radius	VuOtpRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the cell row to the container width. Default: `false`.
compact	`boolean`	false	Tighter label/hint/error spacing. Default: `false`.
length	`number`	6	Number of OTP characters. Default: `6`.
alphanumeric	`boolean`	false	Allows letters in addition to digits. Default: `false`.
value	`string`	""	Canonical OTP string (unmasked). Default: `""`.
masked	`boolean`	false	Masks cell glyphs (`type="password"`). Default: `false`.
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
incompletemessage	`string`	—	Error when some cells are filled but not all; empty uses default.
arialabel	`string`	—	Names the row when no visible label is present.
incompleteMessage	`string`	""	Error when some cells are filled but not all; empty uses a default.
ariaLabel	`string`	""	Names the row when no visible label is present.
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-change	VuOtpChangeDetail	Committed value change (`detail.value`).
vu-invalid	VuOtpInvalidDetail	When validation messages are recomputed.
vu-clear	VuOtpClearDetail	After `reset()` syncs from `defaultValue`.

Slots

Slot	Description
label	Rich label markup; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.

CSS parts

Part	Description
field	Column stacking label, cells row, hint, and error.
label	Label element above the OTP row.
cells	Flex row wrapping all digit cells (`role="group"`).
cell	One OTP character input.
hint	Neutral helper text under the row.
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.
text	String `label` text when the `label` slot is empty.

Methods

Method	Description
reset	- Clears cells to `defaultValue` and dispatches `vu-clear`.
focusFirst	- Focuses the first OTP cell.
validateInput	- Runs validators and syncs validity.

Types

Name	Definition
VuOtpChangeDetail	`{ value: string; }`
VuOtpClearDetail	`{ value: string; }`
VuOtpInvalidDetail	`{ errors: string[]; }`
VuOtpRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuOtpSize	`"sm" \| "md" \| "lg"`
VuOtpTone	`"subtle" \| "normal" \| "strong"`
VuOtpVariant	`"outline" \| "default" \| "underline"`

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse