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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/input.md.

Input 输入框

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

基础用法

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

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 补充图标或文字。它们作为装饰内容处理,可交互操作应放在输入框外。

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
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
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
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
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
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
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
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
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。

属性类型默认值说明
size'sm' | 'md' | 'lg''md'输入框尺寸
status'error' | 'warning'—校验状态
prefix / suffixReactNode—输入内容前后的装饰性内容
onPressEnterKeyboardEventHandler<HTMLInputElement>—按下回车时触发
typeHTMLInputTypeAttribute'text'输入方式,密码使用 'password'
visibilityTogglebooleantrue密码输入框展示切换按钮
visible / defaultVisiblebooleanfalse受控密码可见状态 / 初始状态
onVisibleChange(visible: boolean) => void—密码可见状态变化
visibilityIcon(visible: boolean) => ReactNode—自定义密码切换图标
value / defaultValuestring | number | readonly string[]—受控值 / 非受控初始值
onChangeChangeEventHandler<HTMLInputElement>—从 event.target.value 读取内容
disabled / readOnlybooleanfalse禁用 / 只读
refRef<HTMLInputElement>—输入框引用
allowClearbooleanfalse展示清除按钮
onClear() => void—清除后触发;onChange 同样触发
showCountboolean | ((value: string, maxLength?: number) => ReactNode)false展示或自定义字数统计

InputSearchProps API

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

属性类型默认值说明
size'sm' | 'md' | 'lg''md'输入框尺寸。
status'error' | 'warning'—显示状态
prefixReactNode—前置内容
suffixReactNode—后置内容
allowClearbooleanfalse显示清除按钮
onClear() => void—清除输入后触发
showCountboolean | ((value: string, maxLength?: number) => ReactNode)false显示字数,可自定义渲染
visibilityTogglebooleantrue显示密码切换按钮
visibleboolean—受控的密码可见状态
defaultVisiblebooleanfalse初始密码可见状态
onVisibleChange(visible: boolean) => void—密码可见状态变化
visibilityIcon(visible: boolean) => ReactNode—自定义密码切换图标
onPressEnterKeyboardEventHandler<HTMLInputElement>—按下 Enter 时触发
onSearch(value: string) => void—搜索或按 Enter 时触发
loadingbooleanfalse加载状态
enterButtonReactNode—搜索按钮文字,省略时展示图标

InputGroupProps API

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

属性类型默认值说明
compactboolean—连接相邻控件