Badge

Compact labeling element for counters, indicators, and status markers, with color, outline/smooth, and size variants.

Overview

A <Badge> adds counts, labels, or status indicators to content — highlighting new items, notification counts, or other supplementary information alongside any content or component.

Basic usage

A <Badge> scales to suit the size of the parent element by using relative font sizing and em units.

Example heading New

import { Badge } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <h1>
        Example heading <Badge color="secondary">New</Badge>
      </h1>
      <h2>
        Example heading <Badge color="secondary">New</Badge>
      </h2>
      <h3>
        Example heading <Badge color="secondary">New</Badge>
      </h3>
      <h4>
        Example heading <Badge color="secondary">New</Badge>
      </h4>
      <h5>
        Example heading <Badge color="secondary">New</Badge>
      </h5>
      <h6>
        Example heading <Badge color="secondary">New</Badge>
      </h6>
    </>
  )
}

A badge composes as part of a link or button to provide a counter.

import { Badge, Button } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Button color="primary">
      Notifications <Badge color="secondary">4</Badge>
    </Button>
  )
}

Badge content can be confusing for screen reader users without proper context. Use semantic roles by adding role="status" for counters or role="presentation" for decorative badges, and provide descriptions with aria-label to explain the badge's meaning.

import { Badge, Button } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Button color="primary">
      Profile{' '}
      <Badge color="secondary" role="status" aria-label="unread messages">
        9
      </Badge>
    </Button>
  )
}

Color variants

Set the color prop to one of the Chassis themed colors to apply the appropriate background and text colors.

DefaultAlternatePrimarySecondaryNeutralDangerSuccessWarningInfoBlackWhite

import { Badge } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Badge color="default">Default</Badge>
      <Badge color="alternate">Alternate</Badge>
      <Badge color="primary">Primary</Badge>
      <Badge color="secondary">Secondary</Badge>
      <Badge color="neutral">Neutral</Badge>
      <Badge color="danger">Danger</Badge>
      <Badge color="success">Success</Badge>
      <Badge color="warning">Warning</Badge>
      <Badge color="info">Info</Badge>
      <Badge color="black">Black</Badge>
      <Badge color="white">White</Badge>
    </>
  )
}

Color alone doesn't convey meaning to assistive technology users. Ensure clarity through text with adequate contrast, ARIA attributes where needed, and the .visually-hidden class for screen reader content when color is the only indicator.

Outline style

Set variant="outline" for badges with a transparent background, colored border, and text.

DefaultPrimarySecondaryDangerSuccessWarningInfo

import { Badge } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Badge color="default" variant="outline">
        Default
      </Badge>
      <Badge color="primary" variant="outline">
        Primary
      </Badge>
      <Badge color="secondary" variant="outline">
        Secondary
      </Badge>
      <Badge color="danger" variant="outline">
        Danger
      </Badge>
      <Badge color="success" variant="outline">
        Success
      </Badge>
      <Badge color="warning" variant="outline">
        Warning
      </Badge>
      <Badge color="info" variant="outline">
        Info
      </Badge>
    </>
  )
}

Smooth style

Set variant="smooth" for badges with a subdued background color and matching text color, for a softer appearance.

DefaultPrimarySecondaryDangerSuccessWarningInfo

import { Badge } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Badge color="default" variant="smooth">
        Default
      </Badge>
      <Badge color="primary" variant="smooth">
        Primary
      </Badge>
      <Badge color="secondary" variant="smooth">
        Secondary
      </Badge>
      <Badge color="danger" variant="smooth">
        Danger
      </Badge>
      <Badge color="success" variant="smooth">
        Success
      </Badge>
      <Badge color="warning" variant="smooth">
        Warning
      </Badge>
      <Badge color="info" variant="smooth">
        Info
      </Badge>
    </>
  )
}

Size variants

Set size="sm" or size="lg" to adjust a badge's size for compact spaces or greater emphasis. Combine with circle for round counters.

SmallMediumLarge222

import { Badge } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Badge color="primary" size="sm">
        Small
      </Badge>
      <Badge color="primary">Medium</Badge>
      <Badge color="primary" size="lg">
        Large
      </Badge>
      <Badge color="primary" size="sm" circle>
        2
      </Badge>
      <Badge color="primary" circle>
        2
      </Badge>
      <Badge color="primary" size="lg" circle>
        2
      </Badge>
    </>
  )
}

Use cases

With components

A badge nests inside buttons and other components to indicate counts, status, or other supplementary information.

import { Badge, Button } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Button color="primary">
      Notifications{' '}
      <Badge color="secondary" circle role="status" aria-label="new notifications">
        2
      </Badge>
    </Button>
  )
}

Positioned badges

Set the position prop to place a badge in one of the corners of a link or button. The parent needs position-relative (or another positioning context) for this to work.

import { Badge, Button } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Button color="primary" className="position-relative">
        Profile
        <Badge color="danger" position="top-start" circle>
          99+ <span className="visually-hidden">unread messages</span>
        </Badge>
      </Button>
      <Button color="primary" className="position-relative ms-xs">
        Profile
        <Badge color="danger" position="top-end" circle>
          99+ <span className="visually-hidden">unread messages</span>
        </Badge>
      </Button>
      <br />
      <Button color="primary" className="position-relative">
        Profile
        <Badge color="danger" position="bottom-start" circle>
          99+ <span className="visually-hidden">unread messages</span>
        </Badge>
      </Button>
      <Button color="primary" className="position-relative ms-xs">
        Profile
        <Badge color="danger" position="bottom-end" circle>
          99+ <span className="visually-hidden">unread messages</span>
        </Badge>
      </Button>
    </>
  )
}

Custom corners

Beyond the default rounded appearance and the circle prop, border-radius utility classes applied through className give precise control over corners.

SharpBluntSoftPill

import { Badge } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Badge color="primary" className="rounded-zero">
        Sharp
      </Badge>
      <Badge color="primary" className="rounded-sm">
        Blunt
      </Badge>
      <Badge color="primary" className="rounded-md">
        Soft
      </Badge>
      <Badge color="primary" className="rounded-full">
        Pill
      </Badge>
    </>
  )
}

API

Badge

Prop	Type	Default
`asChild?`	`boolean`	—
Render the single child element in place of this component's own element, with this component's classes, props and ref merged onto it: `<Button asChild><Link href="/login">Log in</Link></Button>`. The alternative to `component` for React Server Components — an element can be passed from the server to this package's client components, a component reference (`component={Link}`) can't.
`circle?`	`boolean`	—
Select the shape of the component.
`className?`	`string`	—
A string of all className you want applied to the component.
`color?`	`ContextColor`	—
Sets the color of the component to one of Chassis context colors.
`component?`	`ElementType`	—
Component used for the root node. Either a string to use a HTML element or a component.
`position?`	`"top-start" \| "top-end" \| "bottom-end" \| "bottom-start"`	—
Position badge in one of the corners of a link or button.
`ref?`	`any`	—

`size?`	`Sizing`	—
Sets the size of the component to one of Chassis component sizes.
`variant?`	`ContextStyle`	—
Sets the context style of the component. `solid`/`basic` render the default look with no extra class.