InputOtp

基础表单

基于 Bootstrap 5 的验证码输入组件，以多个单字符输入格收集一次性验证码，支持输入自动跳格、空格退格回退、方向键与 Home/End 定位、粘贴分发填充，提供数字模式校验、掩码输入、分隔符、校验状态、完成回调、受控模式与隐藏域表单提交，配合 InputOtpSlot / useInputOtp 可自定义槽位组合

Component Demo

Basic usage and examples of the InputOtp component

基础用法

默认渲染 6 个单字符输入格，输入后自动跳至下一格；空格退格会回退并清除上一格，支持左右方向键与 Home/End 快速定位

位数与分隔符

---

length 控制槽位数量；separator 渲染在相邻槽位之间，可用于形如「xxxx-xxxx」的掩码格式

数字模式与校验

inputMode 在移动端唤起数字键盘；pattern 为单字符正则，不匹配的输入与粘贴字符会被自动过滤

掩码输入

password 开启后每个槽位以密码掩码显示输入内容

尺寸

size 提供 sm、lg 两种尺寸，槽位宽度与字号随 form-control 尺寸类同步缩放

状态

支持 disabled 禁用、readOnly 只读，以及 isInvalid / isValid 校验状态样式；单字符槽位会自动隐藏校验图标，状态通过边框颜色体现

粘贴填充

复制验证码 246813，粘贴到任意输入格可一次性填充从该格开始的剩余槽位；超出的字符与不匹配 pattern 的字符会被丢弃

受控模式

传入 value 后组件不再维护内部状态，值完全由外部控制，onChange 反馈每次编辑后的完整验证码

完成回调

输入完成后触发 onComplete

onComplete 在验证码从未填满变为填满时触发，适合自动提交或校验场景

自定义插槽

—

children 替换内置槽位后，可通过 useInputOtp 读取 slots 并用 InputOtpSlot 按索引渲染，实现分组、分隔与个性化样式

表单提交

提交后在此显示表单值

name 将完整验证码写入隐藏域随表单提交，可配合 required 参与浏览器原生校验

API Documentation

Complete API reference for the InputOtp component

Props

InputOtp

属性名	类型	默认值	描述
`as`	`ElementType`	`'div'`	渲染的根容器元素类型
`autoComplete`	`string`	`'one-time-code'`	仅应用于第一个槽位的自动填充提示，其余槽位为 `off`，便于短信验证码自动填充
`autoFocus`	`boolean`	`false`	挂载后是否自动聚焦第一个槽位
`children`	`ReactNode`	-	自定义槽位组合内容，传入后替换内置槽位渲染（`name` 隐藏域仍会保留），配合 `useInputOtp` 与 `InputOtpSlot` 使用
`className`	`string`	-	自定义类名，作用于根容器
`defaultValue`	`string`	`''`	非受控模式下的初始验证码值
`disabled`	`boolean`	`false`	是否禁用所有槽位（隐藏域同步禁用）
`inputMode`	`InputHTMLAttributes<HTMLInputElement>['inputMode']`	`'text'`	槽位的虚拟键盘类型，如 `numeric`、`tel` 等
`isInvalid`	`boolean`	`false`	是否为所有槽位应用无效状态样式（`is-invalid`）
`isValid`	`boolean`	`false`	是否为所有槽位应用有效状态样式（`is-valid`）
`length`	`number`	`6`	槽位数量，对应验证码的字符个数
`name`	`string`	-	隐藏域的 `name`，传入后完整验证码随表单提交
`onChange`	`(value: string) => void`	-	验证码值变化时的回调，携带最新的完整值
`onComplete`	`(value: string) => void`	-	验证码从未填满变为填满时触发的回调，携带完整值
`password`	`boolean`	`false`	是否以密码掩码显示槽位内容
`pattern`	`string`	-	单字符校验正则表达式源码（如 `[0-9]`、`[a-zA-Z0-9]`），不匹配的输入与粘贴字符会被过滤
`placeholder`	`string`	`''`	每个槽位的占位符，通常为单个字符
`readOnly`	`boolean`	`false`	是否只读，槽位可聚焦但不可编辑
`required`	`boolean`	`false`	隐藏域的 `required`，空值提交时触发浏览器校验（需配合 `name`）
`separator`	`ReactNode`	-	渲染在相邻槽位之间的分隔内容，如分隔符、图标等
`size`	`InputOtpSize`	-	槽位尺寸，可选 `sm`、`lg`，对应 `form-control-sm`、`form-control-lg`
`value`	`string`	-	受控的验证码值，配合 `onChange` 使用；传入后组件不再维护内部状态
`...rest`	`HTMLAttributes`	-	根容器的所有原生属性（如 `style`、`aria-`、`data-` 等）

InputOtpSlot

属性名	类型	默认值	描述
`className`	`string`	-	自定义类名，可用于槽位的个性化样式
`index`	`number`	-	槽位索引（必填），决定该输入格承载验证码的哪一位；独立使用时渲染为普通表单控件
`...rest`	`InputHTMLAttributes`	-	输入框的其余原生属性（`size`、`type` 除外）；由组件内部维护的 `value`、`onChange`、`onKeyDown`、`onPaste` 等会被覆盖

Type Definitions

InputOtpContextValue

验证码输入上下文值，可通过 `useInputOtp` 获取（不在 `InputOtp` 内返回 `null`）

export interface InputOtpContextValue {
  autoComplete: string;
  disabled: boolean;
  focusSlot: (index: number) => void;
  handleChange: (index: number, event: ChangeEvent<HTMLInputElement>) => void;
  handleKeyDown: (index: number, event: KeyboardEvent<HTMLInputElement>) => void;
  handlePaste: (index: number, event: ClipboardEvent<HTMLInputElement>) => void;
  inputMode?: InputHTMLAttributes<HTMLInputElement>['inputMode'];
  isInvalid: boolean;
  isValid: boolean;
  length: number;
  password: boolean;
  placeholder: string;
  readOnly: boolean;
  registerSlot: (index: number) => (element: HTMLInputElement | null) => void;
  size?: InputOtpSize;
  slots: string[];
}

InputOtpProps

验证码输入组件属性接口

export interface InputOtpProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
  as?: ElementType;
  autoComplete?: string;
  autoFocus?: boolean;
  children?: ReactNode;
  className?: string;
  defaultValue?: string;
  disabled?: boolean;
  inputMode?: InputHTMLAttributes<HTMLInputElement>['inputMode'];
  isInvalid?: boolean;
  isValid?: boolean;
  length?: number;
  name?: string;
  onChange?: (value: string) => void;
  onComplete?: (value: string) => void;
  password?: boolean;
  pattern?: string;
  placeholder?: string;
  readOnly?: boolean;
  required?: boolean;
  separator?: ReactNode;
  size?: InputOtpSize;
  value?: string;
}

InputOtpSize

槽位尺寸类型，对应 `form-control-sm`、`form-control-lg`

export type InputOtpSize = 'lg' | 'sm';

InputOtpSlotProps

单个槽位组件属性接口

export interface InputOtpSlotProps extends Omit<
  InputHTMLAttributes<HTMLInputElement>,
  'size' | 'type'
> {
  className?: string;
  index: number;
}