# nord-otp-field
> OTP Field is a segmented one-time-code input: it renders length individual
> character cells plus a visually-hidden input that holds the full value, enabling
> SMS / keychain autofill and native pattern/required validation. Typing fills
> and auto-advances, Backspace clears and moves back, the arrow keys navigate, and
> pasting a code distributes its characters across the cells.
>
> OTP Field is a control only — it has no built-in label, hint or error. Compose
> it inside a Field with a Field Label
> (connected with for) to give it an accessible name, helper text and an error
> message, exactly like a native input.
## Usage
OTP Field is a **control only** — it has no built-in label, hint or error. Pair it with a [Field](/components/field/) to give it a label, helper text and an error message, exactly like a native input. Connect the [Field Label](/components/field-label/) to the OTP field with the `for` attribute so it gets an accessible name and click-to-focus. The label names the **first cell** (the OTP field forwards its accessible name onto it), while the remaining cells announce their position (for example, "Character 2 of 6").
Import the OTP field and the Field parts you need — each import registers its custom element:
```js
import '@nordhealth/components/lib/OtpField'
import '@nordhealth/components/lib/Field'
import '@nordhealth/components/lib/FieldLabel'
import '@nordhealth/components/lib/FieldDescription'
import '@nordhealth/components/lib/FieldError'
```
Then compose the Field around the OTP field:
```html
Verification code
Enter the 6-character code we sent to your device.
```
OTP Field renders `length` individual character cells plus a visually-hidden input that holds the full value. The hidden input carries `autocomplete="one-time-code"`, so SMS and keychain one-time-code autofill works, and it carries the native `pattern`, `minlength`, `maxlength` and `required` so form validation works. Typing fills and auto-advances, Backspace clears and moves back, the arrow keys navigate, and pasting a code distributes its characters across the cells.
OTP Field renders in the light DOM, so you can style it directly with your own CSS or Tailwind utilities, and size it with the `size` attribute (`s` | `m` | `l`) or the `--n-otp-field-*` custom properties.
Set `name` to submit the value with a form. The value submits under the host `name`; the inner cell inputs and the hidden input carry no `name`, so the browser never double-submits.
```html
```
Listen for the `complete` event to react when every cell is filled — for example, to submit the form automatically.
```js
document.querySelector('nord-otp-field').addEventListener('complete', (event) => {
console.log('Code entered:', event.value)
})
```
> **Do:** - Use for short verification or one-time codes, such as 2FA, email confirmation, or recovery codes.
- Pair it with a [Field](/components/field/) and a [Field Label](/components/field-label/) connected with `for`, so it has an accessible name, helper text and an error message.
- Use `type="alphanumeric"` for codes that mix letters and digits, and `type="numeric"` for digit-only codes.
- Set `autocomplete="one-time-code"` (the default) so SMS and keychain autofill works.
- Use `mask` when the code should be obscured on shared screens.
> **Don't:** - Don't use for free-form or long text entry, see [Input](/components/input/) instead.
- Don't add a Field Label without a `for` pointing at the OTP field's `id`, or the first cell will have no accessible name.
- Don't use for passwords or secrets longer than a few characters, see [Input](/components/input/) instead.
- Don't change `length` to mismatch the code the user is expected to enter — every cell should map to one character of the code.
## Examples
### Overview
```html
```
### Alphanumeric
```html
```
### Grouped
```html
```
### Custom Normalize
```html
Recovery code
Letters and digits only. Letters are converted to uppercase.
```
### Masked
```html
```
### Form Integration
```html
```
### Invalid
```html
```
### Disabled
```html
```
### Readonly
```html
```
### Placeholder
```html
```
### Right To Left
```html
```
### Standalone
```html
```
### Field
```html
Verification code
Check your email for the code.
```
## API Reference
### Properties
- **length** (`number`, default: `6`) — The number of OTP cells. Must be a positive integer.
- **type** (`OtpFieldType`, default: `'numeric'`) — Controls the allowed characters, inputmode and pattern. numeric accepts
digits; alphanumeric accepts letters and digits.
- **readonly** (`boolean`, default: `false`) — Prevents the user from changing the value while keeping navigation and focus.
- **mask** (`boolean`, default: `false`) — Obscures each cell (renders type="password") for use on shared screens.
- **placeholder** (`string | undefined`) — Placeholder character or string shown in every empty cell.
- **invalid** (`boolean`, default: `false`) — Marks the field invalid, applying error styling and aria-invalid to every
cell and the hidden input. Pair with a nord-field-error in the Field.
- **autocomplete** (`string`, default: `'one-time-code'`) — The autocomplete token applied to the first cell and the hidden input (all
other cells get autocomplete="off"). Defaults to one-time-code to enable
SMS / keychain OTP autofill.
- **group-size** (`number`, default: `0`) — Renders a decorative separator after every N cells (for example, 3 shows
123-456). 0 disables grouping. The separator is aria-hidden and does
not affect the value or navigation.
- **value** (`string`, default: `''`) — The OTP value, for example '123456'. Whitespace is stripped, characters are
filtered by type, and the result is clamped to length. Set programmatically
to prefill.
- **size** (`'s' | 'm' | 'l'`, default: `'m'`) — The size of the component.
- **label** (`string`, default: `''`) — Label for the control. Ignored when the control is wrapped in a
<nord-field>, which provides the label via <nord-field-label>.
- **hint** (`string | undefined`) — Optional hint text shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-description>.
- **hint-below** (`boolean`, default: `false`) — Renders the hint below the control and any error instead of below the label.
- **hide-label** (`boolean`, default: `false`) — Visually hide the label, but still expose it to assistive technologies.
- **error** (`string | undefined`) — Optional error shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-error>.
- **required** (`boolean`, default: `false`) — Determines whether the control is required or not.
A required control is announced as such to assistive technology and, inside
a <nord-field>, drives the required indicator on the <nord-field-label>.
When using this property you need to also set “novalidate” attribute on a form element to prevent browser from displaying its own validation errors.
- **hide-required** (`boolean`, default: `false`) — Visually hide the required indicator, but still expose the required state
to assistive technologies.
- **disabled** (`boolean`, default: `false`) — Makes the component disabled. This prevents users from
being able to interact with the component, and conveys
its inactive state to assistive technologies.
- **name** (`string | undefined`) — The name of the form component.
- **form** (`HTMLFormElement | null`) — Gets the form, if any, associated with the form element.
The setter accepts a string, which is the id of the form.
### Events
- **input** (`NordEvent`) — Dispatched whenever the OTP value changes through user interaction (typing, Backspace/Delete, paste, autofill).
- **change** (`NordEvent`) — Dispatched alongside input when the committed value changes via user interaction.
- **complete** (`OtpFieldCompleteEvent`) — Dispatched after the value updates when every cell becomes filled.
- **value-invalid** (`OtpFieldInvalidEvent`) — Dispatched when typed or pasted text contained characters rejected by type.
### Methods
- **focus** — `focus(options?: FocusOptions) => void` — Focus the field by moving focus into its active cell.
### CSS Custom Properties
- `--n-otp-field-gap` (default: `var(--n-space-s)`) — Gap between cells (and between groups when group-size is used).
- `--n-otp-field-cell-size` (default: `var(--n-space-xl)`) — Controls the block-size and inline-size of each square cell. When unset, size maps to the shared control block sizes.
- `--n-otp-field-background` (default: `var(--n-color-surface)`) — Cell background.
- `--n-otp-field-border-color` (default: `var(--n-color-border-strong)`) — Cell border color (resting).
- `--n-otp-field-border-radius` (default: `var(--n-border-radius-s)`) — Cell corner radius.
- `--n-otp-field-font-size` (default: `var(--n-font-size-m)`) — Cell character font size.