---
title: TextField 文本输入框
description: 便于组合的文本字段，包含标签、说明与内联校验。
links:
  rac: TextField
  source: textfield/textfield.tsx
  styles: textfield.css
  storybook: Components/Forms/TextField
  figma: true
---

## 用法

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

<ComponentPreview name="textfield-basic" />

## 组件结构

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

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

> **TextField** 将标签、输入、说明与错误信息整合为单个无障碍组件。若只需独立输入，请使用 **[Input](/docs/components/input)** 或 **[TextArea](/docs/components/textarea)**。

## 示例

### 表面样式

在 [Surface](/docs/components/surface) 内使用时，请在 Input 或 TextArea 组件上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。

<ComponentPreview name="textfield-on-surface" />

### 带描述

<ComponentPreview name="textfield-with-description" />

### 必填字段

<ComponentPreview name="textfield-required" />

### 禁用状态

<ComponentPreview name="textfield-disabled" />

### 宽度充满

<ComponentPreview name="textfield-full-width" />

### 表单校验

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

<ComponentPreview name="textfield-validation" />

### 受控组件

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

<ComponentPreview name="textfield-controlled" />

### 错误信息

<ComponentPreview name="textfield-with-error" />

### 文本域

多行内容请使用 [TextArea](/docs/components/textarea)，而非 [Input](/docs/components/input)。

<ComponentPreview name="textfield-textarea" />

### Input 类型

<ComponentPreview name="textfield-input-types" />

### 渲染函数

<ComponentPreview
  name="textfield-render-function"
/>

## 自定义样式

### Tailwind CSS

<ComponentPreview name="text-field-custom-styles" />

### 全局 CSS

若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@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](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

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

> **提示：** 子组件（[Label](/docs/components/label)、[Input](/docs/components/input)、[TextArea](/docs/components/textarea)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）各自拥有 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](https://react-spectrum.adobe.com/react-aria/TextField.html) 的全部 props。

#### Base Props

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

#### Validation Props

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

#### Value Props

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

#### State Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `isDisabled` | `boolean` | - | 是否禁用输入。 |
| `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 |

#### Form Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `name` | `string` | - | 用于 HTML 表单提交的 input 名称。 |
| `autoFocus` | `boolean` | - | 是否在挂载时自动聚焦。 |

#### Accessibility Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `aria-label` | `string` | - | 无可见标签时的无障碍标签。 |
| `aria-labelledby` | `string` | - | 用于标注该字段的元素 id。 |
| `aria-describedby` | `string` | - | 用于描述该字段的元素 id。 |
| `aria-details` | `string` | - | 提供附加详情的元素 id。 |

### Composition Components

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

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

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

```tsx
<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 | 类型 | 描述 |
|------|------|------|
| `isDisabled` | `boolean` | 字段是否禁用。 |
| `isInvalid` | `boolean` | 字段当前是否无效。 |
| `isReadOnly` | `boolean` | 字段是否只读。 |
| `isRequired` | `boolean` | 字段是否必填。 |
| `isFocused` | `boolean` | 字段是否聚焦（已弃用 — 请使用 `isFocusWithin`）。 |
| `isFocusWithin` | `boolean` | 是否有任一子元素聚焦。 |
| `isFocusVisible` | `boolean` | 是否为可见键盘焦点。 |

## 相关案例

<RelatedShowcases component="TextField" />

## 相关组件

<RelatedComponents component="textfield" />