CSC Design System v4
VueFlavour Vue React Angular TypeScriptPrimaryCSC UI ColorsPrimarySecondaryAccentCustom ColorsRedOrangeGreenBluePurplePink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<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, use c-text-field with a mask.

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 a label or 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. required marks every box aria-required, and invalid every box aria-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.
  • autofocus focuses 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

Basic
Vue React Angular TypeScript
<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

PropertyAttributeTypeDefaultDescription
autofocusautofocusbooleanfalse Focus the first digit when the field mounts.
errorMessageerror-messagestring'' Error message shown in place of the hint while the input is invalid
hideMessagehide-messageboolean— Hide the message line — the hint and error messages under the field — and the room it keeps.
hinthintstring'' Hint text for the input
invalidinvalidbooleanfalse Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`.
labellabelstring'' Label of the input group, shown above the digit inputs
lengthlengthnumber6 Number of digits in the code, one box each
namenamestring'' The name the code submits under in a native `<form>`, as typed so far
requiredrequiredbooleanfalse Set as required — shows the required marker on the label
valuevaluestring'' The digits entered so far, joined into one string (`''` when none). Setting it fills the boxes from the first one
hideDetails deprecated hide-detailsbooleanfalse Deprecated. Use `hide-message`. Hide the hint and error messages

Events

EventDetailDescription
changestringFired when the code is committed — Enter, or focus leaving the digits after a change — carrying the digits entered so far (`''` when none).
completionstringFired when the last digit is filled, carrying the complete code.
inputvoidNative bubbling input event fired alongside every value change so a plain `v-model` stays in sync. No detail.
update:valuestringv-model contract event fired on every digit change, carrying the digits entered so far (`''` when none).

Methods

MethodSignatureDescription
focus(options?: FocusOptions): voidFocus its first digit box, as `focus()` does on a native control: the element renders no box of its own to take it.

Slots

SlotDescription
defaultFallback 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.

PartDescription
rootThe wrapper laying out the label, the digit inputs and the message
labelThe group label rendered above the digit inputs
digitsThe inline-grid wrapper around the digit inputs
inputEach single-digit `<input>` box (one per digit)
messageThe hint or error message under the digits, which describes each digit