Skip to content

OTP Input ​

A segmented one-time password input that renders individual cells for each digit. Auto-advances focus between cells, supports paste, Backspace navigation, and fires completion events.

Basic Usage ​

html
<ore-otp-input label="Verification code" color="primary"></ore-otp-input>

Listen for completion: use the complete event (not change) to trigger auto-submission after the last cell is filled. Always provide a label attribute to give context (e.g. "Verification code").

html
<ore-otp-input id="otp" label="Enter OTP" color="primary"></ore-otp-input>

<script type="module">
  import '@vielzeug/refine/otp-input';

  document.getElementById('otp').addEventListener('complete', (e) => {
    console.log('OTP complete:', e.detail.value);
  });
</script>

Length ​

Keep length at 4–8 cells: more cells increase cognitive load.

Full width

Types ​

Avoid using alphanumeric for numeric-only codes (e.g. SMS OTPs): numeric triggers the numeric keyboard on mobile.

Full width

Masked Input ​

Use masked to hide the entered values. Always use masked for PINs and security codes to prevent shoulder-surfing.

Full width

With Separator ​

Use separator to add a visual divider between cells.

Full width

Sizes ​

Full width

Colors ​

Full width

Variants ​

Full width

Disabled ​

Full width

Label, Helper & Error ​

label renders a visible caption above the cells; helper and error render assistive text below. An error replaces the helper text, marks every cell invalid, and sets aria-invalid/aria-errormessage on the group. Pass richer markup through the label, helper, and error slots instead of the text attributes.

Full width

Localized Labels ​

Cell and group labels are screen-reader-only and default to English. Override them with the labels JS property: group names the group when no visible label is set, and digit(index, total) names each cell.

Full width

Code Insertion ​

Only the first cell advertises autocomplete="one-time-code". When the browser inserts a complete code there, the component distributes it across the cells instead of keeping only its last character.

Typing, multi-character insertion, and paste use the same character filtering. Bulk insertion starts at the receiving cell, preserves preceding cells, and discards characters beyond the remaining cells. Numeric codes accept digits; alphanumeric codes also accept ASCII letters. Focus moves to the next cell, or stays on the last cell after completion.

API Reference ​

Attributes ​

AttributeTypeDefaultDescription
lengthnumber6Number of input cells
type'numeric' | 'alphanumeric''numeric'Allowed character type
valuestring''Current value (string of all cells concatenated)
maskedbooleanfalseRender cells as hidden characters
separatorbooleanfalseShow a visual divider between cells
disabledbooleanfalseDisable all cells
labelstring''Visible label above the cells
helperstringN/AHelper text below the cells (hidden by error)
errorstringN/AError text; invalidates the cells and group
namestringN/AForm field name
color'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error'N/AFocus ring / active cell color
size'sm' | 'md' | 'lg''md'Cell size
variant'solid' | 'flat' | 'bordered' | 'outline' | 'ghost''solid'Visual style variant

JS Properties ​

PropertyTypeDefaultDescription
labels{ group?: string; digit?: (i, total) => string }English defaultsScreen-reader labels for the group and each cell

Events ​

EventDetailDescription
inputNative EventEmitted after insertion; read the joined host value with eventFieldValue(event)
changeNative EventEmitted after insertion or deletion; read the joined host value with eventFieldValue(event)
complete{ value: string, originalEvent?: Event }Fired when all cells have been filled

CSS Custom Properties ​

PropertyDescription
--otp-cell-sizeWidth and height of each cell
--otp-cell-gapGap between cells
--otp-cell-font-sizeFont size inside each cell
--otp-cell-radiusCell border radius (defaults to var(--radius))
--otp-cell-bgCell background color
--otp-cell-border-colorDefault cell border color
--otp-cell-focus-borderFocused border/caret color
--otp-cell-hover-bgCell background on hover (flat/ghost variants)
--otp-cell-hover-border-colorCell border on hover (flat/bordered variants)
--otp-cell-focus-bgCell background when focused (flat/bordered variants)
--otp-cell-focus-border-colorCell border when focused (flat variant)

Accessibility ​

The OTP input renders a role="group" container named by the visible label (via aria-labelledby) or, when no label is shown, by the labels.group string. The first cell advertises autocomplete="one-time-code"; subsequent cells use autocomplete="off". An active error sets aria-invalid plus aria-errormessage on the group.

Keyboard navigation is fully supported: focus auto-advances to the next cell on valid input, Backspace moves back and clears the cell, Tab moves focus out of the group, and pasting fills cells from the focused cell onward.

Do not auto-submit without giving users a chance to review: show a confirmation step before sending.

  • Input: plain single-line input field