Pin Input

For pin or verification codes with auto-focus transfer and masking options.

Pin Input

Anatomy

To set up the pin input correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the PinInput component in your project. Let's take a look at the most basic example:

import { PinInput } from '@ark-ui/react'

export const Basic = () => (
  <PinInput.Root onValueComplete={(e) => alert(e.valueAsString)}>
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Control>
      {[0, 1, 2].map((id, index) => (
        <PinInput.Input key={id} index={index} />
      ))}
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
)

import { Index } from 'solid-js'
import { PinInput } from '@ark-ui/solid'

export const Basic = () => (
  <PinInput.Root onValueComplete={(e) => alert(e.valueAsString)}>
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Control>
      <Index each={[0, 1, 2]}>{(id) => <PinInput.Input index={id()} />}</Index>
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
)

<script setup lang="ts">
import { PinInput } from '@ark-ui/vue'
</script>

<template>
  <PinInput.Root>
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Control>
      <PinInput.Input v-for="id in [0, 1, 2]" :key="id" :index="id" />
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
</template>

Setting a default value

To set the initial value of the pin input, set the defaultValue prop.

Example not found

Example not found

Example not found

Changing the placeholder

To customize the default pin input placeholder ○ for each input, pass the placeholder prop and set it to your desired value.

import { PinInput } from '@ark-ui/react'

export const Customized = () => (
  <PinInput.Root placeholder="*">
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Control>
      {[0, 1, 2].map((id, index) => (
        <PinInput.Input key={id} index={index} />
      ))}
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
)

import { Index } from 'solid-js'
import { PinInput } from '@ark-ui/solid'

export const Customized = () => (
  <PinInput.Root placeholder="*">
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Control>
      <Index each={[0, 1, 2]}>{(id) => <PinInput.Input index={id()} />}</Index>
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
)

<script setup lang="ts">
import { PinInput } from '@ark-ui/vue'
</script>

<template>
  <PinInput.Root placeholder="*">
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Control>
      <PinInput.Input v-for="id in [0, 1, 2]" :key="id" :index="id" />
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
</template>

Blur on complete

By default, the last input maintains focus when filled, and we invoke the onValueComplete callback. To blur the last input when the user completes the input, set the prop blurOnComplete to true.

import { PinInput } from '@ark-ui/react'

export const Blurred = () => (
  <PinInput.Root blurOnComplete>
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Control>
      {[0, 1, 2].map((id, index) => (
        <PinInput.Input key={id} index={index} />
      ))}
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
)

import { Index } from 'solid-js'
import { PinInput } from '@ark-ui/solid'

export const Blurred = () => (
  <PinInput.Root blurOnComplete>
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Control>
      <Index each={[0, 1, 2]}>{(id) => <PinInput.Input index={id()} />}</Index>
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
)

<script setup lang="ts">
import { PinInput } from '@ark-ui/vue'
</script>

<template>
  <PinInput.Root blurOnComplete>
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Control>
      <PinInput.Input v-for="id in [0, 1, 2]" :key="id" :index="id" />
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
</template>

Using OTP mode

To trigger smartphone OTP auto-suggestion, it is recommended to set the autocomplete attribute to "one-time-code". The pin input component provides support for this automatically when you set the otp prop to true.

Example not found

Example not found

Example not found

Securing the text input

When collecting private or sensitive information using the pin input, you might need to mask the value entered, similar to <input type="password"/>. Pass the mask prop to true.

Example not found

Example not found

Example not found

Listening for changes

The pin input component invokes several callback functions when the user enters:

onValueChange — Callback invoked when the value is changed.
onValueComplete — Callback invoked when all fields have been completed (by typing or pasting).
onValueInvalid — Callback invoked when an invalid value is entered into the input. An invalid value is any value that doesn't match the specified "type".

API Reference

Root

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.
`autoFocus`		`boolean` Whether to auto-focus the first input.
`blurOnComplete`		`boolean` Whether to blur the input when the value is complete
`defaultValue`		`string[]` The initial value of the pin input when it is first rendered. Use when you do not need to control the state of the pin input
`disabled`		`boolean` Whether the inputs are disabled
`form`		`string` The associate form of the underlying input element.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string hiddenInput: string label: string control: string input(id: string): string }>` The ids of the elements in the pin input. Useful for composition.
`invalid`		`boolean` Whether the pin input is in the invalid state
`mask`		`boolean` If `true`, the input's value will be masked just like `type=password`
`name`		`string` The name of the input element. Useful for form submission.
`onValueChange`		`(details: ValueChangeDetails) => void` Function called on input change
`onValueComplete`		`(details: ValueChangeDetails) => void` Function called when all inputs have valid values
`onValueInvalid`		`(details: ValueInvalidDetails) => void` Function called when an invalid value is entered
`otp`		`boolean` If `true`, the pin input component signals to its fields that they should use `autocomplete="one-time-code"`.
`pattern`		`string` The regular expression that the user-entered input value is checked against.
`placeholder`		`string` The placeholder text for the input
`selectOnFocus`		`boolean` Whether to select input value when input is focused
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`type`		`'numeric' \| 'alphabetic' \| 'alphanumeric'` The type of value the pin-input should allow
`value`		`string[]` The value of the the pin input.

Control

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.

HiddenInput

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.

Input

Prop	Default	Type
`index`		`number`
`asChild`		`boolean` Render as a different element type.

Label

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.