> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/input.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.

# Input 输入框

输入单行文本，如姓名、邮箱或搜索关键词。


## 基础用法

使用 `FormField` 为输入框提供名称；占位文字不能替代标签。


项目名称

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/basic.tsx"
import { Form, FormField, Input } from '@ifhover/leaf-ui';

export function InputBasic() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="项目名称">
        <Input name="project" placeholder="为你的项目起个名字" />
      </FormField>
    </Form>
  );
}
```

展开代码


## 示例

### 前后缀

通过 `prefix` 和 `suffix` 补充图标或文字。它们作为装饰内容处理，可交互操作应放在输入框外。


搜索项目

域名

.com

affixes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/affixes.tsx"
import { Form, FormField, Input } from '@ifhover/leaf-ui';
import { Search } from 'lucide-react';

export function InputAffixes() {
  return (
    <Form layout="vertical">
      <FormField label="搜索项目">
        <Input prefix={<Search />} placeholder="输入关键词" />
      </FormField>
      <FormField label="域名">
        <Input suffix=".com" placeholder="example" />
      </FormField>
    </Form>
  );
}
```

展开代码

### 密码输入

设置 `type="password"` 隐藏输入内容。通过 `visible` 和 `onVisibleChange` 控制可见状态，`visibilityIcon` 自定义切换图标，`visibilityToggle={false}` 隐藏切换按钮。


密码

受控密码

无切换按钮

password.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/password.tsx"
import { Form, FormField, Input } from '@ifhover/leaf-ui';
import { Eye, EyeOff } from 'lucide-react';
import { useState } from 'react';

export function InputPassword() {
  const [visible, setVisible] = useState(false);
  return (
    <Form layout="vertical">
      <FormField label="密码">
        <Input type="password" placeholder="请输入密码" autoComplete="new-password" />
      </FormField>
      <FormField label="受控密码">
        <Input
          type="password"
          defaultValue="leaf-garden"
          visible={visible}
          onVisibleChange={setVisible}
          visibilityIcon={(shown) => (shown ? <EyeOff size={16} /> : <Eye size={16} />)}
        />
      </FormField>
      <FormField label="无切换按钮">
        <Input type="password" placeholder="不展示切换按钮" visibilityToggle={false} />
      </FormField>
    </Form>
  );
}
```

展开代码

### 清除内容

设置 `allowClear` 显示清除按钮。清除会触发 `onChange`，输入值变为空字符串。


项目名称

当前内容：Leaf Garden

clear.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/clear.tsx"
import { Form, FormField, Input, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function InputClear() {
  const [value, setValue] = useState('Leaf Garden');

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="项目名称">
        <Input value={value} onChange={(event) => setValue(event.target.value)} allowClear />
      </FormField>
      <Text tone="muted" role="status">
        当前内容：{value || '未填写'}
      </Text>
    </Form>
  );
}
```

展开代码

### 字数统计

使用 `showCount` 显示或自定义统计，搭配 `maxLength` 限制输入长度。


默认统计

11 / 30

自定义统计

4 字

count.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/count.tsx"
import { Form, FormField, Input } from '@ifhover/leaf-ui';

export function InputCount() {
  return (
    <Form layout="vertical">
      <FormField label="默认统计">
        <Input defaultValue="Leaf Garden" showCount maxLength={30} />
      </FormField>
      <FormField label="自定义统计">
        <Input defaultValue="Leaf" showCount={(value) => `${value.length} 字`} />
      </FormField>
    </Form>
  );
}
```

展开代码

### 尺寸

提供 `sm`、`md` 和 `lg` 三种尺寸。


小

中

大

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/sizes.tsx"
import { Form, FormField, Input } from '@ifhover/leaf-ui';

export function InputSizes() {
  return (
    <Form layout="vertical">
      <FormField label="小">
        <Input size="sm" placeholder="项目名称" />
      </FormField>
      <FormField label="中">
        <Input size="md" placeholder="项目名称" />
      </FormField>
      <FormField label="大">
        <Input size="lg" placeholder="项目名称" />
      </FormField>
    </Form>
  );
}
```

展开代码

### 状态

`disabled` 禁用交互，`readOnly` 保留可读内容但禁止编辑。`status` 只显示校验外观，不执行校验；错误信息可通过 `FormField` 提供。


只读

禁用

错误

项目名称不能为空。

警告

states.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/states.tsx"
import { Form, FormField, Input } from '@ifhover/leaf-ui';

export function InputStates() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="只读">
        <Input defaultValue="Leaf Garden" readOnly />
      </FormField>
      <FormField label="禁用">
        <Input disabled placeholder="暂时不可编辑" />
      </FormField>
      <FormField label="错误" error="项目名称不能为空。">
        <Input placeholder="请输入项目名称" />
      </FormField>
      <FormField label="警告">
        <Input status="warning" defaultValue="已经存在相似名称" />
      </FormField>
    </Form>
  );
}
```

展开代码

### 受控输入与回车

[](#)
通过 `value` 和 `onChange` 管理内容。`onPressEnter` 在按下 Enter 时触发；输入法组合输入中或键盘事件已被阻止时不会触发。


输入并回车

已提交：等待输入

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/controlled.tsx"
import { Form, FormField, Input, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function InputControlled() {
  const [value, setValue] = useState('');
  const [submitted, setSubmitted] = useState('');
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="输入并回车">
        <Input
          value={value}
          placeholder="输入后按 Enter"
          onChange={(event) => setValue(event.target.value)}
          onPressEnter={() => setSubmitted(value)}
        />
      </FormField>
      <Text tone="muted" role="status">
        已提交：{submitted || '等待输入'}
      </Text>
    </Form>
  );
}
```

展开代码

### 搜索输入

