ProComponents, templates & AI tooling
HeroUI
27.7k
快速开始
组件
发布说明
迁移

TextField 文本输入框

便于组合的文本字段，包含标签、说明与内联校验。

FigmaStorybookReact Aria源代码样式源代码

引入

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。

带说明

必填字段

校验

使用 isInvalid 与 FieldError 展示校验信息。

受控

通过受控 value 同步计数器、预览或格式化。

错误信息

禁用状态

TextArea

多行内容请使用 TextArea 替代 Input。

Input 类型

全宽

在 Surface 内

置于 Surface 中时，请在 Input 或 TextArea 上使用 variant="secondary"，以应用适合表面背景的弱强调变体。

自定义渲染函数

样式

传入 Tailwind CSS 类

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

function CustomTextField() {
  return (
    <TextField className="gap-2 rounded-xl border border-border/60 bgsurface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Project name
      </Label>
      <Input className="rounded-lg border border-border/60 bgsurface px-3 py-2" />
      <Description className="text-xs text-default-500">
        Keep it short and memorable.
      </Description>
    </TextField>
  );
}

自定义组件类

TextField 默认样式很少。覆盖 .textfield 类即可自定义容器样式。

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

  /* 无效时自动隐藏说明 */
  .textfield[data-invalid="true"] [data-slot="description"],
  .textfield[aria-invalid="true"] [data-slot="description"] {
    @apply hidden;
  }

  /* Description 默认内边距 */
  .textfield [data-slot="description"] {
    @apply px-1;
  }
}

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 Props

继承 React Aria TextField 的全部 props。

Base Props

Prop类型默认值描述
childrenReact.ReactNode | (values: TextFieldRenderProps) => React.ReactNode-子组件（Label、Input 等）或渲染函数。
classNamestring | (values: TextFieldRenderProps) => string-用于样式的 CSS 类，支持渲染 prop。
styleReact.CSSProperties | (values: TextFieldRenderProps) => React.CSSProperties-行内样式，支持渲染 prop。
fullWidthbooleanfalseTextField 是否占满容器宽度。
idstring-元素的唯一 id。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, TextFieldRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

Validation Props

Prop类型默认值描述
isRequiredbooleanfalse提交表单前是否必须填写。
isInvalidboolean-当前值是否无效。
validate(value: string) => ValidationError | true | null | undefined-自定义校验函数。
validationBehavior'native' | 'aria''native'使用原生 HTML 表单校验还是 ARIA 属性。
validationErrorsstring[]-服务端校验错误。

Value Props

Prop类型默认值描述
valuestring-当前值（受控）。
defaultValuestring-默认值（非受控）。
onChange(value: string) => void-值变化时调用的事件处理函数。

State Props

Prop类型默认值描述
isDisabledboolean-是否禁用输入。
isReadOnlyboolean-是否可选中但不可修改。

Form Props

Prop类型默认值描述
namestring-用于 HTML 表单提交的 input 名称。
autoFocusboolean-是否在挂载时自动聚焦。

Accessibility Props

Prop类型默认值描述
aria-labelstring-无可见标签时的无障碍标签。
aria-labelledbystring-用于标注该字段的元素 id。
aria-describedbystring-用于描述该字段的元素 id。
aria-detailsstring-提供附加详情的元素 id。

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 时，可使用以下值：

Prop类型描述
isDisabledboolean字段是否禁用。
isInvalidboolean字段当前是否无效。
isReadOnlyboolean字段是否只读。
isRequiredboolean字段是否必填。
isFocusedboolean字段是否聚焦（已弃用 — 请使用 isFocusWithin）。
isFocusWithinboolean是否有任一子元素聚焦。
isFocusVisibleboolean是否为可见键盘焦点。

Typography 排版

面向标题、正文与行内代码的语义化排版原语，基于 React Aria Components 的 Text 构建。

TextArea 多行文本框

原语级多行文本输入组件，可接受标准 HTML 属性。

本页目录

引入用法组件结构带说明必填字段校验受控错误信息禁用状态TextAreaInput 类型全宽在 Surface 内自定义渲染函数样式传入 Tailwind CSS 类自定义组件类CSS 类交互状态API 参考TextField PropsBase PropsValidation PropsValue PropsState PropsForm PropsAccessibility PropsComposition ComponentsTextFieldRenderProps