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

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

# Badge 角标

展示数量或未读提醒。


## 基础用法

使用 `count` 设置数量，传入 `children` 将角标附着到内容上。


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

counts.tsx

复制代码

```tsx lineNumbers file="../../src/examples/badge/counts.tsx"
import { Badge, Button, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Bell } from 'lucide-react';

export function BadgeCounts() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">数量上限</Text>
      <Flex align="center" wrap>
        <Badge count={120} aria-label="120 条未读通知">
          <Button startIcon={<Bell />} aria-label="通知" />
        </Badge>
      </Flex>
      <Text tone="muted">显示零值</Text>
      <Flex align="center" wrap>
        <Badge count={0} showZero aria-label="0 条未读通知">
          <Button startIcon={<Bell />} aria-label="通知" />
        </Badge>
      </Flex>
    </Grid>
  );
}
```

展开代码

### 红点提醒

设置 `dot` 只提示有新内容。请通过 `aria-label` 说明提醒的含义。


dot.tsx

复制代码

```tsx lineNumbers file="../../src/examples/badge/dot.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>
  );
}
```

展开代码

### 内置角标

设置 `placement="inside"`，将提醒放在内容内部。为角标留出空间，避免遮挡文字或图标。


inside.tsx

复制代码

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

export function BadgeInside() {
  return (
    <Badge dot placement="inside" aria-label="有未读通知">
      <Button variant="outline" startIcon={<Bell />} aria-label="通知" />
    </Badge>
  );
}
```

展开代码


## API

### Badge API

角标的计数、圆点提醒及附着位置配置。

| 属性          | 类型                      | 默认值         | 说明                                  |
| ----------- | ----------------------- | ----------- | ----------------------------------- |
| `children`  | `ReactNode`             | 必填          | 角标附着的内容；不传入内容时不渲染角标                 |
| `count`     | `number \| string`      | —           | 角标内容                                |
| `max`       | `number`                | `99`        | 超过该值时展示 max+                        |
| `showZero`  | `boolean`               | `false`     | 允许展示 0                              |
| `dot`       | `boolean`               | `false`     | 使用圆点提醒                              |
| `placement` | `'outside' \| 'inside'` | `'outside'` | 附着角标的位置：默认外置，inside 放在右上角内部；RTL 下镜像 |
| `color`     | `string`                | —           | 自定义角标颜色                             |
