OTP — `<mv-otp>`

One-time code input: a real hidden field handles typing, pasting and SMS autofill, while animated slots display the code with a blinking caret, a separator and an error shake.

Category	Forms
Type	Web Component (`<mv-otp>`)
Status	stable
Keywords	otp, code, pin, 2fa, verification, one-time-code, form-associated

When to use

A one-time code from SMS or email must be entered, with paste and autofill support
A two-factor or login verification step needs a clear per-character layout with error feedback
A short numeric PIN must be entered masked

Avoid when

The value is a password or free-length secret rather than a fixed-length code → use Input instead
The code is long or has variable length, like a license key; a plain text field handles it better

Install

node scripts/add.mjs otp --out ./src/marvelous

AI agent with the Marvelous UI MCP server: install_components({ slugs: ["otp"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Files copied (dependencies included): tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/motion.js, components/otp/otp.js, components/otp/otp.css.

Usage

Canonical markup — start from it and customize with attributes, data-* and CSS variables:

<div style="display:grid;gap:1.75rem;justify-items:center;text-align:center">
  <form id="otp-demo-verify" style="display:grid;gap:.6rem;justify-items:center">
    <label for="otp-demo-code" style="font-size:.875rem;font-weight:600">Verification code</label>
    <mv-otp id="otp-demo-code" name="code" length="6" separator required aria-describedby="otp-demo-hint"></mv-otp>
    <p id="otp-demo-hint" style="margin:0;font-size:.8125rem;color:var(--mv-fg-muted)" aria-live="polite">Sent by text to (•••) •••-••42 — try <strong>424242</strong>.</p>
  </form>

  <div style="display:flex;gap:2.5rem;flex-wrap:wrap;justify-content:center">
    <div style="display:grid;gap:.5rem;justify-items:center">
      <label for="otp-demo-ref" style="font-size:.8125rem;font-weight:500;color:var(--mv-fg-muted)">Referral code</label>
      <mv-otp id="otp-demo-ref" length="6" pattern="alphanumeric" case="upper" separator="3" placeholder="–" data-size="sm"></mv-otp>
    </div>
    <div style="display:grid;gap:.5rem;justify-items:center">
      <label for="otp-demo-pin" style="font-size:.8125rem;font-weight:500;color:var(--mv-fg-muted)">PIN</label>
      <mv-otp id="otp-demo-pin" length="4" mask value="2718" data-size="sm"></mv-otp>
    </div>
  </div>
</div>
<script type="module">
  const otp = document.getElementById("otp-demo-code");
  const hint = document.getElementById("otp-demo-hint");
  const initial = hint.innerHTML;
  otp?.addEventListener("mv-complete", (e) => {
    if (e.detail.value === "424242") {
      otp.valid = true;
      hint.textContent = "Code confirmed, redirecting…";
      hint.style.color = "var(--mv-success)";
    } else {
      otp.invalid = true;
      hint.textContent = "Incorrect code, try again.";
      hint.style.color = "var(--mv-danger)";
    }
  });
  otp?.addEventListener("mv-change", (e) => {
    if (!e.detail.complete && hint.style.color) { hint.innerHTML = initial; hint.style.color = ""; }
  });
</script>

API

Attributes

Name	Type	Default	Description
`length`	number	`6`	Number of slots (1–12).
`pattern`	numeric \| alphanumeric \| alpha \| `<single-character regex>`	`numeric`	Accepted characters; “numeric” opens the number pad on mobile.
`case`	upper \| lower		Forces the case of typed characters.
`separator`	boolean \| "3" \| "2,4"		Visual separator: in the middle if empty, otherwise after the given positions.
`mask`	boolean		Masks the characters (•), for a PIN.
`placeholder`	string		Character(s) shown in empty slots (e.g. “–” or “000000”).
`value`	string		Initial value (and form reset value).
`name`	string		Field name in the form.
`required`	boolean		Invalid until every slot is filled.
`invalid`	boolean		Error state (red border + shake when set); cleared on the next input.
`valid`	boolean		Success state (green border and tint); cleared on the next input.
`disabled`	boolean		Disables input.
`label`	string		Accessible name when no `<label for>` is associated.
`data-size`	sm \| lg		Slot size.

Properties

Name	Type	Description
`value`	string	Current code (filtered and truncated).
`complete`	boolean	Read-only: every slot is filled.
`form / validity / validationMessage`	—	Native form API (ElementInternals).

Methods

Name	Description
`focus()`	Focuses the real input.
`clear()`	Clears the code and the valid/invalid states.
`shake()`	Plays the shake animation.
`checkValidity() / reportValidity()`	Native validation.

Events

Name	Description
`mv-change`	detail: { value, complete } on every change.
`mv-complete`	detail: { value } when the last slot is filled.

CSS classes

Name	Description
`mv-otp-slot / -char / -caret / -separator`	Generated parts (data-active, data-filled).

CSS variables

Name	Default	Description
`--mv-otp-slot-width`	`2.75rem`	Slot width.
`--mv-otp-slot-height`	`3rem`	Slot height.
`--mv-otp-gap`	`var(--mv-space-2)`	Space between slots.
`--mv-otp-radius`	`var(--mv-radius-md)`	Slot radius.

Accessibility

A single real <input> (autocomplete="one-time-code", numeric inputmode) holds focus and the accessible name (from <label for>, label or aria-label); the visual slots are aria-hidden. Arrow keys, Home/End, Backspace and Delete move between slots; pasting spreads the code. aria-invalid reflects the error state; form-associated element with native validation.