<c-otp-input>
A one-time-code field: a row of single-digit boxes, filled in order as the user types or pastes a code, under a group label and above a hint or error message.
Usage
Set length to the number of digits (six by default), name the field with
label, and listen for completion to act as soon as every box is filled:
<c-otp-input
v-model="code"
:error-message="error"
:invalid="!!error"
hint="Enter the 6-digit code we sent you"
label="Verification code"
@completion="verify"
/>
When to use
- Entering a short numeric code sent by text message or email, or shown by an authenticator app.
- Not for other numbers — use
c-number-field. For a code with letters or a fixed format, usec-text-fieldwith amask.
Value
The value is the digits entered so far, joined into one string: '12' after
two digits, '' when none. It is the same string everywhere — the value
property, update:value and change. Every change fires update:value and
input; change fires when the code is committed, on Enter or when focus
leaves the boxes after a change (moving between the boxes does not count).
The digits run from the first box up to the first empty one: clearing a box in the middle ends the value there, and the digits after it count again once it is filled.
completion fires with the whole code whenever a change leaves every box
filled, so editing a complete code fires it again with the new code.
Setting value fills the boxes from the first one and fires nothing; set it
to '' to clear them.
Typing and pasting
Each box takes one digit and brings up the numeric keyboard on a phone. Typing a digit moves focus to the next box, and focusing a box selects its digit, so typing replaces it. Backspace in an empty box moves back to the previous one. Anything but a digit — a letter, a space, punctuation — is dropped as it is typed.
Pasting a code into the first box fills the boxes in order, up to length
digits, and moves focus to the last box filled. Spaces and line breaks in the
pasted text are skipped; a paste with any other character that is not a digit
is ignored. The boxes opt out of browser and password-manager autofill.
Label and validation
The label prop names the group; for richer label content, put it in the
default slot instead (the prop wins when both are set). required adds the
required marker to the label. A native <form> without novalidate stops a
submit on an empty required code, and on a partly filled one; elsewhere,
enforcing it is your form logic's job. The code submits under name; see
In a form on c-button.
Validation is yours too: set invalid and an error-message explaining why.
The boxes take the error colour and the message replaces the hint. While
invalid without an error-message, the boxes are still coloured but the hint
keeps rendering as a hint. Checking the code on completion or change fits
most flows. hide-message hides the hint and the error message.
Accessibility
- The boxes form a
role="group"named by the label. Without alabelor slotted label the group has no name, so always give it one. - Each box is its own input and Tab stop, labelled with its position ("Enter
code - digit number - 2 of 6") and described by the hint or error message.
requiredmarks every boxaria-required, andinvalidevery boxaria-invalid. - About 1.4 seconds after the digits stop changing, a polite live region reads what has been entered ("Currently entered - 1 - 2 - 3"), prefixed with the error message while one is shown.
- The box labels and the announcement are fixed English strings.
autofocusfocuses the first box when the field mounts. Use it where entering the code is the page's only task.
Customization
Restyle via CSS parts: ::part(root) wraps the label, the boxes and the
message; ::part(label) is the group label; ::part(digits) is the row of
boxes; ::part(input) is each box; ::part(message) is the hint or error
message.
c-otp-input::part(input) {
font-family: monospace;
}
Examples
<template>
<div>
<c-otp-input
v-model="code"
hint="Enter the 6-digit code we sent you"
label="OTP"
/>
<p>Code: {{ code }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const code = ref('');
</script>
API reference
<c-otp-input>
A one-time-code field: a row of single-digit boxes, filled in order as the user types or pastes a code, under a group label and above a hint or error message.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
autofocus | autofocus | boolean | false | Focus the first digit when the field mounts. |
errorMessage | error-message | string | '' | Error message shown in place of the hint while the input is invalid |
hideMessage | hide-message | boolean | — | Hide the message line — the hint and error messages under the field — and the room it keeps. |
hint | hint | string | '' | Hint text for the input |
invalid | invalid | boolean | false | Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`. |
label | label | string | '' | Label of the input group, shown above the digit inputs |
length | length | number | 6 | Number of digits in the code, one box each |
name | name | string | '' | The name the code submits under in a native `<form>`, as typed so far |
required | required | boolean | false | Set as required — shows the required marker on the label |
value | value | string | '' | The digits entered so far, joined into one string (`''` when none). Setting it fills the boxes from the first one |
hideDetails deprecated | hide-details | boolean | false | Deprecated. Use `hide-message`. Hide the hint and error messages |
Events
| Event | Detail | Description |
|---|---|---|
change | string | Fired when the code is committed — Enter, or focus leaving the digits after a change — carrying the digits entered so far (`''` when none). |
completion | string | Fired when the last digit is filled, carrying the complete code. |
input | void | Native bubbling input event fired alongside every value change so a plain `v-model` stays in sync. No detail. |
update:value | string | v-model contract event fired on every digit change, carrying the digits entered so far (`''` when none). |
Methods
| Method | Signature | Description |
|---|---|---|
focus | (options?: FocusOptions): void | Focus its first digit box, as `focus()` does on a native control: the element renders no box of its own to take it. |
Slots
| Slot | Description |
|---|---|
default | Fallback content for the group label when the `label` prop is not set |
CSS parts
Style from outside with c-otp-input::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The wrapper laying out the label, the digit inputs and the message |
label | The group label rendered above the digit inputs |
digits | The inline-grid wrapper around the digit inputs |
input | Each single-digit `<input>` box (one per digit) |
message | The hint or error message under the digits, which describes each digit |