# OTP Field (/docs/otp-field)
## API Reference [#api-reference]
## Basic [#basic]
`OTPField` renders input slots automatically from `length`. Use `inputProps` to customize every
automatic slot, `groupSize` for common grouped layouts, or manual children only when the layout
needs arbitrary per-slot markup.
{`
import { Field, FieldLabel, OTPField } from "moduix";
import { useId } from "react";
export function OTPFieldDemo() {
const id = useId();
return (
Verification code
);
}
`}
{(context) => }
{(context) => }
## Anatomy [#anatomy]
`OTPField` owns the field state and renders one input slot for each character in `length`. The
automatic slots are the recommended default because labels, slot count, and basic accessibility
labels stay in one place.
```text
OTPField[length]
├─ OTPFieldInput
├─ OTPFieldInput
├─ OTPFieldSeparator (optional, from groupSize)
└─ OTPFieldInput
```
```tsx
```
| Part | Role |
| ------------------- | ------------------------------------------------------------------------------------------------------ |
| `OTPField` | Root state machine. Controls value, validation, completion callbacks, masking, and automatic slots. |
| `OTPFieldInput` | Visible character slot. Rendered automatically unless custom `children` are provided. |
| `OTPFieldSeparator` | Optional visible separator between groups. Rendered automatically from `groupSize` or manually placed. |
`OTPField` does not use portal-like service layers such as `portal`, `backdrop`, `positioner`, or
`viewport`. In most cases, keep automatic input rendering and style the root or generated inputs
with `className`, `inputProps`, and CSS variables.
## Composition [#composition]
Use `length` for the number of slots. Add `groupSize` when the code should be visually split, for
example `groupSize={3}` for `123-456` or `groupSize={[3, 2]}` for `ABC-DE-F`.
`inputProps` accepts either an object for every generated slot or a function that receives
`index` and `length` for per-slot props. Use `separator` to replace the default separator icon when
`groupSize` is set. For layouts that need arbitrary markup around slots, pass `OTPFieldInput` and
`OTPFieldSeparator` as children manually.
## Examples [#examples]
### Alphanumeric [#alphanumeric]
Use `validationType="alphanumeric"` for recovery, backup, or invite codes that accept letters and numbers.
{`
import {
Field,
FieldDescription,
FieldLabel,
OTPField,
} from "moduix";
import { useId, useState } from "react";
export function AlphanumericOTPField() {
const id = useId();
const [value, setValue] = useState("");
return (
Recovery code
Letters and numbers are allowed, for example A7C9XZ.
);
}
`}
### Grouped Layout [#grouped-layout]
Use `groupSize` when a code should be presented in smaller visual groups.
{`
import {
Field,
FieldLabel,
OTPField,
} from "moduix";
import { useId } from "react";
export function GroupedOTPField() {
const id = useId();
return (
Auth code
);
}
`}
### Placeholder Hints [#placeholder-hints]
Pass native `placeholder` props to the input slots and style them with `className`.
{`
import { Field, FieldDescription, FieldLabel, OTPField } from "moduix";
import { useId } from "react";
import styles from "./otp-field.module.css";
export function PlaceholderOTPField() {
const id = useId();
return (
Verification code
Placeholder hints stay visible until the active slot is focused.
);
}
`}
{`
.placeholderInput {
&::placeholder {
color: var(--color-muted-foreground);
}
&:focus::placeholder {
color: transparent;
}
}
`}
### Masked [#masked]
Use `mask` when the code should be obscured while it is being typed.
{`
import { Field, FieldLabel, OTPField } from "moduix";
import { useId } from "react";
export function MaskedOTPField() {
const id = useId();
return (
PIN
);
}
`}
### Field Validation [#field-validation]
Wrap the control in `Field` to show validation errors from props such as `required`.
{`
import {
Field,
FieldError,
FieldLabel,
OTPField,
} from "moduix";
import { useId } from "react";
export function ValidatedOTPField() {
const id = useId();
return (
Verification code
Please enter the verification code.
);
}
`}
### Auto Submit [#auto-submit]
Use `autoSubmit` to submit the owning form as soon as all slots are filled.
{`
import { Field, FieldDescription, FieldLabel, OTPField } from "moduix";
import { useId, useState } from "react";
export function AutoSubmitOTPField() {
const id = useId();
const [completedValue, setCompletedValue] = useState("");
const [submittedValue, setSubmittedValue] = useState("");
return (
);
}
`}
### Custom Sanitization [#custom-sanitization]
Set `validationType="none"` with `sanitizeValue` when pasted or typed values need custom normalization.
{`
import { Field, FieldDescription, FieldLabel, OTPField } from "moduix";
import { useId, useState } from "react";
export function CustomSanitizationOTPField() {
const id = useId();
const [value, setValue] = useState("");
const [invalidValue, setInvalidValue] = useState("");
return (
Invite code
Last invalid attempt: {invalidValue || "none"}
nextValue.toUpperCase().replace(/[^A-Z0-9]/g, "")}
onValueChange={setValue}
onValueInvalid={setInvalidValue}
/>
);
}
`}
### Custom Separator [#custom-separator]
Style generated slots with `inputProps` and pass any icon to `separator`.
{`
import {
Field,
FieldLabel,
OTPField,
SeparatorMarkIcon,
} from "moduix";
import { useId } from "react";
import styles from "./otp-field.module.css";
export function CustomSeparatorOTPField() {
const id = useId();
return (
Styled code
}
className={styles.customRoot}
/>
);
}
`}
{`
.customInput {
--otp-field-input-width: 3rem;
--otp-field-input-height: 3rem;
--otp-field-font-size: var(--text-xl);
--otp-field-bg-filled: var(--color-muted);
}
.customRoot {
--otp-field-separator-size: 1.5rem;
--otp-field-separator-color: var(--color-primary);
}
`}