# @fayegram-ai/faye-ui/controls/otp-field

Public exports and dependency-resolved component properties, with usage and rendering guidance.

## Import

```tsx
import { OTPField } from '@fayegram-ai/faye-ui/controls/otp-field';
```

[Usage and behavior guide](/docs/numeric/) · [API JSON](/api/packages/controls/otp-field.json)

This entry declares a client boundary. Follow the rendering guide for framework integration.

## Public exports

| Name | Kind | Resolved declaration type |
|---|---|---|
| `OTPField` | value | `{ readonly Root: { (input: Omit<import("@base-ui/react").OTPFieldRootProps, "ref"> & import("react").RefAttributes<HTMLDivElement> & { variants?: {} \| undefined; }): import("react").ReactElement; displayName: string; }; readonly Input: { (input: Omit<import("@base-ui/react").OTPFieldInputProps, "ref"> & import("react").RefAttributes<HTMLInputElement> & { variants?: {} \| undefined; }): import("react").ReactElement; displayName: string; }; readonly Separator: { (input: Omit<import("@base-ui/react").SeparatorProps, "ref"> & import("react").RefAttributes<HTMLDivElement> & { variants?: {} \| undefined; }): import("react").ReactElement; displayName: string; }; }` |

## OTPField

Public component; use the linked family guide for complete composition and behavior.

Dependency-resolved declaration properties. Common React/native HTML attributes are omitted from the table; use the full declaration and React/native references. Generic and union restrictions remain authoritative in TypeScript.

### OTPField.Root

| Property | Required | Type | Meaning |
|---|---|---|---|
| `autoComplete` | No | `string \| undefined` | The input autocomplete attribute. Applied to the first slot and hidden validation input. |
| `autoSubmit` | No | `boolean \| undefined` | Whether to submit the owning form when the OTP becomes complete. |
| `className` | No | `string \| ((state: OTPFieldRootState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `defaultValue` | No | `string \| undefined` | The uncontrolled OTP value when the component is initially rendered. |
| `disabled` | No | `boolean \| undefined` | Whether the component should ignore user interaction. |
| `form` | No | `string \| undefined` | A string specifying the `form` element with which the hidden input is associated. This string's value must match the id of a `form` element in the same document. |
| `id` | No | `string \| undefined` | The id of the first input element. Subsequent inputs derive their ids from it (`{id}-2`, `{id}-3`, and so on). |
| `inputMode` | No | `"text" \| "search" \| "none" \| "tel" \| "url" \| "email" \| "numeric" \| "decimal" \| undefined` | The virtual keyboard hint applied to the slot inputs and hidden validation input. Built-in validation modes provide sensible defaults, but you can override them when needed. |
| `length` | Yes | `number` | The number of OTP input slots. Required so the root can clamp values, detect completion, and generate consistent validation markup before all slots hydrate. |
| `mask` | No | `boolean \| undefined` | Whether the slot inputs should mask entered characters. Pass `type` directly to individual `<OTPField.Input>` parts to use a custom input type. |
| `name` | No | `string \| undefined` | Identifies the field when a form is submitted. |
| `normalizeValue` | No | `((value: string) => string) \| undefined` | Function that normalizes the OTP value after whitespace and `validationType` filtering. It runs whenever OTP Field normalizes a value, including initial/default values, controlled values, and user edits. The returned value is filtered by `validationType` again, then clamped to `length`. It should be idempotent because OTP Field may normalize the same value more than once while handling edits, storing state, and rendering controlled or uncontrolled values. Non-idempotent normalizers can compound across those normalization passes. Characters rejected while normalizing typed or pasted text are reported through `onValueInvalid`. |
| `onValueChange` | No | `((value: string, eventDetails: OTPFieldRoot.ChangeEventDetails) => void) \| undefined` | Callback fired when the OTP value changes. The `eventDetails.reason` indicates what triggered the change: - `'input-change'` for typing or autofill - `'input-clear'` when a character is removed by text input - `'input-paste'` for paste interactions - `'keyboard'` for keyboard interactions that change the value |
| `onValueComplete` | No | `((value: string, eventDetails: OTPFieldRoot.CompleteEventDetails) => void) \| undefined` | Callback function that is fired when the OTP value becomes complete, or when a complete value is pasted while the OTP is already complete. When the value changes, it runs later than `onValueChange`, after the internal value update is applied. If a complete pasted value matches the current value, `onValueChange` does not fire. If `autoSubmit` is enabled, it runs immediately before the owning form is submitted. |
| `onValueInvalid` | No | `((value: string, eventDetails: OTPFieldRoot.InvalidEventDetails) => void) \| undefined` | Callback fired when entered text contains characters that are rejected by validation or normalization before the OTP value updates. The `value` argument is the attempted user-entered string before normalization. |
| `readOnly` | No | `boolean \| undefined` | Whether the user should be unable to change the field value. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, OTPFieldRootState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `required` | No | `boolean \| undefined` | Whether the user must enter a value before submitting a form. |
| `style` | No | `CSSProperties \| ((state: OTPFieldRootState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `validationType` | No | `OTPValidationType \| undefined` | The type of input validation to apply to the OTP value. |
| `value` | No | `string \| undefined` | The OTP value. |
| `variants` | No | `{} \| undefined` | See the usage contract and declaration. |

### OTPField.Input

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: OTPFieldInputState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, OTPFieldInputState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `style` | No | `CSSProperties \| ((state: OTPFieldInputState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{} \| undefined` | See the usage contract and declaration. |

### OTPField.Separator

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: SeparatorState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `orientation` | No | `Orientation \| undefined` | The orientation of the separator. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, SeparatorState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `style` | No | `CSSProperties \| ((state: SeparatorState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{} \| undefined` | See the usage contract and declaration. |

## Defaults and customization

Descriptor defaults: ``. Parts: `root`, `input`, `separator`. Explicit instance props take precedence over configured defaults.

Use semantic tokens, public part hooks and customization sheets. Keep visual configuration separate from application state.

## State, events and accessibility

For interactive controls, pair a controlled value/open prop with its corresponding change callback; default props initialize uncontrolled state. Keep application validation and submission policy explicit. Name controls with visible labels, name icon-only actions on the button, and preserve focus and dismissal behavior when replacing parts. Use native form names and submit/reset types where supported. See the usage guide for component-specific behavior and live examples.

## Declaration authority

Generated from `packages/faye-ui/dist/controls/otp-field.d.ts` after the semantic package build. Common native/React attributes are intentionally omitted from property tables. Generic overloads, discriminated unions and complete inherited attributes remain authoritative in installed TypeScript declarations. [React DOM attributes](https://react.dev/reference/react-dom/components/common) and [Base UI component contracts](https://base-ui.com/react/overview/quick-start) describe the inherited foundations.