`InputSearch` 在点击搜索按钮或按 Enter 时通过 `onSearch` 返回输入内容。


搜索项目

搜索

搜索内容：未搜索

search.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/search.tsx"
import { Form, FormField, InputSearch, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function InputSearchDemo() {
  const [query, setQuery] = useState('');

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="搜索项目">
        <InputSearch placeholder="输入关键词" enterButton="搜索" onSearch={setQuery} />
      </FormField>
      <Text tone="muted" role="status">
        搜索内容：{query || '未搜索'}
      </Text>
    </Form>
  );
}
```

展开代码

### 输入组合

使用 `InputGroup` 连接相邻控件，并为组合中的每个输入分别提供名称。


网址

group.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input/group.tsx"
import { Form, FormField, Input, InputGroup, Select } from '@ifhover/leaf-ui';
import { useId } from 'react';

export function InputGroupDemo() {
  const protocolId = useId();
  const domainId = useId();

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="网址" htmlFor={domainId}>
        <InputGroup aria-label="网址">
          <Select
            id={protocolId}
            aria-label="协议"
            style={{ width: 110 }}
            defaultValue="https"
            options={[
              { value: 'https', label: 'https://' },
              { value: 'http', label: 'http://' },
            ]}
          />
          <Input id={domainId} aria-label="域名" placeholder="example.com" />
        </InputGroup>
      </FormField>
    </Form>
  );
}
```

展开代码


## API

### Input API

#### 表单接入

设置 `name` 可通过 FormData 读取值。非受控字段随表单重置恢复初始值，受控字段需同步重置应用状态。表单标签、帮助与错误的接入见 [Form](https://ifhover.github.io/leaf-ui/components/form.md)。

| 属性                           | 类型                                                              | 默认值      | 说明                          |
| ---------------------------- | --------------------------------------------------------------- | -------- | --------------------------- |
| `size`                       | `'sm' \| 'md' \| 'lg'`                                          | `'md'`   | 输入框尺寸                       |
| `status`                     | `'error' \| 'warning'`                                          | —        | 校验状态                        |
| `prefix` / `suffix`          | `ReactNode`                                                     | —        | 输入内容前后的装饰性内容                |
| `onPressEnter`               | `KeyboardEventHandler<HTMLInputElement>`                        | —        | 按下回车时触发                     |
| `type`                       | `HTMLInputTypeAttribute`                                        | `'text'` | 输入方式，密码使用 `'password'`      |
| `visibilityToggle`           | `boolean`                                                       | `true`   | 密码输入框展示切换按钮                 |
| `visible` / `defaultVisible` | `boolean`                                                       | `false`  | 受控密码可见状态 / 初始状态             |
| `onVisibleChange`            | `(visible: boolean) => void`                                    | —        | 密码可见状态变化                    |
| `visibilityIcon`             | `(visible: boolean) => ReactNode`                               | —        | 自定义密码切换图标                   |
| `value` / `defaultValue`     | `string \| number \| readonly string[]`                         | —        | 受控值 / 非受控初始值                |
| `onChange`                   | `ChangeEventHandler<HTMLInputElement>`                          | —        | 从 `event.target.value` 读取内容 |
| `disabled` / `readOnly`      | `boolean`                                                       | `false`  | 禁用 / 只读                     |
| `ref`                        | `Ref<HTMLInputElement>`                                         | —        | 输入框引用                       |
| `allowClear`                 | `boolean`                                                       | `false`  | 展示清除按钮                      |
| `onClear`                    | `() => void`                                                    | —        | 清除后触发；onChange 同样触发         |
| `showCount`                  | `boolean \| ((value: string, maxLength?: number) => ReactNode)` | `false`  | 展示或自定义字数统计                  |

### InputSearchProps API

搜索输入框的提交行为与操作参数。

| 属性                 | 类型                                                              | 默认值     | 说明             |
| ------------------ | --------------------------------------------------------------- | ------- | -------------- |
| `size`             | `'sm' \| 'md' \| 'lg'`                                          | `'md'`  | 输入框尺寸。         |
| `status`           | `'error' \| 'warning'`                                          | —       | 显示状态           |
| `prefix`           | `ReactNode`                                                     | —       | 前置内容           |
| `suffix`           | `ReactNode`                                                     | —       | 后置内容           |
| `allowClear`       | `boolean`                                                       | `false` | 显示清除按钮         |
| `onClear`          | `() => void`                                                    | —       | 清除输入后触发        |
| `showCount`        | `boolean \| ((value: string, maxLength?: number) => ReactNode)` | `false` | 显示字数，可自定义渲染    |
| `visibilityToggle` | `boolean`                                                       | `true`  | 显示密码切换按钮       |
| `visible`          | `boolean`                                                       | —       | 受控的密码可见状态      |
| `defaultVisible`   | `boolean`                                                       | `false` | 初始密码可见状态       |
| `onVisibleChange`  | `(visible: boolean) => void`                                    | —       | 密码可见状态变化       |
| `visibilityIcon`   | `(visible: boolean) => ReactNode`                               | —       | 自定义密码切换图标      |
| `onPressEnter`     | `KeyboardEventHandler<HTMLInputElement>`                        | —       | 按下 Enter 时触发   |
| `onSearch`         | `(value: string) => void`                                       | —       | 搜索或按 Enter 时触发 |
| `loading`          | `boolean`                                                       | `false` | 加载状态           |
| `enterButton`      | `ReactNode`                                                     | —       | 搜索按钮文字，省略时展示图标 |

### InputGroupProps API

组合多个输入相关控件的参数。

| 属性        | 类型        | 默认值 | 说明     |
| --------- | --------- | --- | ------ |
| `compact` | `boolean` | —   | 连接相邻控件 |
