---
title: FieldError 字段错误
description: 展示表单字段校验错误消息
links:
  rac: FieldError
  source: field-error/field-error.tsx
  styles: field-error.css
---

## 用法

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

<ComponentPreview
  name="field-error-basic"
/>

FieldError 组件展示表单字段的校验错误消息。当父字段标记为无效时自动显示，并提供平滑的透明度过渡。

## 示例

### 基础校验

```tsx
export function Basic() {
  const [value, setValue] = useState("");
  const isInvalid = value.length > 0 && value.length < 3;

  return (
    <TextField className="w-64" isInvalid={isInvalid}>
      <Label htmlFor="username">Username</Label>
      <Input
        id="username"
        placeholder="Enter username"
        value={value}
        onChange={(e) => setValue(e.target.value)}
      />
      <FieldError>Username must be at least 3 characters</FieldError>
    </TextField>
  );
}
```

### 动态错误信息

```tsx
<TextField isInvalid={errors.length > 0}>
  <Label>Password</Label>
  <Input type="password" />
  <FieldError>
    {(validation) => validation.validationErrors.join(', ')}
  </FieldError>
</TextField>
```

### 自定义校验逻辑

```tsx
function EmailField() {
  const [email, setEmail] = useState('');
  const isInvalid = email.length > 0 && !email.includes('@');

  return (
    <TextField isInvalid={isInvalid}>
      <Label>Email</Label>
      <Input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
      />
      <FieldError>Email must include @ symbol</FieldError>
    </TextField>
  );
}
```

### 多条错误信息

```tsx
<TextField isInvalid={hasErrors}>
  <Label>Username</Label>
  <Input />
  <FieldError>
    {errors.map((error, i) => (
      <div key={i}>{error}</div>
    ))}
  </FieldError>
</TextField>
```

## 自定义样式

### Tailwind CSS

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

### 全局 CSS

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

```css
@layer components {
  .field-error {
    @apply font-medium text-danger;
  }
}
```

## 样式参考

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

FieldError 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/field-error.css)）：

#### 基础类 [!toc]

- `.field-error` - 基础错误样式，danger 色
- 仅在存在 `data-visible` 属性时显示
- 长消息以省略号截断

## API 参考

### FieldError

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | - | 错误消息内容或 render 函数 |

## 无障碍

FieldError 组件通过以下方式确保无障碍性：

- 使用适当的 ARIA 属性播报错误
- 语义化 HTML 支持屏幕阅读器
- 提供视觉与程序化错误指示
- 根据校验状态自动管理可见性

## 相关组件

<RelatedComponents component="fielderror" />