Badge

Displays a small indicator positioned relative to another element, commonly used for notification counts, status dots, and labels

Usage

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.

Anatomy

Badge is designed to be positioned relative to another element using Badge.Anchor. Plain-text children are automatically wrapped in <Badge.Label>.

For standalone label usage, use the Chip component instead.

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

Examples

Variants

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.

Sizes

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.

Colors

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.

Placements

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.

Dot Badge

Empty badges act as status indicators — useful for online/offline states or activity signals.

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.

With Content

Badge supports text, numbers, and icons as content. When no children are provided, it renders as a dot indicator.

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.

Customization

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.

Global CSS

To customize the Badge component classes, you can use the @layer components directive. Learn more.

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}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The Badge component uses these CSS classes (View source styles):

Base Classes [!toc]

.badge - Base badge container styles
.badge__label - Label text slot styles
.badge-anchor - Positioning wrapper for the anchored element

Color Classes [!toc]

.badge--accent - Accent color variant
.badge--danger - Danger color variant
.badge--default - Default color variant
.badge--success - Success color variant
.badge--warning - Warning color variant

Variant Classes [!toc]

.badge--primary - Primary variant with filled background
.badge--secondary - Secondary variant with default background
.badge--soft - Soft variant with lighter background

Size Classes [!toc]

.badge--sm - Small size
.badge--md - Medium size (default)
.badge--lg - Large size

Placement Classes [!toc]

.badge--top-right - Position at top-right corner (default)
.badge--top-left - Position at top-left corner
.badge--bottom-right - Position at bottom-right corner
.badge--bottom-left - Position at bottom-left corner

Compound Variant Classes [!toc]

Badges support combining variant and color classes (e.g., .badge--primary.badge--accent). The following combinations have default styles defined:

Primary Variants:

.badge--primary.badge--accent - Primary accent with filled background
.badge--primary.badge--default - Primary default with filled background
.badge--primary.badge--success - Primary success with filled background
.badge--primary.badge--warning - Primary warning with filled background
.badge--primary.badge--danger - Primary danger with filled background

Soft Variants:

.badge--soft.badge--accent - Soft accent with lighter background
.badge--soft.badge--default - Soft default with lighter background
.badge--soft.badge--success - Soft success with lighter background
.badge--soft.badge--warning - Soft warning with lighter background
.badge--soft.badge--danger - Soft danger with lighter background

API Reference

Badge

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Content to display inside the badge (text, number, or icon). When omitted, renders as a dot.
`className`	`string`	-	Additional CSS classes for the root element
`color`	`"default" \| "accent" \| "success" \| "warning" \| "danger"`	`"default"`	Color variant of the badge
`variant`	`"primary" \| "secondary" \| "soft"`	`"primary"`	Visual style variant
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Size of the badge
`placement`	`"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"`	`"top-right"`	Position of the badge relative to its anchor

Badge.Anchor

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	The element to anchor the badge to, plus the Badge itself
`className`	`string`	-	Additional CSS classes for the anchor wrapper

Badge.Label

Prop	Type	Default	Description
`children`	`React.ReactNode`	-	Label text content
`className`	`string`	-	Additional CSS classes for the label slot

Avatar

Display user profile images with customizable fallback content

Chip

Small informational badges for displaying labels, statuses, and categories

Badge

Usage

Anatomy

Examples

Variants

Sizes

Colors

Placements

Dot Badge

With Content

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Base Classes [!toc]

Color Classes [!toc]

Variant Classes [!toc]

Size Classes [!toc]

Placement Classes [!toc]

Compound Variant Classes [!toc]

API Reference

Badge

Badge.Anchor

Badge.Label

Related Components