Components
Pin input

Pin Input

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

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:

<script setup lang="ts">
import { PinInput } from '@ark-ui/vue/pin-input'
</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.

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

<template>
  <PinInput.Root :model-value="['1', '2', '3']">
    <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>

Changing the placeholder

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

<script setup lang="ts">
import { PinInput } from '@ark-ui/vue/pin-input'
</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.

<script setup lang="ts">
import { PinInput } from '@ark-ui/vue/pin-input'
</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.

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

<template>
  <PinInput.Root otp>
    <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>

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.

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

<template>
  <PinInput.Root mask>
    <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>

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".

Using the Field Component

The Field component helps manage form-related state and accessibility attributes of a pin input. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

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

<template>
  <Field.Root>
    <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>
    <Field.HelperText>Additional Info</Field.HelperText>
    <Field.ErrorText>Error Info</Field.ErrorText>
  </Field.Root>
</template>

Using the Root Provider

The RootProvider component provides a context for the pin-input. It accepts the value of the usePin-input hook. You can leverage it to access the component state and methods from outside the pin-input.

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

const pinInput = usePinInput()
</script>

<template>
  <button @click="pinInput.focus()">Focus</button>

  <PinInput.RootProvider :value="pinInput">
    <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.RootProvider>
</template>

If you're using the RootProvider component, you don't need to use the Root component.

API Reference

Root

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
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`

modelValue
string[]

name
string

The name of the input element. Useful for form submission.

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

readOnly
boolean

Whether the pin input is in the valid state

required
boolean

Whether the pin input is required

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'
'numeric' | 'alphabetic' | 'alphanumeric'

The type of value the pin-input should allow

EmitEvent
update:modelValue
[value: string[]]

The callback fired when the model value changes.

valueChange
[details: ValueChangeDetails]

Function called on input change

valueComplete
[details: ValueChangeDetails]

Function called when all inputs have valid values

valueInvalid
[details: ValueInvalidDetails]

Function called when an invalid value is entered

Data AttributeValue
[data-scope]pin-input
[data-part]root
[data-invalid]Present when invalid
[data-disabled]Present when disabled
[data-complete]Present when the pin-input value is complete
[data-readonly]Present when read-only

Control

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

HiddenInput

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Input

PropDefaultType
index
number

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]pin-input
[data-part]input
[data-disabled]Present when disabled
[data-complete]Present when the input value is complete
[data-invalid]Present when invalid

Label

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]pin-input
[data-part]label
[data-invalid]Present when invalid
[data-disabled]Present when disabled
[data-complete]Present when the label value is complete
[data-readonly]Present when read-only

RootProvider

PropDefaultType
value
MachineApi<PropTypes>

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Accessibility

Keyboard Support

KeyDescription
ArrowLeft
Moves focus to the previous input
ArrowRight
Moves focus to the next input
Backspace
Deletes the value in the current input and moves focus to the previous input
Delete
Deletes the value in the current input
Control + V
Pastes the value into the input fields