> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/input-otp.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# InputOTP 验证码输入

输入和粘贴验证码。

## 基本用法


已完成: —

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input-otp/basic.tsx"
import { InputOTP, Space, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function InputOTPBasic() {
  const [value, setValue] = useState('');
  const [complete, setComplete] = useState('');
  return (
    <Space direction="vertical" align="stretch">
      <InputOTP value={value} onChange={setValue} onComplete={setComplete} />
      <output>
        <Text tone="muted">已完成: {complete || '—'}</Text>
      </output>
    </Space>
  );
}
```

展开代码

## 更多用法


字母与数字

—

隐藏字符禁用

123456

advanced.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input-otp/advanced.tsx"
import { InputOTP, Space, Text } from '@ifhover/leaf-ui';

export function InputOTPOptions() {
  return (
    <Space direction="vertical" align="stretch">
      <Text tone="muted">字母与数字</Text>
      <InputOTP
        mode="alphanumeric"
        length={8}
        separator={(index) => (index === 3 ? <span>—</span> : null)}
      />
      <Text tone="muted">隐藏字符</Text>
      <InputOTP length={4} mask size="lg" />
      <Text tone="muted">禁用</Text>
      <InputOTP defaultValue="123456" disabled />
    </Space>
  );
}
```

展开代码

## 使用说明

保留一个输入控件以支持粘贴和 one-time-code 自动填充。onComplete 表示字符完整；验证码有效性由服务端验证。

## 类型

组装数据、定义回调和使用 ref 时，可以导入这些类型。

```ts
import type { InputOTPProps } from '@ifhover/leaf-ui';
```

## InputOTPProps API

| 属性             | 类型                             | 默认值         | 说明                  |
| -------------- | ------------------------------ | ----------- | ------------------- |
| `length`       | `number`                       | `6`         | 验证码字符数量             |
| `value`        | `string`                       | —           | 受控值                 |
| `defaultValue` | `string`                       | `''`        | 初始值；非受控表单 reset 时恢复 |
| `onChange`     | `(value: string) => void`      | —           | 值变化回调               |
| `onComplete`   | `(value: string) => void`      | —           | 完整输入后触发             |
| `mode`         | `'numeric' \| 'alphanumeric'`  | `'numeric'` | 展示模式或允许的字符          |
| `mask`         | `boolean \| string`            | `false`     | 隐藏字符，可自定义替代字符       |
| `separator`    | `(index: number) => ReactNode` | —           | 按位置插入分隔内容           |
| `size`         | `'sm' \| 'md' \| 'lg'`         | `'md'`      | 尺寸或间距预设             |
| `status`       | `'error' \| 'warning'`         | —           | 显示状态                |