03 · Forms — text

OtpInput

length · mode · size sm/md/lg · mask · separator · state · disabled

A one-time code in 46×54 boxes; focus moves on its own to the next one as you type and pasting fills everything.

Typing the code

4 8 2 9 1 5
.heex
<.otp_input id="otp01" name="otp01" separator={3} value="482915" aria-label="Código" loop />

size

sm
md
lg
.heex
<div class="flex flex-col gap-3">
  <div :for={size <- ~w(sm md lg)} class="flex flex-wrap items-center gap-2.5">
    <span class="w-[30px] font-mono text-xs text-muted">{size}</span>
    <.otp_input id={"otp02-#{size}"} name={"otp02_#{size}"} size={size} value="4829" autofocus aria-label={"Código #{size}"} />
  </div>
</div>

length · separator · mask

length=4 · mask
separator=3
alphanumeric
.heex
<div class="grid grid-cols-3 gap-4">
  <.otp_input id="otp03-mask" name="otp03_mask" label="length=4 · mask" length={4} mask value="1234" />
  <.otp_input id="otp03-sep" name="otp03_sep" label="separator=3" separator={3} value="482915" />
  <.otp_input id="otp03-alnum" name="otp03_alnum" label="alphanumeric" mode="alphanumeric" value="A7K2Q9" />
</div>

state · disabled

success
Código confirmado
error
Código inválido. Restam 2 tentativas.
disabled
.heex
<div class="grid grid-cols-3 gap-4">
  <.otp_input id="otp04-ok" name="otp04_ok" label="success" state="success" value="482915" help="Código confirmado" />
  <.otp_input id="otp04-err" name="otp04_err" label="error" state="error" value="482910" help="Código inválido. Restam 2 tentativas." />
  <.otp_input id="otp04-dis" name="otp04_dis" label="disabled" disabled />
</div>

API values that complete the parity

mode=numeric
.heex
<div class="grid grid-cols-3 gap-3.5">
  <div class="flex flex-col items-start gap-1.5"><.otp_input id="otp05-num" name="otp05_num" length={4} value="4829" aria-label="Código" /><span class="font-mono text-[11px] text-muted">mode=numeric</span></div>
</div>

Usage

<.otp_input field={@form[:code]} length={6} separator={3} on_complete="verify" />
<.otp_input name="pin" length={4} mask size="lg" />

Rules

  • separator={3} splits six boxes into 3 and 3.
  • state="success" paints green; error red, with the message below.
  • mask shows dots, like a password.

API reference

Todos os function components, atributos, valores e slots que este componente cobre.

A one-time code made of single-character boxes.

<.otp_input field={@form[:code]} label="Codigo de 6 digitos" />
<.otp_input name="pin" length={4} mask autofocus />
<.otp_input field={@form[:code]} separator={3} on_complete="verify" />
<.otp_input name="invite" mode="alphanumeric" length={8} size="lg" />

Typing fills a box and moves to the next, Backspace on an empty box goes back and empties the previous one, the arrows, Home and End move between boxes, and a paste or an autofill spreads its characters over the boxes. Characters the mode does not allow are dropped.

The boxes have no name: a hidden input named like the field carries the joined code and fires a bubbling input event whenever it changes, so a surrounding phx-change receives %{"name" => "482913"} (a partial code while it is typed). A value the server sends later wins over the one in the browser (render value="" to clear a rejected code).

on_complete is an event name or a %JS{}; it is sent to target (or the LiveView) each time the code changes while every box is filled, with %{"id" => id, "name" => name, "value" => code}.

The behaviour lives in the LedgerUI.Otp hook (file otp.js), so the component needs a stable id (from field or name).

With autofocus the box that takes the focus first (the first empty one) is rendered with data-on, so the ring and the caret show before the hook runs (the hook moves that attribute).

<.otp_input>

Renders the boxes, with their caption, help and errors when given.

Attr Type Default Values / notes
id :string nil
name :string nil
value :any nil
field {:struct, Phoenix.HTML.FormField} nil
label :string nil
label_class :any nil
help :string nil
errors :list []
state :string nil nil, `,success,error`
length :integer 6
mode :string "numeric" numeric, alphanumeric
size :string nil nil, sm, md, lg
mask :boolean false
disabled :boolean false
autofocus :boolean false
loop :boolean false Demo animation (CSS only): the digits of value appear in sequence, each box taking the ring in turn. The boxes stay empty.
separator :any nil
on_complete :any nil
target :any nil
aria_label :string "One-time code"
digit_label :string "Digit"
wrapper_class :any nil
class :any nil

Any other HTML/phx attribute goes to the root element.