OTP Field · base-ui-svelte

API Reference

Props mirror Base UI React where applicable, adapted for Svelte 5. Native HTML attributes for the rendered element are also accepted unless noted.

OTPField.Root

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

Props

length number —

Name: length
Description: —
Type: number

value string —

Name: value
Description: Controlled value.
Type: string | undefined

defaultValue string —

Name: defaultValue
Description: Uncontrolled initial value.
Type: string

onValueChange function —

Name: onValueChange
Description: Event handler called when the value changes.
Type: ((value: string, event: Event) => void) | undefined

onComplete function —

Name: onComplete
Description: —
Type: ((value: string) => void) | undefined

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

type 'text' | 'password' —

Name: type
Description: Native control type when rendering a native element.
Type: 'text' | 'password'

pattern string —

Name: pattern
Description: —
Type: string | undefined

autoSubmit boolean false

Name: autoSubmit
Description: Whether to submit the owning form when the OTP becomes complete.
Type: boolean
Default: false

mask boolean | string false

Name: mask
Description: When true, inputs use type="password". A string sets a display mask character via CSS hooks.
Type: boolean | string
Default: false

validationType 'numeric' | 'alphanumeric' | 'none' 'numeric'

Name: validationType
Description: Built-in character validation. Overrides default digit-only when set.
Type: 'numeric' | 'alphanumeric' | 'none'
Default: 'numeric'

normalizeValue function —

Name: normalizeValue
Description: 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.
Type: ((value: string) => string) | undefined

onValueInvalid function —

Name: onValueInvalid
Description: 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.
Type: ((details: { value: string; reason: 'pattern' | 'validation-type' }) => void) | undefined

readOnly boolean false

Name: readOnly
Description: Whether the user should be unable to change the field value.
Type: boolean
Default: false

required boolean false

Name: required
Description: Whether the user must enter a value before submitting a form.
Type: boolean
Default: false

form string —

Name: form
Description: 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.
Type: string | undefined

autoFocus boolean —

Name: autoFocus
Description: —
Type: boolean

name string —

Name: name
Description: Identifies the field when a form is submitted.
Type: string | undefined

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet<[{ value: string; disabled: boolean }]>

Data attributes

Attribute	Description
`data-disabled`	Present when the OTP field is disabled.

OTPField.Input

An individual OTP character input. Renders an <input> element.

Props

index number —

Name: index
Description: —
Type: number | undefined

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

Data attributes

Attribute	Description
`data-disabled`	Present when the OTP field is disabled.
`data-index`	Index of the item within a collection.
`data-mask`	Present on the element when applicable.
`data-readonly`	Present when the OTP field is readonly.

OTPField.Separator

A separator element accessible to screen readers. Renders a <div> element.

Props

orientation 'horizontal' | 'vertical' 'horizontal'

Name: orientation
Description: The orientation of the separator.
Type: 'horizontal' | 'vertical'
Default: 'horizontal'

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-orientation`	The orientation of the component.