` element.
**Root Props:**
| Prop | Type | Default | Description |
| :-------------- | :---------------------------------------------------------------------------------------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | `string` | - | Identifies the field when a form is submitted. |
| defaultValue | `string` | - | The uncontrolled OTP value when the component is initially rendered. |
| value | `string` | - | The OTP value. |
| onValueChange | `((value: string, eventDetails: OTPFieldPreview.Root.ChangeEventDetails) => void)` | - | 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 |
| autoComplete | `string` | `'one-time-code'` | The input autocomplete attribute. Applied to the first slot and hidden validation input. |
| autoSubmit | `boolean` | `false` | Whether to submit the owning form when the OTP becomes complete. |
| form | `string` | - | 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. |
| inputMode | `'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'` | - | 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\* | `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 | `boolean` | `false` | Whether the slot inputs should mask entered characters.
Pass `type` directly to individual `
` parts to use a custom
input type. |
| onValueComplete | `((value: string, eventDetails: OTPFieldPreview.Root.CompleteEventDetails) => void)` | - | Callback function that is fired when the OTP value becomes complete. It runs later than `onValueChange`, after the internal value update is applied. If `autoSubmit` is enabled, it runs immediately before the owning form is submitted. |
| onValueInvalid | `((value: string, eventDetails: OTPFieldPreview.Root.InvalidEventDetails) => void)` | - | Callback fired when entered text contains characters that are rejected by sanitization,
before the OTP value updates. The `value` argument is the attempted user-entered string before sanitization. |
| sanitizeValue | `((value: string) => string)` | - | Function for custom sanitization when `validationType` is set to `'none'`.
This function runs before updating the OTP value from user interactions. |
| validationType | `OTPFieldPreview.Root.ValidationType` | `'numeric'` | The type of input validation to apply to the OTP value. |
| disabled | `boolean` | `false` | Whether the component should ignore user interaction. |
| readOnly | `boolean` | `false` | Whether the user should be unable to change the field value. |
| required | `boolean` | `false` | Whether the user must enter a value before submitting a form. |
| id | `string` | - | The id of the first input element.
Subsequent inputs derive their ids from it (`{id}-2`, `{id}-3`, and so on). |
| className | `string \| ((state: OTPFieldRootState) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: OTPFieldRootState) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | `ReactElement \| ((props: HTMLProps, state: OTPFieldRootState) => ReactElement)` | - | 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. |
**Root Data Attributes:**
| Attribute | Type | Description |
| :------------ | :--- | :--------------------------------------------------------------------------- |
| data-disabled | - | Present when the OTP field is disabled. |
| data-readonly | - | Present when the OTP field is readonly. |
| data-required | - | Present when the OTP field is required. |
| data-valid | - | Present when the OTP field is in valid state (when wrapped in Field.Root). |
| data-invalid | - | Present when the OTP field is in invalid state (when wrapped in Field.Root). |
| data-dirty | - | Present when the OTP field's value has changed (when wrapped in Field.Root). |
| data-touched | - | Present when the OTP field has been touched (when wrapped in Field.Root). |
| data-complete | - | Present when all slots are filled. |
| data-filled | - | Present when the OTP field contains at least one character. |
| data-focused | - | Present when one of the OTP field inputs is focused. |
### Root.Props
Re-export of [Root](/react/components/otp-field.md) props.
### Root.State
```typescript
type OTPFieldPreviewRootState = {
/** Whether all slots are filled. */
complete: boolean;
/** Whether the component should ignore user interaction. */
disabled: boolean;
/** The number of OTP input slots. */
length: number;
/** Whether the user should be unable to change the field value. */
readOnly: boolean;
/** Whether the user must enter a value before submitting a form. */
required: boolean;
/** The OTP value. */
value: string;
/** Whether the field has been touched. */
touched: boolean;
/** Whether the field value has changed from its initial value. */
dirty: boolean;
/** Whether the field is valid. */
valid: boolean | null;
/** Whether the field has a value. */
filled: boolean;
/** Whether the field is focused. */
focused: boolean;
};
```
### Root.ChangeEventReason
```typescript
type OTPFieldPreviewRootChangeEventReason =
| 'input-change'
| 'input-clear'
| 'input-paste'
| 'keyboard';
```
### Root.ChangeEventDetails
```typescript
type OTPFieldPreviewRootChangeEventDetails = (
| { reason: 'input-change'; event: InputEvent | Event }
| { reason: 'input-clear'; event: InputEvent | Event | FocusEvent }
| { reason: 'input-paste'; event: ClipboardEvent }
| { reason: 'keyboard'; event: KeyboardEvent }
) & {
/** Cancels Base UI from handling the event. */
cancel: () => void;
/** Allows the event to propagate in cases where Base UI will stop the propagation. */
allowPropagation: () => void;
/** Indicates whether the event has been canceled. */
isCanceled: boolean;
/** Indicates whether the event is allowed to propagate. */
isPropagationAllowed: boolean;
/** The element that triggered the event, if applicable. */
trigger: Element | undefined;
};
```
### Root.CompleteEventDetails
```typescript
type OTPFieldPreviewRootCompleteEventDetails =
| { reason: 'input-change'; event: InputEvent | Event }
| { reason: 'input-paste'; event: ClipboardEvent }
| { reason: 'keyboard'; event: KeyboardEvent };
```
### Root.CompleteEventReason
```typescript
type OTPFieldPreviewRootCompleteEventReason = 'input-change' | 'input-paste' | 'keyboard';
```
### Root.InvalidEventDetails
```typescript
type OTPFieldPreviewRootInvalidEventDetails =
| { reason: 'input-change'; event: InputEvent | Event }
| { reason: 'input-paste'; event: ClipboardEvent };
```
### Root.InvalidEventReason
```typescript
type OTPFieldPreviewRootInvalidEventReason = 'input-change' | 'input-paste';
```
### Root.ValidationType
```typescript
type OTPFieldPreviewRootValidationType = 'numeric' | 'alpha' | 'alphanumeric' | 'none';
```
### Input
An individual OTP character input.
Renders an `` element.
**Separator Props:**
| Prop | Type | Default | Description |
| :---------- | :------------------------------------------------------------------------------------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| orientation | `Orientation` | `'horizontal'` | The orientation of the separator. |
| className | `string \| ((state: SeparatorState) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: SeparatorState) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | `ReactElement \| ((props: HTMLProps, state: SeparatorState) => ReactElement)` | - | 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. |
### Separator.Props
Re-export of [Separator](/react/components/otp-field.md) props.
### Separator.State
```typescript
type OTPFieldPreviewSeparatorState = {
/** The orientation of the separator. */
orientation: Orientation;
};
```
## Additional Types
### OTPFieldInputProps
```typescript
type OTPFieldInputProps = {
/**
* CSS class applied to the element, or a function that
* returns a class based on the component's state.
*/
className?: string | ((state: OTPFieldInputState) => string | 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.
*/
render?: ReactElement | ((props: HTMLProps, state: OTPFieldInputState) => ReactElement);
/**
* Style applied to the element, or a function that
* returns a style object based on the component's state.
*/
style?: React.CSSProperties | ((state: OTPFieldInputState) => React.CSSProperties | undefined);
};
```
### OTPFieldInputState
```typescript
type OTPFieldInputState = {
/** Whether this input contains a character. */
filled: boolean;
/** The input index. */
index: number;
/** The character rendered in this slot. */
value: string;
/** Whether the component should ignore user interaction. */
disabled: boolean;
/** The number of OTP input slots. */
length: number;
/** Whether the user must enter a value before submitting a form. */
required: boolean;
/** Whether the user should be unable to change the field value. */
readOnly: boolean;
/** Whether all slots are filled. */
complete: boolean;
/** Whether the field has been touched. */
touched: boolean;
/** Whether the field value has changed from its initial value. */
dirty: boolean;
/** Whether the field is valid. */
valid: boolean | null;
/** Whether the field is focused. */
focused: boolean;
};
```
### OTPFieldRootChangeEventReason
```typescript
type OTPFieldRootChangeEventReason = 'input-change' | 'input-clear' | 'input-paste' | 'keyboard';
```
### OTPFieldRootCompleteEventReason
```typescript
type OTPFieldRootCompleteEventReason = 'input-change' | 'input-paste' | 'keyboard';
```
### OTPFieldRootInvalidEventReason
```typescript
type OTPFieldRootInvalidEventReason = 'input-change' | 'input-paste';
```
### OTPFieldRootProps
```typescript
type OTPFieldRootProps = {
/**
* The id of the first input element.
* Subsequent inputs derive their ids from it (`{id}-2`, `{id}-3`, and so on).
*/
id?: string;
/**
* The input autocomplete attribute. Applied to the first slot and hidden validation input.
* @default 'one-time-code'
*/
autoComplete?: string;
/**
* 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.
*/
form?: string;
/**
* The number of OTP input slots.
* Required so the root can clamp values, detect completion, and generate
* consistent validation markup before all slots hydrate.
*/
length: number;
/**
* Whether to submit the owning form when the OTP becomes complete.
* @default false
*/
autoSubmit?: boolean;
/**
* Whether the slot inputs should mask entered characters.
* Pass `type` directly to individual `` parts to use a custom
* input type.
* @default false
*/
mask?: boolean;
/**
* 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.
*/
inputMode?: 'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal' | 'search';
/**
* The type of input validation to apply to the OTP value.
* @default 'numeric'
*/
validationType?: OTPFieldRoot.ValidationType;
/**
* Function for custom sanitization when `validationType` is set to `'none'`.
* This function runs before updating the OTP value from user interactions.
*/
sanitizeValue?: (value: string) => string;
/**
* Whether the user must enter a value before submitting a form.
* @default false
*/
required?: boolean;
/**
* Whether the component should ignore user interaction.
* @default false
*/
disabled?: boolean;
/**
* Whether the user should be unable to change the field value.
* @default false
*/
readOnly?: boolean;
/** Identifies the field when a form is submitted. */
name?: string;
/** The OTP value. */
value?: string;
/** The uncontrolled OTP value when the component is initially rendered. */
defaultValue?: string;
/**
* 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
*/
onValueChange?: (value: string, eventDetails: OTPFieldRoot.ChangeEventDetails) => void;
/**
* Callback fired when entered text contains characters that are rejected by sanitization,
* before the OTP value updates.
*
* The `value` argument is the attempted user-entered string before sanitization.
*/
onValueInvalid?: (value: string, eventDetails: OTPFieldRoot.InvalidEventDetails) => void;
/**
* Callback function that is fired when the OTP value becomes complete.
*
* It runs later than `onValueChange`, after the internal value update is applied.
*
* If `autoSubmit` is enabled, it runs immediately before the owning form is submitted.
*/
onValueComplete?: (value: string, eventDetails: OTPFieldRoot.CompleteEventDetails) => void;
/**
* CSS class applied to the element, or a function that
* returns a class based on the component's state.
*/
className?: string | ((state: OTPFieldRootState) => string | undefined);
/**
* Style applied to the element, or a function that
* returns a style object based on the component's state.
*/
style?: React.CSSProperties | ((state: OTPFieldRootState) => React.CSSProperties | 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.
*/
render?: ReactElement | ((props: HTMLProps, state: OTPFieldRootState) => ReactElement);
};
```
### OTPFieldRootState
```typescript
type OTPFieldRootState = {
/** Whether all slots are filled. */
complete: boolean;
/** Whether the component should ignore user interaction. */
disabled: boolean;
/** The number of OTP input slots. */
length: number;
/** Whether the user should be unable to change the field value. */
readOnly: boolean;
/** Whether the user must enter a value before submitting a form. */
required: boolean;
/** The OTP value. */
value: string;
/** Whether the field has been touched. */
touched: boolean;
/** Whether the field value has changed from its initial value. */
dirty: boolean;
/** Whether the field is valid. */
valid: boolean | null;
/** Whether the field has a value. */
filled: boolean;
/** Whether the field is focused. */
focused: boolean;
};
```
## External Types
### ValidationType
```typescript
type ValidationType = 'numeric' | 'alpha' | 'alphanumeric' | 'none';
```
### Orientation
```typescript
type Orientation = 'horizontal' | 'vertical';
```
## Export Groups
- `OTPFieldPreview.Root`: `OTPFieldPreview.Root`, `OTPFieldPreview.Root.State`, `OTPFieldPreview.Root.Props`, `OTPFieldPreview.Root.ValidationType`, `OTPFieldPreview.Root.ChangeEventReason`, `OTPFieldPreview.Root.ChangeEventDetails`, `OTPFieldPreview.Root.InvalidEventReason`, `OTPFieldPreview.Root.InvalidEventDetails`, `OTPFieldPreview.Root.CompleteEventReason`, `OTPFieldPreview.Root.CompleteEventDetails`
- `OTPFieldPreview.Input`: `OTPFieldPreview.Input`, `OTPFieldPreview.Input.State`, `OTPFieldPreview.Input.Props`
- `OTPFieldPreview.Separator`: `OTPFieldPreview.Separator`, `OTPFieldPreview.Separator.Props`, `OTPFieldPreview.Separator.State`
- `Default`: `OTPFieldRootProps`, `OTPFieldRootState`, `OTPFieldRootChangeEventReason`, `OTPFieldRootChangeEventDetails`, `OTPFieldRootInvalidEventReason`, `OTPFieldRootInvalidEventDetails`, `OTPFieldRootCompleteEventReason`, `OTPFieldRootCompleteEventDetails`, `OTPFieldInputState`, `OTPFieldInputProps`
## Canonical Types
Maps `Canonical`: `Alias` — Use Canonical when its namespace is already imported; otherwise use Alias.
- `OTPFieldRoot.ChangeEventDetails`: `OTPFieldRootChangeEventDetails`
- `OTPFieldRoot.InvalidEventDetails`: `OTPFieldRootInvalidEventDetails`
- `OTPFieldRoot.CompleteEventDetails`: `OTPFieldRootCompleteEventDetails`