---
title: ErrorMessage 错误消息
description: 用于展示错误的底层错误消息组件
links:
  rac: TagGroup
  source: error-message/error-message.tsx
  styles: error-message.css
---

## 用法

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

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

`ErrorMessage` 是基于 React Aria `Text` 组件、`errorMessage` slot 的底层组件，用于在 **非表单组件**（如 `TagGroup`、`Calendar` 及其他集合类组件）中展示错误消息。

## 组件结构

```tsx
import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';

<TagGroup>
  <Label />
  <TagGroup.List>
    <Tag />
  </TagGroup.List>
  <Description />
  <ErrorMessage />
</TagGroup>
```

## 何时使用

`ErrorMessage` **不绑定表单**，是用于非表单上下文的通用错误展示组件。

- **推荐用于** 非表单组件（如 `TagGroup`、`Calendar`、集合类组件）
- **表单字段** 建议使用 [`FieldError`](/docs/components/field-error)，它提供表单专用校验特性与自动错误处理，遵循标准化表单校验模式。

## ErrorMessage 与 FieldError

| 组件 | 使用场景 | 表单集成 | 示例组件 |
|-----------|----------|------------------|---------------------|
| `ErrorMessage` | 非表单组件 | 否 | `TagGroup`、`Calendar` |
| `FieldError` | 表单字段（推荐） | 是 | `TextField`、`NumberField`、`Select` |

表单校验建议使用 `FieldError`，它遵循标准化表单校验模式并提供表单专用特性。参见 [FieldError 文档](/docs/components/field-error) 与 [Form 指南](/docs/components/form)。

## 自定义样式

### Tailwind CSS

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

### 全局 CSS

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

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

## 样式参考

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

### CSS 类

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

#### 基础类 [!toc]

- `.error-message` - 基础错误消息样式，danger 色与文本截断

#### 插槽类 [!toc]

- `[slot="errorMessage"]` - 用于 React Aria 集成的 ErrorMessage slot 样式

## API 参考

### ErrorMessage

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `ReactNode` | - | 错误消息内容 |

## 说明

`ErrorMessage` 基于 React Aria 的 `Text` 组件，`slot="errorMessage"`。可通过 `[slot=errorMessage]` CSS 选择器定位。

## 无障碍

ErrorMessage 组件通过以下方式增强无障碍性：

- 使用屏幕阅读器可识别的语义化 HTML
- 提供 `slot="errorMessage"` 属性以集成 React Aria
- 错误状态支持适当的文本对比度
- 遵循 WAI-ARIA 错误消息最佳实践

## 相关组件

<RelatedComponents component="errormessage" />