Skip to main content

PinInput

Enter pins and verification codes with automatic focus advance and clipboard support.

Props
Slots

Anatomy#

PinInput [component; slot=root]
├── input [slot]
└── separator [slot]

Usage#

Use PinInput for verification codes, OTPs, or numeric PINs. It renders one single-character input per slot.

import { PinInput } from 'moraine'

export function Example() {
  return <PinInput length={6} onComplete={(code) => console.log(code)} />
}

Values and completion#

length sets the number of slots (default 5). value and defaultValue accept a joined string ('123456') or an array with one character per slot, and are filtered by validationType and truncated to length. onValueChange always receives an array of length entries with '' for empty slots; use .join('') for the string. onComplete receives the joined string once every slot is filled. Set name to submit the joined value through a hidden input, and form to associate the control with a <form> outside its ancestors. A native form reset restores defaultValue.

<PinInput length={4} value={code()} onValueChange={(chars) => setCode(chars.join(''))} />

Validation type and mask#

validationType controls which characters a slot accepts: 'number' (digits), 'alpha' (letters), 'alphanumeric', or 'text' (any non-whitespace character, the default). It also picks the default inputMode; set inputMode to override it. Use mask to render the slots as password inputs and conceal the entered characters.

<PinInput validationType="number" mask length={4} />

OTP autofill#

Use otp to set autocomplete="one-time-code", so mobile devices can fill codes from SMS messages.

<PinInput otp length={6} />

The hidden input, rendered when name is set, also accepts pasted or autofilled full codes and distributes them across the slots.

Normalization and invalid input#

Use normalizeValue to transform proposed values after validationType filtering, and onValueInvalid to observe refused characters, with a reason of 'patternMismatch' or 'tooLong'. normalizeValue runs on string value and defaultValue and on typed, pasted, or autofilled text; it must be idempotent.

<PinInput
  length={6}
  validationType="alphanumeric"
  normalizeValue={(value) => value.toUpperCase()}
  onValueInvalid={({ value, reason }) => console.warn(reason, value)}
/>

Auto-submit#

Use autoSubmit to call requestSubmit() on the owning form right after onComplete, which runs native validation and fires a submit event. The form comes from form, the inputs, or the closest ancestor <form>; nothing happens without one.

<form>
  <PinInput name="code" length={6} autoSubmit />
</form>

Placeholder#

Use placeholder to show a character hint in empty slots that are not focused:

<PinInput length={6} placeholder="○" />

Separators#

Use groupSize to insert separators between groups of slots. Pass true to split the slots in half, a number for fixed-size groups, or an array of consecutive group sizes. Use separatorRender to replace the default • separator.

<PinInput length={6} groupSize />
<PinInput length={6} groupSize={3} />
<PinInput length={7} groupSize={[3, 1, 3]} />

Keyboard interaction#

Key Description
← Moves focus to the previous input (in RTL, the next).
→ Moves focus to the next input (in RTL, the previous).
Ctrl/Cmd + arrow Moves focus to the first input (previous) or the first empty input (next).
↖ / ↑ Moves focus to the first input.
↘ / ↓ Moves focus to the first empty input (the last when all are filled).
⌫ Clears the focused slot, or the previous slot when it is empty, and moves back.
Ctrl/Cmd + ⌫ Clears all inputs and moves to the first.
⌦ Clears the focused slot.

Backspace and Delete have no effect when the control is read-only. Pasted text fills the slots from the focused one.

Examples#

One-Time Password verification#

Use otp and groupSize for a standard 6-digit SMS verification code.

import { PinInput } from 'moraine'
import { createSignal, Show } from 'solid-js'

export function OtpExample() {
  const [completedCode, setCompletedCode] = createSignal('')

  return (
    <div class="flex flex-col gap-3">
      <PinInput length={6} groupSize otp onComplete={(code) => setCompletedCode(code)} />
      <Show when={completedCode()}>
        <p class="text-sm text-muted-foreground">Verification code entered: {completedCode()}</p>
      </Show>
    </div>
  )
}

