PIN Input
Enter the 4-digit code we sent to your phone.
Code verified.
That code isn't right. Check it and try again.
A one-cell-per-character code input (OTP / PIN) with auto-advance, paste spreading and backspace handling.
Import
Section titled “Import”<script> import PinInput from "@invisible-ui/svelte/PinInput.svelte";</script><script setup> import { PinInput } from "@invisible-ui/vue";</script>import { PinInput } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-pin-input></ds-pin-input>In Elements:
<ds-pin-input label="Verification code" name="code" length="6"></ds-pin-input>The element sends change with detail.value on every edit and complete
once every cell is filled.
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | "" | |
length | number | 6 | |
type | PinInputType | "numeric" | Allowed characters. |
mask | boolean | false | Obscure entered characters. |
disabled | boolean | false | Disable all cells. |
invalid | boolean | false | Validation state — colors the cells (red ring) and signals errors. |
error | string | undefined | undefined | Error message, shown under the cells and announced. A non-empty one marks the cells invalid, like invalid, and every cell points at it through aria-describedby. The app owns it: a form reset leaves it in place, so the app clears it. |
success | boolean | false | Validation success — colors the cells green (e.g. a verified code). |
name | string | undefined | undefined | Form field name — the combined code is submitted under it. |
label * | string | — | Accessible group name. |
onValueChange | ((value: string) => void) | undefined | undefined | Called on every change. |
onComplete | ((value: string) => void) | undefined | undefined | Called when all cells are filled. |
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | string | undefined | v-model value; takes precedence over value when bound. |
value | string | "" | |
length | number | 6 | |
type | PinInputType | "numeric" | Allowed characters. |
mask | boolean | false | Render cells masked (like a password). |
disabled | boolean | false | |
invalid | boolean | false | Validation state; colors the cells (red ring) and signals errors. |
success | boolean | false | Validation success; colors the cells green (e.g. a verified code). |
error | string | undefined | Error message. When non-empty it shows after the cells as an alert, describes each cell and marks the cells invalid. The application owns it: a form reset leaves it in place, and the application clears it. |
name | string | undefined | Form field name; the combined code is submitted under it. |
label * | string | — | Accessible name for the group of cells (required). |
onValueChange | (value: string) => void | undefined | Called whenever the combined value changes. |
onComplete | (value: string) => void | undefined | Called once all cells are filled. |
| Event | Payload |
|---|---|
update:modelValue | value: string |
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | "" | Initial (uncontrolled) or current (controlled) code. |
length | number | 6 | |
type | PinInputType | "numeric" | Allowed characters. |
mask | boolean | false | Render cells masked (like a password). |
disabled | boolean | false | |
invalid | boolean | — | Validation state; colors the cells (red ring) and signals errors. |
error | string | — | An error message shown under the cells as an alert. It describes each cell and marks the input invalid, like invalid. The app owns it: a form reset leaves it in place, so the app clears it. |
success | boolean | false | Validation success; colors the cells green (e.g. a verified code). |
name | string | — | Form field name; the combined code is submitted under it. |
label * | string | — | Accessible name for the group of cells (required). |
onValueChange | (value: string) => void | — | Called whenever the combined value changes. |
onComplete | (value: string) => void | — | Called once all cells are filled. |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | |
value | yes | |
length | yes | default 6 |
type | yes | numeric|alphanumeric |
mask | yes | |
disabled | yes | |
invalid | yes | |
success | yes | |
name | yes | |
description | yes | |
error | yes | a message that also marks the cells invalid |
Reactive attributes re-render the element when they change after the first render.
Properties: value (string).
Emits: bubbling change CustomEvent with detail.value on every edit, and complete CustomEvent with detail.value once every cell is filled.
Digits from other scripts
Section titled “Digits from other scripts”A numeric PIN input accepts Arabic-Indic (٠–٩) and Persian (۰–۹) digits,
typed or pasted, in every locale. The cells show ASCII digits, and
onValueChange and onComplete report ASCII digits.
Error message
Section titled “Error message”A non-empty error shows the message under the control with a hazard icon and
announces it as an alert. It also marks the cells invalid, as invalid does.
Every cell points at it through aria-describedby and takes
aria-invalid="true"; the group takes neither. The message is plain text.
<PinInput label="Verification code" length={6} bind:value error={codeError} />The app owns the message and clears it: a form reset leaves it in place. In Flutter, the validator’s message clears on form reset.
Accessibility
Section titled “Accessibility”- A labelled group of single-character inputs; focus auto-advances and paste fills across cells.
- The arrows follow the layout direction. In a right-to-left layout, ArrowLeft moves to the next cell and ArrowRight to the previous one.
- A non-empty
erroraddsaria-invalid="true"and anaria-describedbylink to the message on every cell.
Example
Section titled “Example”<PinInput length={4} label="Verification code" />In React, onComplete reports the code once every cell is filled:
<PinInput label="Verification code" length={6} name="code" onComplete={verify} />Themeable via --ds-pin-input-*.