OTP input

Anatomy

The label, help text, and error message come from a Field. Screen readers hear one field, not one per box.

Length, type, and mask

• length sets the number of boxes: 6 by default, 4 for a PIN.
• type: numeric (default) accepts 0–9 and shows the number pad; alphanumeric accepts letters and digits and keeps their case.
• mask shows filled boxes as dots. Use it only for a code people know, such as a PIN: it can stop the phone from filling in an SMS code.

Typing and pasting

• Typing fills a box and moves to the next. Typing on a filled box replaces it.
• Backspace clears and steps back. Arrow keys, Home, and End move between boxes. Tab always leaves the field.
• Pasting fills every box, from any position, and drops spaces and hyphens: "98 76-54" becomes 987654.
• An SMS code from the phone's autofill fills every box at once.
• The active box shows a blinking caret, or a steady one when reduced motion is on.

States

The boxes don't change on hover. The active box takes the focus color and a thicker border; that is the focus indicator.

• Error: set error on the Field. Every box turns red, the active one too, and the message shows under the row. The OTP input doesn't check the code; you decide when and what to say.
• readonly: people can focus and copy the code, but not change it.
• disabled: the field can't be focused or edited, and it's left out of the form.
• Required: set required on the Field. The code must be complete to submit.
• A correct code shows no green state. Move people on to the next screen.

Completion

When the last box fills, the field fires tk-complete with the code in detail.value. It doesn't submit or move focus by itself.

• You can submit on tk-complete, but people using a screen reader or keyboard may want to check the code first. A verify button is safer.
• If the code is wrong, set error on the Field and keep focus in the field.

When to use

• Use an OTP input for a fixed-length one-time code: a verification code, a two-factor code, a PIN.
• Use an Input for other text, including a long reference number. A password goes in tk-input type="password".
• A single field works too. An Input with inputmode="numeric" and autocomplete="one-time-code" is simpler and just as accessible. Use the OTP input when the boxed look helps people see the code's length.
• Build the surroundings yourself: the resend link and its countdown, the verify button, the "sent to" text, and the success screen.

Content

• Label: name the code and its length: "Enter the 6-digit code we sent you".
• Help text: where the code was sent, or how long it's valid. No links.
• Error: say what happened and what to do: "That code is incorrect. Check it and try again", or "Enter the 6-digit code" for an empty submit. No "please" or "sorry".

More in Errors.

Do / Don't

Related

• Field: the label, help text, and error around the code.
• Input: any other text, and the single-field option for a code.

API

Attributes

Events

Resetting the form restores the first value without firing change.

Methods

• focus(): moves focus into the field.

CSS

• ::part(field): the row of boxes.
• ::part(box): each box.
• ::part(input): the real <input>.

Tokens

The caret is border/accent/focus, red on an error. Characters are font-size-lg, medium weight. Boxes are radius-8, space-8 apart. Values per theme: Color.

Accessibility

Built in:

• One real <input>: one Tab stop, one field for screen readers, and native caret, paste, and autofill.
• autocomplete="one-time-code" by default, so SMS codes fill in.
• The keyboard follows type: the number pad for numeric codes.
• Typing never moves focus out of the field, and Tab always leaves it.
• A composing Field names the field, links the help text and error, and marks it invalid on error.
• Enter submits the form the field is in.

Your part:

• Give every OTP input a name: a Field label, or aria-label.
• Don't submit the moment the code is complete without a way to check it.
• Use mask only for codes people know.

Contrast limits

The resting box border shares the Input's limits: see Input contrast limits.