# Pin Input

URL: https://ark-ui.com/docs/components/pin-input
LLM: https://ark-ui.com/llms.txt/components/pin-input

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

---



## Anatomy



```tsx
<PinInput.Root>
  <PinInput.Label />
  <PinInput.Control>
    <PinInput.Input />
  </PinInput.Control>
  <PinInput.HiddenInput />
</PinInput.Root>
```

## Examples

```tsx
import { PinInput } from '@ark-ui/react/pin-input'
import styles from 'styles/pin-input.module.css'

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

### Placeholder

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

```tsx
import { PinInput } from '@ark-ui/react/pin-input'
import styles from 'styles/pin-input.module.css'

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

### 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`.

```tsx
import { PinInput } from '@ark-ui/react/pin-input'
import styles from 'styles/pin-input.module.css'

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

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

```tsx
import { PinInput } from '@ark-ui/react/pin-input'
import styles from 'styles/pin-input.module.css'

export const OTPMode = () => (
  <PinInput.Root className={styles.Root} otp>
    <PinInput.Label className={styles.Label}>Label</PinInput.Label>
    <PinInput.Control className={styles.Control}>
      {[0, 1, 2].map((id, index) => (
        <PinInput.Input key={id} index={index} className={styles.Input} />
      ))}
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
)
```

### Masking

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

```tsx
import { PinInput } from '@ark-ui/react/pin-input'
import styles from 'styles/pin-input.module.css'

export const Mask = () => (
  <PinInput.Root className={styles.Root} mask>
    <PinInput.Label className={styles.Label}>Label</PinInput.Label>
    <PinInput.Control className={styles.Control}>
      {[0, 1, 2].map((id, index) => (
        <PinInput.Input key={id} index={index} className={styles.Input} />
      ))}
    </PinInput.Control>
    <PinInput.HiddenInput />
  </PinInput.Root>
)
```

### Change Events

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

### Field

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.

```tsx
import { Field } from '@ark-ui/react/field'
import { PinInput } from '@ark-ui/react/pin-input'
import fieldStyles from 'styles/field.module.css'
import styles from 'styles/pin-input.module.css'

export const WithField = () => (
  <Field.Root className={fieldStyles.Root}>
    <PinInput.Root className={styles.Root}>
      <PinInput.Label className={styles.Label}>Label</PinInput.Label>
      <PinInput.Control className={styles.Control}>
        {[0, 1, 2].map((id, index) => (
          <PinInput.Input key={id} index={index} className={styles.Input} />
        ))}
      </PinInput.Control>
      <PinInput.HiddenInput />
    </PinInput.Root>
    <Field.HelperText className={fieldStyles.HelperText}>Additional Info</Field.HelperText>
    <Field.ErrorText className={fieldStyles.ErrorText}>Error Info</Field.ErrorText>
  </Field.Root>
)
```

### Root Provider

An alternative way to control the pin input is to use the `RootProvider` component and the `usePinInput` hook. This way
you can access the state and methods from outside the component.

```tsx
import { PinInput, usePinInput } from '@ark-ui/react/pin-input'
import styles from 'styles/pin-input.module.css'

export const RootProvider = () => {
  const pinInput = usePinInput({ onValueComplete: (e) => alert(e.valueAsString) })

  return (
    <div className="stack">
      <button onClick={() => pinInput.focus()}>Focus</button>

      <PinInput.RootProvider value={pinInput} className={styles.Root}>
        <PinInput.Label className={styles.Label}>Label</PinInput.Label>
        <PinInput.Control className={styles.Control}>
          {[0, 1, 2].map((id, index) => (
            <PinInput.Input key={id} index={index} className={styles.Input} />
          ))}
        </PinInput.Control>
        <PinInput.HiddenInput />
      </PinInput.RootProvider>
    </div>
  )
}
```

## API Reference

### Props

### Root

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`autoFocus`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to auto-focus the first input.

**`autoSubmit`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to auto-submit the owning form when all inputs are filled.

**`blurOnComplete`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to blur the input when the value is complete

**`count`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The number of inputs to render to improve SSR aria attributes.
This will be required in next major version.

**`defaultValue`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The initial value of the the pin input when rendered.
Use when you don't need to control the value of the pin input.

**`disabled`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the inputs are disabled

**`form`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The associate form of the underlying input element.

**`id`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The unique identifier of the machine.

**`ids`**
Type: `Partial<{
  root: string
  hiddenInput: string
  label: string
  control: string
  input: (id: string) => string
}>`
Required: false
Default Value: `undefined`
Description: The ids of the elements in the pin input. Useful for composition.

**`invalid`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the pin input is in the invalid state

**`mask`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: If `true`, the input's value will be masked just like `type=password`

**`name`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The name of the input element. Useful for form submission.

**`onValueChange`**
Type: `(details: ValueChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Function called on input change

**`onValueComplete`**
Type: `(details: ValueChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Function called when all inputs have valid values

**`onValueInvalid`**
Type: `(details: ValueInvalidDetails) => void`
Required: false
Default Value: `undefined`
Description: Function called when an invalid value is entered

**`otp`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: If `true`, the pin input component signals to its fields that they should
use `autocomplete="one-time-code"`.

**`pattern`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The regular expression that the user-entered input value is checked against.

**`placeholder`**
Type: `string`
Required: false
Default Value: `"○"`
Description: The placeholder text for the input

**`readOnly`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the pin input is in the valid state

**`required`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the pin input is required

**`sanitizeValue`**
Type: `(value: string) => string`
Required: false
Default Value: `undefined`
Description: Function to sanitize pasted values before validation.
Useful for stripping dashes, spaces, or other formatting.

**`selectOnFocus`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to select input value when input is focused

**`translations`**
Type: `IntlTranslations`
Required: false
Default Value: `undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`type`**
Type: `'numeric' | 'alphanumeric' | 'alphabetic'`
Required: false
Default Value: `"numeric"`
Description: The type of value the pin-input should allow

**`value`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The controlled value of the the pin input.

#### Data Attributes

**`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

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### HiddenInput

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Input

#### Props

**`index`**
Type: `number`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: pin-input
**`data-part`**: input
**`data-disabled`**: Present when disabled
**`data-complete`**: Present when the input value is complete
**`data-filled`**: 
**`data-index`**: The index of the item
**`data-invalid`**: Present when invalid

### Label

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`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-required`**: Present when required
**`data-readonly`**: Present when read-only

### RootProvider

#### Props

**`value`**
Type: `UsePinInputReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `string[]` | The value of the input as an array of strings. |
| `valueAsString` | `string` | The value of the input as a string. |
| `complete` | `boolean` | Whether all inputs are filled. |
| `count` | `number` | The number of inputs to render |
| `items` | `number[]` | The array of input values. |
| `setValue` | `(value: string[]) => void` | Function to set the value of the inputs. |
| `clearValue` | `VoidFunction` | Function to clear the value of the inputs. |
| `setValueAtIndex` | `(index: number, value: string) => void` | Function to set the value of the input at a specific index. |
| `focus` | `VoidFunction` | Function to focus the pin-input. This will focus the first input. |


## Accessibility

### Keyboard Support

**`ArrowLeft`**
Description: Moves focus to the previous input

**`ArrowRight`**
Description: Moves focus to the next input

**`Backspace`**
Description: Deletes the value in the current input and moves focus to the previous input

**`Delete`**
Description: Deletes the value in the current input

**`Control + V`**
Description: Pastes the value into the input fields