> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/badge.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.

# Badge 角标

展示数量、未读提醒或简短状态。

## 基础用法


8

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/badge/basic.tsx"
import { Badge, Button } from '@ifhover/leaf-ui';

import { Bell } from 'lucide-react';

export function BadgeBasic() {
  return (
    <Badge count={8} aria-label="8 条未读通知">
      <Button variant="outline" startIcon={<Bell />} aria-label="通知" />
    </Badge>
  );
}
```

展开代码

## 数值规则

超过 `max` 的数值展示为上限加号；使用 `showZero` 展示零值。


超过数量上限99+

显示零值0

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/badge/basic.tsx"
import { Badge, Button, Flex, Space, Text } from '@ifhover/leaf-ui';

import { Bell } from 'lucide-react';

export function BadgeCounts() {
  return (
    <Space wrap size={32}>
      <Flex direction="column" gap="sm" align="start">
        <Text>超过数量上限</Text>
        <Badge count={120}>
          <Button variant="outline" startIcon={<Bell />} aria-label="通知" />
        </Badge>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>显示零值</Text>
        <Badge count={0} showZero>
          <Button variant="outline" startIcon={<Bell />} aria-label="通知" />
        </Badge>
      </Flex>
    </Space>
  );
}
```

展开代码

## 红点提醒

只提示有新内容，不展示具体数量。


basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/badge/basic.tsx"
import { Badge, Button } from '@ifhover/leaf-ui';

import { Mail } from 'lucide-react';

export function BadgeDot() {
  return (
    <Badge dot aria-label="有未读消息">
      <Button variant="outline" startIcon={<Mail />} aria-label="消息" />
    </Badge>
  );
}
```

展开代码

## 状态标记

用圆点和文字说明当前状态。


运行中待处理已停止更新中未启动

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/badge/basic.tsx"
import { Badge, Space } from '@ifhover/leaf-ui';

export function BadgeStatuses() {
  return (
    <Space wrap size={24}>
      <Badge status="success" text="运行中" />
      <Badge status="warning" text="待处理" />
      <Badge status="error" text="已停止" />
      <Badge status="info" text="更新中" />
      <Badge status="default" text="未启动" />
    </Space>
  );
}
```

展开代码

## Badge API

| 属性         | 类型                                                         | 默认值     | 说明              |
| ---------- | ---------------------------------------------------------- | ------- | --------------- |
| `children` | `ReactNode`                                                | —       | 设置后将角标附着在该内容右上方 |
| `count`    | `number \| string`                                         | —       | 角标内容            |
| `max`      | `number`                                                   | `99`    | 超过该值时展示 max+    |
| `showZero` | `boolean`                                                  | `false` | 允许展示 0          |
| `dot`      | `boolean`                                                  | `false` | 使用圆点提醒          |
| `status`   | `'success' \| 'warning' \| 'error' \| 'info' \| 'default'` | —       | 使用对应颜色的状态圆点     |
| `text`     | `ReactNode`                                                | —       | 圆点旁的说明          |
| `color`    | `string`                                                   | —       | 自定义角标颜色         |

## 类型

定义组件属性或组装列表时可导入相关类型。

```ts
import type { BadgeProps } from '@ifhover/leaf-ui';
```

## 使用说明

独立使用时可展示数量或状态。附着在按钮等内容上时，为圆点提醒提供 aria-label，以说明提醒的含义。