Badge 徽章

相对其他元素定位的小型指示器，常用于通知数量、状态点与标签

用法

1import { Badge } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// oxlint-disable jsx-a11y/prefer-tag-over-role -- The CSS-painted status dot has no image resource for an HTML img.3// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.4import { Avatar, Badge } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6import { s } from "../card/display.stylex";7
8export function BadgeBasic() {9  return (10    <div {...stylex.props(s.row6)}>11      <Badge.Anchor>12        <Avatar>13          <Avatar.Image14            alt="John Doe"15            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"16          />17          <Avatar.Fallback>JD</Avatar.Fallback>18        </Avatar>19        <Badge color="danger" size="sm">20          521        </Badge>22      </Badge.Anchor>23      <Badge.Anchor>24        <Avatar>25          <Avatar.Image26            alt="Alex Brown"27            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"28          />29          <Avatar.Fallback>AB</Avatar.Fallback>30        </Avatar>31        <Badge color="accent" size="sm">32          New33        </Badge>34      </Badge.Anchor>35      <Badge.Anchor>36        <Avatar>37          <Avatar.Image38            alt="Chris Davis"39            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"40          />41          <Avatar.Fallback>CD</Avatar.Fallback>42        </Avatar>43        <Badge role="img" aria-label="Online" color="success" placement="bottom-right" size="sm" />44      </Badge.Anchor>45    </div>46  );47}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

Badge 通过 Badge.Anchor 相对其他元素定位。纯文本子节点会自动包裹在 <Badge.Label> 中。

独立标签用法请使用 Chip 组件。

1<Badge.Anchor>2  <Avatar />3  <Badge color="danger">5</Badge>4</Badge.Anchor>

示例

变体

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Avatar, Badge, Separator } from "@lenso/ui";4import { Fragment } from "react";5import * as stylex from "@stylexjs/stylex";6import { s } from "../card/display.stylex";7
8const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";9export function BadgeVariants() {10  const variants = ["primary", "secondary", "soft"] as const;11  const colors = ["accent", "default", "success", "warning", "danger"] as const;12  return (13    <div {...stylex.props(s.column8)}>14      {variants.map((variant, index) => (15        <Fragment key={variant}>16          <div {...stylex.props(s.column4)}>17            <h3 {...stylex.props(s.textSm, s.semibold, s.muted, s.capitalize)}>{variant}</h3>18            <div {...stylex.props(s.row6)}>19              {colors.map((color) => (20                <Badge.Anchor key={color}>21                  <Avatar>22                    <Avatar.Image alt="John Doe" src={AVATAR_URL} />23                    <Avatar.Fallback>JD</Avatar.Fallback>24                  </Avatar>25                  <Badge color={color} size="sm" variant={variant}>26                    527                  </Badge>28                </Badge.Anchor>29              ))}30            </div>31          </div>32          {index < variants.length - 1 && <Separator />}33        </Fragment>34      ))}35    </div>36  );37}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

尺寸

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Avatar, Badge } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { s } from "../card/display.stylex";6
7const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";8export function BadgeSizes() {9  const sizes = ["sm", "md", "lg"] as const;10  return (11    <div {...stylex.props(s.row6)}>12      {sizes.map((size) => (13        <Badge.Anchor key={size}>14          <Avatar size={size}>15            <Avatar.Image alt="John Doe" src={AVATAR_URL} />16            <Avatar.Fallback>JD</Avatar.Fallback>17          </Avatar>18          <Badge color="danger" size={size}>19            520          </Badge>21        </Badge.Anchor>22      ))}23    </div>24  );25}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

颜色

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Avatar, Badge } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { s } from "../card/display.stylex";6
7const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";8export function BadgeColors() {9  const colors = ["default", "accent", "success", "warning", "danger"] as const;10  return (11    <div {...stylex.props(s.row6)}>12      {colors.map((color) => (13        <Badge.Anchor key={color}>14          <Avatar>15            <Avatar.Image alt="John Doe" src={AVATAR_URL} />16            <Avatar.Fallback>JD</Avatar.Fallback>17          </Avatar>18          <Badge color={color} size="sm" />19        </Badge.Anchor>20      ))}21    </div>22  );23}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

徽章位置

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Avatar, Badge } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { s } from "../card/display.stylex";6
7const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";8export function BadgePlacements() {9  const placements = ["top-right", "top-left", "bottom-right", "bottom-left"] as const;10  return (11    <div {...stylex.props(s.row8)}>12      {placements.map((placement) => (13        <div key={placement} {...stylex.props(s.centeredColumn2)}>14          <Badge.Anchor>15            <Avatar>16              <Avatar.Image alt="John Doe" src={AVATAR_URL} />17              <Avatar.Fallback>JD</Avatar.Fallback>18            </Avatar>19            <Badge color="accent" placement={placement} size="sm" />20          </Badge.Anchor>21          <span {...stylex.props(s.textXs, s.muted)}>{placement}</span>22        </div>23      ))}24    </div>25  );26}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

点状徽标

