---
title: "Pin Input"
description: "A short code entered one character to a box, for two-factor and verification codes."
---

Use it for a code of known length that somebody reads off another screen: a two-factor code, an email verification code, a pairing code. Typing fills a box and moves on, `Backspace` steps back, and a pasted code is dealt out across the boxes.

The value is a single string with no gaps, so a character typed in a later box lands in the first empty one.

_Live example of Pin Input — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add pin-input
```

Files written — React: components/ui/pin-input.tsx. Vue: components/ui/pin-input/PinInput.vue, components/ui/pin-input/index.ts.

## Usage

React:

```tsx
import { PinInput } from "@/components/ui/pin-input"
```

Vue:

```ts
import { PinInput } from "@/components/ui/pin-input"
```

## Examples

### Masked

`mask` draws every character as a dot, for a PIN that should not be read over a shoulder. `length` sets the number of boxes.

_Live example of Pin Input — see the page for the rendered demo._

### Alphanumeric

`type="alphanumeric"` accepts letters as well as digits, and `groupSize` draws a separator after every four boxes so a long backup code is easier to copy.

_Live example of Pin Input — see the page for the rendered demo._

### Invalid

`invalid` turns every box's border to the danger colour. Pair it with an error message, and clear it as soon as the code changes: edit the last two digits to `16` to see it pass.

_Live example of Pin Input — see the page for the rendered demo._

## API reference

**`PinInput`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / v-model` | `string` | — | The code so far. In React, leave it undefined and pass `defaultValue` to let the component own it. |
| `onValueChange` | `(value: string) => void` | — | React only. Called on every change; Vue emits `update:modelValue`. |
| `onComplete / @complete` | `(value: string) => void` | — | Called with the code when the last box is filled, and again each time a complete code is changed to a different one. |
| `length` | `number` | `6` | How many characters the code has. |
| `type` | `"numeric" \| "alphanumeric"` | `"numeric"` | `numeric` accepts digits only and asks a phone for its number pad. |
| `mask` | `boolean` | `false` | Draws every character as a dot. |
| `groupSize` | `number` | `0` | Draws a separator after every this-many boxes. `0` draws none. |
| `invalid` | `boolean` | `false` | Turns the borders to the danger colour and sets `aria-invalid` on each box. |
| `disabled` | `boolean` | `false` | Stops every box taking input. |
| `label` | `string` | `"Verification code"` | Accessible name of the group. |
| `name` | `string` | — | Adds a hidden input with this name, so the code posts with a form. |
| `formatCellLabel` | `(state: { position, length, type }) => string` | `defaultPinInputCellLabel` | Builds the accessible name of each box: `Digit 2 of 6`. `position` counts from 1. |

Submit from the complete callback when the code should be checked as soon as it is whole, and keep a visible button for readers who paste a code and expect to confirm it.

## Accessibility

The boxes sit in a `role="group"` named by `label`, and each box announces its position ("Digit 2 of 6"). The first box carries `autocomplete="one-time-code"`, which lets a phone offer the code from a text message. `Left` and `Right` move between boxes following the reading direction, and `Home` and `End` jump to the ends. An error needs words as well as the red border: put the message in a `FieldHelp` with `variant="error"`.

Each box takes its name from `formatCellLabel`. [Translating labels](/docs/translating-labels) lists every English default.

## Tokens

Pin Input reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
