Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

PinInput / OTP

A multi-cell PIN or one-time-code input with paste and complete handling.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add pin-input

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Verification code
Vue
<script setup lang="ts">
import { ref } from 'vue'
import PinInput from './components/ui/pin-input/PinInput.vue'

const code = ref('')
const messages = {
  character: (index: number, total: number) => `Digit ${index} of ${total}`,
}
function verifyCode(value: string) {
  console.log(value)
}
</script>

<template>
  <span id="verification-label">Verification code</span>
  <PinInput
    v-model="code"
    name="verificationCode"
    aria-labelledby="verification-label"
    :length="6"
    :messages="messages"
    @complete="verifyCode"
  />
</template>

Name the root group and localize every cell label. Typing advances, paste fills forward, navigation keys move focus, and a hidden named input serializes the complete value for forms.

When to use it

One-time verification

Collect a six-digit code sent through another channel.

Masked access code

Enter a short numeric secret without displaying each character.

More examples

Verification code

Autofill and paste can populate the six cells.

Verification code
<script setup lang="ts">
import { ref } from 'vue'
import PinInput from './components/ui/pin-input/PinInput.vue'

const code = ref('')
const messages = { character: (index: number, total: number) => `Digit ${index} of ${total}` }
function verify() {
  console.log(code.value)
}
</script>
<template>
  <span id="code-label">Verification code</span>
  <PinInput
    v-model="code"
    name="code"
    aria-labelledby="code-label"
    :length="6"
    :messages="messages"
    @complete="verify"
  />
</template>

Masked access code

Application validation still decides whether the value is acceptable.

Masked access code
<script setup lang="ts">
import { ref } from 'vue'
import PinInput from './components/ui/pin-input/PinInput.vue'

const code = ref('')
const messages = { character: (index: number, total: number) => `Digit ${index} of ${total}` }
</script>
<template>
  <span id="access-label">Access code</span>
  <PinInput
    v-model="code"
    aria-labelledby="access-label"
    :length="4"
    mask
    required
    :messages="messages"
  />
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

PinInput

Complete API for PinInput
NameType or signatureDefaultWhat it does
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
namepropstring | undefinedNot setName used when this control submits a value with a form.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
lengthpropnumber | undefined6Number of input cells or visible items.
typeprop"text" | "numeric" | undefined"numeric"Choose the native HTML control type or action behavior.
maskpropboolean | undefinedNot setPattern used to display or restrict entered characters.
autocompletepropstring | undefined"one-time-code"Tell the browser which saved value can fill this field.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
readonlypropboolean | undefinedNot setShow the value while preventing edits.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
messagespropPinInputMessagesRequiredSupply the text this component displays for its built-in actions and states.
modelValuemodelstring | undefined""Current value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: string]—Requests a new model value from the parent.
completeevent[value: string]—Emitted when complete happens.
errorslot{ message: string; messages: string[]; }OptionalContent for the error area of PinInput.
focusexposed() => void—Move keyboard focus to this control.
inputsexposedHTMLInputElement[] | null—Access inputs from a component template ref.
Public type definitions
Public types
// packages/frameworks/vue/components/pin-input/types.ts
// ------- IMPORTS -------

import type { ControlSize } from '@getweini/vue/types'

// ------- TYPES -------

export interface PinInputMessages {
  character: (index: number, total: number) => string
}

export interface PinInputProps {
  id?: string
  name?: string
  form?: string
  length?: number
  type?: 'numeric' | 'text'
  mask?: boolean
  autocomplete?: string
  required?: boolean
  disabled?: boolean
  readonly?: boolean
  invalid?: boolean
  size?: ControlSize
  messages: PinInputMessages
}


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • The complete event fires when interaction fills every cell; verify the value on the server.
  • Named forms reserve two lines below the digits for validation feedback. Longer messages wrap and expand without clipping.
  • The hidden form input serializes the whole code. Required completeness needs application validation.

Accessibility and localization

  • Name the whole group and localize the per-cell character labels. Associate errors with aria-describedby.

Source contract and editing guidance