Skip to content

OrigamOtpInputField ​

<OrigamOtpInputField> renders a row of N single-character inputs (default 6) for one-time password / verification code entry. It emits finish when every slot is filled, and handles auto-advance, backspace, and paste natively.

Basic usage with v-model ​

vue
<script setup lang="ts">
import { ref } from 'vue'
const code = ref('')
</script>

<template>
  <OrigamOtpInputField v-model="code" label="OTP code" />
</template>

Length ​

vue
<template>
  <OrigamOtpInputField :length="4" label="4-digit PIN" />
  <OrigamOtpInputField :length="8" label="8-char token" />
</template>

Type (text / password / number) ​

vue
<template>
  <OrigamOtpInputField type="password" :length="6" label="Hidden OTP" />
  <OrigamOtpInputField type="number"   :length="6" label="Numeric OTP" />
</template>

Divider ​

vue
<template>
  <OrigamOtpInputField :length="6" divider="-" label="With divider" />
</template>

Focus all on mount ​

vue
<template>
  <OrigamOtpInputField :length="4" focus-all autofocus label="Focus all" />
</template>

States (disabled / readonly / error) ​

vue
<template>
  <OrigamOtpInputField :length="4" disabled label="Disabled" />
  <OrigamOtpInputField :length="4" :error="true" error-messages="Invalid code" label="Error" />
</template>

Validation with rules ​

The rules prop accepts an array of validator functions. Each function receives the current OTP string (all cells joined) and must return true to pass, or an error string / false to fail. Validation is wired through useValidation and error messages are displayed below the cell row via <OrigamMessages>.

vue
<script setup lang="ts">
import { ref } from 'vue'
const code = ref('')
const rules = [
  (v: string) => v.length === 6 || 'Code incomplet (6 chiffres requis)',
  (v: string) => /^\d+$/.test(v) || 'Chiffres uniquement',
]
</script>

<template>
  <OrigamOtpInputField
    v-model="code"
    :rules="rules"
    :length="6"
    validate-on="input"
    label="Code de vérification"
  />
</template>

The validateOn prop controls when validation fires:

ValueBehaviour
input (default)Validates on every keystroke
blurValidates when the last focused cell loses focus
submitValidates only on <OrigamForm> submit
lazyLike input but skips the initial silent pass

Slots ​

SlotScopeDescription
defaultfield propsExtra content appended after the cells (does not replace them)
label—Custom label
floatingLabel—Custom floating label
prefix—Content before the cells
suffix—Content after the cells
prependInner—Icon/content inside the control, before the cells
appendInner—Icon/content inside the control, after the cells
clear—Custom clear icon (only rendered when clearable)
loader—Custom loading indicator (shown while loading)

Emits ​

