# PinInput

`PinInput` is a group of inputs to enter sequence of numeric or alphanumeric values quickly. Its most common use case is entering OTP or confirmation codes received through text messages (SMS), emails, or authenticator apps.

Each input collects one character at a time. When a value is accepted, the focus is moved to the next input, until all fields are filled.

```tsx
import {PinInput} from '@gravity-ui/uikit';
```

## Type

By default, the inputs only accept numeric values. To allow alphanumeric values, set the `type` property to `"alphanumeric"`:

```tsx
<PinInput type="alphanumeric" />
```

## Size

This component comes in four sizes: `s`, `m`, `l`, and `xl`. The default size is `m`.

```tsx
<PinInput size="s" />
<PinInput size="m" />
<PinInput size="l" />
<PinInput size="xl" />
```

## State

If you do not want the user to interact with the component, set the `disabled` property:

```tsx
<PinInput disabled />
```

To show an invalid state of the component, use the `validationState` property with the `"invalid"` value. Optionally, you can set an error message text with the `errorMessage` property:

```tsx
<PinInput validationState="invalid" errorMessage="Incorrect PIN" />
```

## Placeholder

By default, there is no placeholder for inputs. You can set it with the `placeholder` property:

```tsx
<PinInput placeholder="😎" />
```

## Mask

If you need to mask entered values, use the `mask` property. It is similar to the `<input type="password"/>` behavior.

```tsx
<PinInput mask />
```

## OTP

If you want the browser to suggest one-time codes from the outer context (e.g., SMS) set the `otp` property.

## API

- `focus(): void`: Sets focus to the current active input.

## CSS API

| Name                       | Description                                                  |
| :------------------------- | :----------------------------------------------------------- |
| `--g-pin-input-item-width` | Sets the width of each input, unless `responsive` is `true`. |
| `--g-pin-input-item-gap`   | Sets a gap between inputs.                                   |

## Properties

| Name             | Description                                                                                                                                           |                     Type                     |   Default   |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | :---------: |
| apiRef           | Ref to the [API](#api).                                                                                                                               |              `React.RefObject`               |             |
| aria-describedby | `aria-describedby` HTML attribute                                                                                                                     |                   `string`                   |             |
| aria-label       | `aria-label` HTML attribute                                                                                                                           |                   `string`                   |             |
| aria-labelledby  | `aria-labelledby` HTML attribute                                                                                                                      |                   `string`                   |             |
| autoFocus        | Enables or disables focusing on the first input on the initial render.                                                                                |                  `boolean`                   |             |
| className        | `class` HTML attribute                                                                                                                                |                   `string`                   |             |
| defaultValue     | Initial value for an uncontrolled component.                                                                                                          |                  `string[]`                  |             |
| disabled         | Toggles the `disabled` state                                                                                                                          |                  `boolean`                   |             |
| errorMessage     | Error text placed under the bottom-start corner that shares space with the note container. Only visible when `validationState` is set to `"invalid"`. |              `React.ReactNode`               |             |
| id               | `id` HTML attribute prefix for inputs. The resulting ID will also contain the `"-${index}"` part.                                                     |                   `string`                   |             |
| length           | Number of input fields.                                                                                                                               |                   `number`                   |     `4`     |
| mask             | When set to `true`, the input values will be masked as the password field.                                                                            |                  `boolean`                   |             |
| name             | `name` HTML attribute for input.                                                                                                                      |                   `string`                   |             |
| form             | The associate form of the underlying input element.                                                                                                   |                   `string`                   |             |
| note             | An element placed under the bottom-end corner that shares space with the error container.                                                             |              `React.ReactNode`               |             |
| onUpdate         | Callback fired when any of inputs changes.                                                                                                            |         `(value: string[]) => void`          |             |
| onUpdateComplete | Callback fired when any of inputs changes and all of them are filled.                                                                                 |         `(value: string[]) => void`          |             |
| otp              | When set to `true`, adds `autocomplete="one-time-code"` to inputs.                                                                                    |                  `boolean`                   |             |
| placeholder      | Placeholder for inputs                                                                                                                                |                   `string`                   |             |
| qa               | `data-qa` HTML attribute used for testing purposes.                                                                                                   |                   `string`                   |             |
| responsive       | Parent's width distributed evenly between inputs.                                                                                                     |                  `boolean`                   |             |
| size             | Input field size.                                                                                                                                     |           `"s"` `"m"` `"l"` `"xl"`           |    `"m"`    |
| style            | `style` HTML attribute                                                                                                                                |            `React.CSSProperties`             |             |
| type             | Determines which input value types are allowed.                                                                                                       |         `"numeric"` `"alphanumeric"`         | `"numeric"` |
| validationState  | Validation state that affects the component appearance.                                                                                               |                 `"invalid"`                  |             |
| value            | Current value for the controlled component.                                                                                                           |                  `string[]`                  |             |
| `onFocus`        | Callback fired when the component receives focus.                                                                                                     | `(event: React.FocusEvent<Element>) => void` |             |
| `onBlur`         | Callback fired when the component loses focus.                                                                                                        | `(event: React.FocusEvent<Element>) => void` |             |