Form integration and validation#

Place PinInput inside form.Field with a validation schema so submission requires every slot to be filled.

import { Button, createForm, PinInput } from 'moraine'
import { createSignal } from 'solid-js'
import * as v from 'valibot'

export function FormIntegration() {
  const [submittedCode, setSubmittedCode] = createSignal('')
  const form = createForm({
    schema: v.object({
      code: v.pipe(
        v.string('Verification code is required'),
        v.length(6, 'Verification code must be 6 digits'),
        v.regex(/^\d+$/, 'Verification code must contain digits only'),
      ),
    }),
    initialInput: { code: '' },
    validate: 'submit',
  })

  return (
    <form.Form onSubmit={(output) => setSubmittedCode(output.code)}>
      <div class="max-w-md space-y-4">
        <form.Field
          name="code"
          label="Verification code"
          description="Enter the 6-digit code sent to your device."
          required
        >
          <PinInput length={6} groupSize validationType="number" otp />
        </form.Field>
        <div class="flex gap-3 items-center">
          <Button type="submit" variant="soft" tone="neutral" size="sm">
            Verify
          </Button>
          <p class="text-xs text-muted-foreground">Verified: {submittedCode() || 'none'}</p>
        </div>
      </div>
    </form.Form>
  )
}

Masked PIN for security#

Use mask to hide the entered characters for sensitive passcodes and PINs.

import { Field, PinInput } from 'moraine'
import { createSignal, Show } from 'solid-js'

export function Masked() {
  const [pin, setPin] = createSignal('')

  return (
    <div class="max-w-sm space-y-3">
      <Field
        label="Transaction PIN"
        description="Enter your 4-digit security PIN for confirmation."
      >
        <PinInput validationType="number" length={4} mask onComplete={(val) => setPin(val)} />
      </Field>
      <Show when={pin()}>
        <p class="text-xs text-muted-foreground">PIN entered ({pin().length} digits)</p>
      </Show>
    </div>
  )
}

Alphanumeric recovery key#

Use validationType="alphanumeric" to accept letters and digits in backup keys and recovery codes.

import { Field, PinInput } from 'moraine'
import { createSignal, Show } from 'solid-js'

export function Alphanumeric() {
  const [code, setCode] = createSignal('')

  return (
    <div class="max-w-md space-y-3">
      <Field
        label="Backup Recovery Key"
        description="Enter your 8-character alphanumeric recovery key."
      >
        <PinInput
          validationType="alphanumeric"
          length={8}
          groupSize={4}
          onComplete={(val) => setCode(val)}
        />
      </Field>
      <Show when={code()}>
        <p class="text-xs text-muted-foreground font-mono">Recovery key: {code()}</p>
      </Show>
    </div>
  )
}

Custom separator#

Pass separatorRender to replace the divider between slot groups. It receives the index of the slot it follows.

import { PinInput } from 'moraine'
import { createSignal, Show } from 'solid-js'

export function CustomSeparator() {
  const [value, setValue] = createSignal('')

  return (
    <div class="flex flex-col gap-3">
      <PinInput
        length={6}
        groupSize={3}
        separatorRender={() => <span class="text-muted-foreground font-semibold px-1">-</span>}
        onComplete={(val) => setValue(val)}
      />
      <Show when={value()}>
        <p class="text-xs text-muted-foreground">Code: {value()}</p>
      </Show>
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-complete
Slot: pin-inputpin-input-input
Description: —
data-disabled
Slot: pin-inputpin-input-input
Description: Present when the component, slot, or item is disabled.
data-filled
Slot: pin-inputpin-input-input
Description: —
data-focused
Slot: pin-inputpin-input-input
Description: Present when the element holds keyboard focus.
data-invalid
Slot: pin-inputpin-input-input
Description: Present when the field or form has a validation error.
data-readonly
Slot: pin-inputpin-input-input
Description: Present when the field is in read-only mode.
data-required
Slot: pin-inputpin-input-input
Description: Present when the field input is required.

Props#

Props for the PinInput component. Renders a <div> element by default.

Prop