# Pin Input

URL: https://ark-ui.com/docs/components/pin-input
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/pin-input.mdx

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

---

<ComponentPreview id="PinInput" />

## Anatomy

<Anatomy id="pin-input" />

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

## Examples

**Example: basic**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component Basic() {
  <PinInput.Root class={styles.Root}>
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </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.

**Example: custom-placeholder**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component CustomPlaceholder() {
  <PinInput.Root class={styles.Root} placeholder="*">
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </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`.

**Example: blur-on-complete**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component BlurOnComplete() {
  <PinInput.Root class={styles.Root} blurOnComplete>
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </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.

**Example: otp-mode**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component OTPMode() {
  <PinInput.Root class={styles.Root} otp>
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </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`.

**Example: mask**

```ripple
import { PinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component Mask() {
  <PinInput.Root class={styles.Root} mask>
    <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
    <PinInput.Control class={styles.Control}>
      for (const index of [0, 1, 2]; key index) {
        <PinInput.Input class={styles.Input} {index} />
      }
    </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.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { PinInput } from 'ark-ripple/pin-input';
import fieldStyles from 'styles/field.module.css';
import styles from 'styles/pin-input.module.css';

export component WithField() {
  <Field.Root class={fieldStyles.Root}>
    <PinInput.Root class={styles.Root}>
      <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
      <PinInput.Control class={styles.Control}>
        for (const index of [0, 1, 2]; key index) {
          <PinInput.Input class={styles.Input} {index} />
        }
      </PinInput.Control>
      <PinInput.HiddenInput />
    </PinInput.Root>
    <Field.HelperText class={fieldStyles.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={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.

**Example: root-provider**

```ripple
import { PinInput, usePinInput } from 'ark-ripple/pin-input';
import styles from 'styles/pin-input.module.css';

export component RootProvider() {
  const pinInput = usePinInput(
    { onValueComplete: (e: PinInput.ValueChangeDetails) => alert(e.valueAsString) },
  );

  <div class="stack">
    <button onClick={() => @pinInput.focus()}>{'Focus'}</button>

    <PinInput.RootProvider value={pinInput} class={styles.Root}>
      <PinInput.Label class={styles.Label}>{'Label'}</PinInput.Label>
      <PinInput.Control class={styles.Control}>
        for (const index of [0, 1, 2]; key index) {
          <PinInput.Input class={styles.Input} {index} />
        }
      </PinInput.Control>
      <PinInput.HiddenInput />
    </PinInput.RootProvider>
  </div>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether to auto-focus the first input. |
| `blurOnComplete` | `boolean` | No | Whether to blur the input when the value is complete |
| `count` | `number` | No | The number of inputs to render to improve SSR aria attributes.
This will be required in next major version. |
| `defaultValue` | `string[]` | No | 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` | `boolean` | No | Whether the inputs are disabled |
| `form` | `string` | No | The associate form of the underlying input element. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  hiddenInput: string
  label: string
  control: string
  input: (id: string) => string
}>` | No | The ids of the elements in the pin input. Useful for composition. |
| `invalid` | `boolean` | No | Whether the pin input is in the invalid state |
| `mask` | `boolean` | No | If `true`, the input's value will be masked just like `type=password` |
| `name` | `string` | No | The name of the input element. Useful for form submission. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function called on input change |
| `onValueComplete` | `(details: ValueChangeDetails) => void` | No | Function called when all inputs have valid values |
| `onValueInvalid` | `(details: ValueInvalidDetails) => void` | No | Function called when an invalid value is entered |
| `otp` | `boolean` | No | If `true`, the pin input component signals to its fields that they should
use `autocomplete="one-time-code"`. |
| `pattern` | `string` | No | The regular expression that the user-entered input value is checked against. |
| `placeholder` | `string` | No | The placeholder text for the input |
| `readOnly` | `boolean` | No | Whether the pin input is in the valid state |
| `required` | `boolean` | No | Whether the pin input is required |
| `selectOnFocus` | `boolean` | No | Whether to select input value when input is focused |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `type` | `'numeric' | 'alphanumeric' | 'alphabetic'` | No | The type of value the pin-input should allow |
| `value` | `string[]` | No | The controlled value of the the pin input. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pin-input |
| `[data-part]` | input |
| `[data-disabled]` | Present when disabled |
| `[data-complete]` | Present when the input value is complete |
| `[data-index]` | The index of the item |
| `[data-invalid]` | Present when invalid |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePinInputReturn` | Yes |  |
| `asChild` | `boolean` | No | 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

<KeyBindingsTable id="pin-input" />