空徽章作为状态指示器，适用于在线/离线或活动信号。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Avatar, Badge } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { s } from "../card/display.stylex";6
7const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";8export function BadgeDot() {9  const colors = ["accent", "success", "warning", "danger"] as const;10  return (11    <div {...stylex.props(s.row6)}>12      {colors.map((color) => (13        <Badge.Anchor key={color}>14          <Avatar>15            <Avatar.Image alt="John Doe" src={AVATAR_URL} />16            <Avatar.Fallback>JD</Avatar.Fallback>17          </Avatar>18          <Badge color={color} placement="bottom-right" size="sm" />19        </Badge.Anchor>20      ))}21    </div>22  );23}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

带内容

Badge 支持文本、数字与图标。无子节点时渲染为点状指示器。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Bell } from "@gravity-ui/icons";4import { Avatar, Badge } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6import { s } from "../card/display.stylex";7
8const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";9export function BadgeWithContent() {10  return (11    <div {...stylex.props(s.row6)}>12      {["5", "New", "99+"].map((content) => (13        <Badge.Anchor key={content}>14          <Avatar>15            <Avatar.Image alt="John Doe" src={AVATAR_URL} />16            <Avatar.Fallback>JD</Avatar.Fallback>17          </Avatar>18          <Badge color="danger" size="sm">19            {content}20          </Badge>21        </Badge.Anchor>22      ))}23      <Badge.Anchor>24        <Avatar>25          <Avatar.Image alt="John Doe" src={AVATAR_URL} />26          <Avatar.Fallback>JD</Avatar.Fallback>27        </Avatar>28        <Badge color="accent" size="sm">29          <Bell {...stylex.props(s.iconDot)} />30        </Badge>31      </Badge.Anchor>32    </div>33  );34}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Avatar, Badge } from "@lenso/ui";4import { s } from "../card/display.stylex";5
6export function CustomStyles() {7  return (8    <Badge.Anchor>9      <Avatar>10        <Avatar.Image11          alt="Kate Wilson"12          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"13        />14        <Avatar.Fallback>KW</Avatar.Fallback>15      </Avatar>16      <Badge xstyle={s.badgeNumber} color="accent" size="sm" variant="soft">17        518      </Badge>19    </Badge.Anchor>20  );21}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

可使用 @layer components 指令自定义 Badge 组件类。了解更多。

1@layer components {2  .badge {3    @apply rounded-full text-xs;4  }5
6  .badge__label {7    @apply font-semibold;8  }9
10  .badge--accent {11    @apply shadow-sm;12  }13}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

Badge 组件使用以下 CSS 类（查看源码样式）：

基础类 [!toc]

.badge - 基础徽章容器样式
.badge__label - 标签文本 slot 样式
.badge-anchor - 锚定元素的定位包装器

颜色类 [!toc]

.badge--accent - 强调色变体
.badge--danger - 危险色变体
.badge--default - 默认色变体
.badge--success - 成功色变体
.badge--warning - 警告色变体

变体类 [!toc]

.badge--primary - 填充背景的主变体
.badge--secondary - 默认背景的次变体
.badge--soft - 浅色背景的 soft 变体

尺寸类 [!toc]

.badge--sm - 小尺寸
.badge--md - 中尺寸（默认）
.badge--lg - 大尺寸

位置类 [!toc]

.badge--top-right - 右上角（默认）
.badge--top-left - 左上角
.badge--bottom-right - 右下角
.badge--bottom-left - 左下角

复合变体类 [!toc]

Badge 支持组合变体与颜色类（如 .badge--primary.badge--accent）。以下组合有默认样式：

Primary Variants:

.badge--primary.badge--accent - 填充背景的 primary accent
.badge--primary.badge--default - 填充背景的 primary default
.badge--primary.badge--success - 填充背景的 primary success
.badge--primary.badge--warning - 填充背景的 primary warning
.badge--primary.badge--danger - 填充背景的 primary danger

Soft Variants:

.badge--soft.badge--accent - 浅色背景的 soft accent
.badge--soft.badge--default - 浅色背景的 soft default
.badge--soft.badge--success - 浅色背景的 soft success
.badge--soft.badge--warning - 浅色背景的 soft warning
.badge--soft.badge--danger - 浅色背景的 soft danger

API 参考

Badge

Prop	类型	默认值	描述
`children`	`React.ReactNode`	-	徽章内容（文本、数字或图标）。省略时渲染为点
`className`	`string`	-	根元素附加 CSS 类
`color`	`"default" \| "accent" \| "success" \| "warning" \| "danger"`	`"default"`	徽章颜色变体
`variant`	`"primary" \| "secondary" \| "soft"`	`"primary"`	视觉样式变体
`size`	`"sm" \| "md" \| "lg"`	`"md"`	徽章尺寸
`placement`	`"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"`	`"top-right"`	相对锚点的位置

Badge.Anchor

Prop	类型	默认值	描述
`children`	`React.ReactNode`	-	锚定元素及 Badge 本身
`className`	`string`	-	锚点包装器附加 CSS 类

Badge.Label

Prop	类型	默认值	描述
`children`	`React.ReactNode`	-	标签文本内容
`className`	`string`	-	标签 slot 附加 CSS 类

Badge 徽章

用法

组件结构

示例

变体

尺寸

颜色

徽章位置

点状徽标

带内容

自定义样式

Tailwind CSS

全局 CSS

样式参考

CSS 类

基础类 [!toc]

颜色类 [!toc]

变体类 [!toc]

尺寸类 [!toc]

位置类 [!toc]

复合变体类 [!toc]

API 参考

Badge

Badge.Anchor

Badge.Label

相关组件