TextField 文本输入框

用法

import { TextField } from '@heroui/react';

组件结构

import {TextField, Label, Input, Description, FieldError} from '@heroui/react';

export default () => (
  <TextField>
    <Label />
    <Input />
    <Description />
    <FieldError />
  </TextField>
)

TextField 将标签、输入、说明与错误信息整合为单个无障碍组件。若只需独立输入，请使用 Input 或 TextArea。

示例

表面样式

在 Surface 内使用时，请在 Input 或 TextArea 组件上使用 variant="secondary"，以应用适合表面背景的低强调变体。

带描述

必填字段

禁用状态

宽度充满

表单校验

将 isInvalid 与 FieldError 配合使用，以展示校验消息。

受控组件

控制 value 以同步计数器、预览或格式化逻辑。

错误信息

文本域

多行内容请使用 TextArea，而非 Input。

Input 类型

渲染函数

自定义样式

Tailwind CSS

全局 CSS

若要自定义组件类，可使用 @layer components 指令。了解更多。

@layer components {
  .textfield {
    @apply flex flex-col gap-1;
  }

  /* When invalid, the description is hidden automatically */
  .textfield[data-invalid="true"] [data-slot="description"],
  .textfield[aria-invalid="true"] [data-slot="description"] {
    @apply hidden;
  }

  /* Description has default padding */
  .textfield [data-slot="description"] {
    @apply px-1;
  }
}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

• .textfield – 根容器，样式极少（flex flex-col gap-1）

提示： 子组件（Label、Input、TextArea、Description、FieldError）各自拥有 CSS 类与样式，定制方式请参见对应文档。

交互状态

TextField 会根据状态自动管理以下 data 属性：

• 无效：[data-invalid="true"] 或 [aria-invalid="true"] — 无效时自动隐藏 description 插槽
• 禁用：[data-disabled="true"] — 在 isDisabled 为 true 时应用
• 焦点在内部：[data-focus-within="true"] — 任一子级 input 聚焦时应用
• 可见焦点：[data-focus-visible="true"] — 键盘导航产生可见焦点时应用

更多属性可通过 render prop 获取（见下文 TextFieldRenderProps）。

API 参考

TextField

继承 React Aria TextField 的全部 props。

Base Props

Validation Props

Value Props

State Props

Form Props

Accessibility Props

Composition Components

TextField 与以下独立组件配合使用，请直接按需引入并组合：

• Label — @heroui/react 的字段标签组件
• Input — @heroui/react 的单行文本输入
• TextArea — @heroui/react 的多行文本输入
• Description — @heroui/react 的辅助说明组件
• FieldError — @heroui/react 的校验错误信息组件

这些组件各自有独立的 props API，请在 TextField 内直接使用：

<TextField isRequired isInvalid={hasError}>
  <Label>Email Address</Label>
  <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
  <Description>We'll never share your email.</Description>
  <FieldError>Please enter a valid email address.</FieldError>
</TextField>

TextFieldRenderProps

对 className、style 或 children 使用渲染 prop 时，可使用以下值：

相关案例

相关组件