# Otp

A fixed-length verification code field: one box per character. Focus moves on as the user types, and a pasted code fills every box. The ref points at the first box.

## Use for

- a one-time code input
- an email or SMS verification code
- a TOTP code from an authenticator app

## Practices

- Do: Render it inside `Field.Root` so the label targets the first box and errors mark it invalid.
- Do: Pass `name` when it sits in a plain `<form>`. A hidden input submits the whole code.
- Don't: Build a verification step from it by hand. Use the steps in `src/blocks/verification/`, such as `VerificationCode`.

## API reference

### Otp

A `role="group"` of inputs. Carries `data-status` and `data-disabled`; each box is a `cl-otp-slot`.

Slot: `cl-otp`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` | `6` | The number of boxes. |
| `value` | `string` |  | The code, when controlled. |
| `defaultValue` | `string` | `''` | The code on mount, when uncontrolled. |
| `onValueChange` | `(value: string) => void` |  | Called with the whole code on every change. |
| `onComplete` | `(value: string) => void` |  | Called with the code once every box is filled. |
| `pattern` | `'numeric' \| 'alpha' \| 'alphanumeric'` | `'numeric'` | `numeric`, `alpha` or `alphanumeric`. Other characters are dropped. |
| `mask` | `boolean` | `false` | Masks each box like a password. |
| `status` | `OtpStatus` | `` `error` when the enclosing `Field` is invalid, else `neutral` `` | Colors every box for the outcome: `neutral`, `success` or `error`. |
| `name` | `string` |  | Submits the code under this name through a hidden input. |

## Examples

### A code field

```tsx
<Field.Root>
  <Field.Label>Verification code</Field.Label>
  <Otp onComplete={onSubmitCode} />
</Field.Root>
```

## Related

- `VerificationCode`
- [Field](/docs/components/field.md)
