Forms

PinInput

Segmented one-time-code input with auto-advance, paste distribution, and masking support for entering short security codes.

import { PinInput } from '@lostgradient/cinder/pin-input';
formotp
01

Overview

Segmented one-time-code input with auto-advance, paste distribution, and optional masking.

Usage

svelte 
<script lang="ts">
  import PinInput from '@lostgradient/cinder/pin-input';
  let code = $state('');
</script>

<PinInput id="otp" bind:value={code} label="Verification code" />
Live preview
02

When to use

Use when
  • Collecting a short security code such as a one-time password or SMS verification code.
  • Letting the browser autofill a one-time-code into a visually segmented control.
Avoid when
  • Collecting a free-form string of any length — use input instead.
  • Collecting a numeric value that participates in arithmetic — use number-input instead.
03

Examples

Alphanumeric code

Eight-character alphanumeric invite code with description text.

Basic PIN input

Six-digit numeric code with auto-advance and SMS autofill.

Masked PIN

Four-digit security PIN rendered as masked segments.

04

Props

Props for pin-input
Name Type Default Required Bindable Description
id text req Stable id used as the segment id prefix and as the hidden input id.
value text '' bind Bindable code value. Defaults to an empty string. No write-back normalization. The bound prop reflects exactly what the consumer set — it is NOT mutated back to the filtered/length-capped value. The displayed and submitted value is normalized via $derived, but the binding itself is left untouched. This is intentional: the consumer owns the source of truth, and silent mutation of a bound prop is a surprising side-effect.
length number 6 Number of segments to render. Normalized to an integer in [1, 12]; non-finite or out-of-range values fall back to 6.
mode 'numeric' | 'alphanumeric' 'numeric' Character set accepted in each segment. Defaults to 'numeric'.
masked boolean false Render segments as password-style fields without changing the emitted value.
label text Visible group label rendered above the segments.
hideLabel boolean false Visually hide the rendered label while keeping it programmatically associated.
description text Optional description text rendered below the segments.
error text Optional error message; sets aria-invalid="true" on every segment.
disabled boolean Disable every segment and the hidden input.
required boolean Mark the group as required for assistive technology.
name text Form-control name applied to the hidden <input> that submits with the form.
autocomplete HTMLInputAttributes['autocomplete'] 'one-time-code' autocomplete value applied to the first segment. Defaults to 'one-time-code' so iOS and Android can autofill SMS codes.
onchange (value: string) => void Fires only for user-initiated committed value changes (typing, paste, autofill, backspace). Never fires for external prop synchronization.