EventPayloadDescription
update:modelValuestring | number | nullPartial / full value
update:focusedbooleanFocus state changed (own useFocus(props) call)
finishstringAll cells filled
click:controlMouseEventClick on the control area (.origam-otp-input-field__content)
mousedown:controlMouseEventMousedown on the control area (.origam-otp-input-field__content)
click:clearMouseEventClear button clicked — also resets the model to empty
click:appendInnerMouseEventAppend-inner adornment clicked (relayed from the focused cell's <origam-field>)
click:prependInnerMouseEventPrepend-inner adornment clicked (relayed from the focused cell's <origam-field>)

focus and blur are not component emits — IOtpInputFieldEmits does not declare them. They reach the consumer as plain DOM events, relayed by Vue's attribute fallthrough: @focus / @blur bound on <origam-otp-input-field> work the normal HTML way, they just aren't part of the typed emits contract.

Props (validation) ​

PropTypeDefaultDescription
rulesArray<(v: string) => true | string>[]Validator functions. Receive the full OTP string and return true or an error message.
validationValueany—⚠️ Inherited from IInputProps but IGNORED by this component. OrigamOtpInputField always validates the joined OTP string; whatever you pass here never reaches the rules. See Validation behaviour.
errorMessagesstring | Array<string>—Static error messages bypassing rule evaluation.
validateOn'input' | 'blur' | 'submit' | 'lazy''input'When validation is triggered.
hideDetailsboolean | 'auto'—true hides the details zone (messages). 'auto' hides it when no messages are present.
hintstring—Helper text shown below the cells when focused (or with persistentHint).
persistentHintboolean—Always show hint, even when the field is not focused.

Validation behaviour ​

  • Validation evaluates props.rules against the joined OTP string (model.join('')).
  • validationValue is deliberately inoperative on this component. Every other origam field lets you validate something other than the model (OrigamInput, OrigamTextField, …); OrigamOtpInputField does not. Internally useValidation receives a Proxy over the props that answers both modelValue and validationValue with the joined OTP string, so a consumer-supplied validation-value is silently discarded. This is intentional — an OTP field has exactly one value worth validating, the code the user typed. The prop remains on the declared surface only because it is inherited from IInputProps and removing it would break the public API (issue #697).
  • Error messages are rendered below the cell row via <OrigamMessages>.
  • The component also fires validate() automatically when the finish event fires (all cells filled).
  • The origam-otp-input-field--error CSS class is applied to the root when isValid === false.

Accessibility ​

  • The root wrapper carries role="group", and aria-label sourced from label when set — one accessible name for the whole widget.
  • Each individual cell ALSO carries its own accessible name (t('origam. input.otp', i + 1), "Please enter OTP character N") — the two combine the same way a <fieldset><legend> groups individually-labelled inputs.
  • label is intentionally NOT forwarded onto individual cells: doing so would render it as a visible floating label repeated once per digit box.
  • A clickable inner adornment gets its accessible name from prependInnerAriaLabel / appendInnerAriaLabel (i18n key or literal string). Without one, the zone stays mouse-only: no role="button", no tab stop, and a dev-mode warning naming the missing prop — the DS never fabricates a label (#747).
PropTypeDefaultDescription
prependInnerAriaLabelstring—Accessible name of the prepend-inner zone. Required for click:prependInner to become keyboard-reachable.
appendInnerAriaLabelstring—Accessible name of the append-inner zone. Required for click:appendInner to become keyboard-reachable.
  • ⛔ There is no OUTER prepend/append zone on this component, and therefore no prependIcon / appendIcon / prependAvatar / appendAvatar / prependAriaLabel / appendAriaLabel prop. That surface belongs to <OrigamInput>, which <OrigamOtpInputField> never mounts — it renders one <origam-field> per digit instead. The props were inherited from IInputProps and did nothing; they were removed in #756, mirroring the IAdjacentEmits exclusion already documented on IOtpInputFieldEmits.

Design tokens ​

Ces cinq variables sont les seules que le composant lit réellement — liste établie par grep -oE "--origam-otp-input-field[a-z-]*" sur son .vue, pas recopiée d'un fichier de tokens.

CSS variableDescription
--origam-otp-input-field---gapEspace entre les cellules
--origam-otp-input-field---border-radiusRayon des cellules
--origam-otp-input-field---padding-blockPadding vertical
--origam-otp-input-field---error-colorCouleur du texte des messages d'erreur
--origam-otp-input-field__details---padding-inlinePadding horizontal de la zone details / messages

⛔ Corrigé le 2026-09-02. Cette table citait --origam-otp-input---cell-width et --origam-otp-input---cell-gap, qui n'existent nulle part — ni dans le SCSS, ni dans les feuilles de tokens. Le préfixe réel porte -field. Elle citait aussi --origam-field---border-color, que ce composant ne lit pas, et une variable de largeur par cellule qui n'existe pas non plus : la largeur des cellules n'est pas thémable aujourd'hui.

Une doc de tokens ne se recopie pas d'un fichier de tokens : elle se mesure sur le composant. C'est précisément l'écart que le critère C7 du classeur appelle « doc MENSONGÈRE », par opposition à « doc absente ».