Badges

Compact labeling elements for counters, indicators, and status markers with multiple styles and sizes.

Overview

Badges are lightweight components used to add counts, labels, or status indicators to content. They highlight new items, display notification counts, and provide supplementary information.

Chassis badges are designed to be flexible, working with any content or component. They support proper screen reader context for accessibility, and are available in multiple styles and colors for customization. The responsive design allows them to adapt to surrounding content, making them versatile across different interfaces.

Basic usage

The .badge class provides the foundational structure for badges. By itself, it creates a minimal badge with default styling.

Base 24 24 Default 24 24 Primary 24 24

html

<!-- Base class -->
<span class="badge">Base</span>
<span class="badge">24</span>
<span class="badge circle">24</span>

<!-- Default variant -->
<span class="badge default">Default</span>
<span class="badge default">24</span>
<span class="badge default circle">24</span>

<!-- Primary variant -->
<span class="badge primary">Primary</span>
<span class="badge primary">24</span>
<span class="badge primary circle">24</span>

Badge elements

Badges can be used on any inline or block element. Use the .badge class to style the element as a badge.

Span Link

Div

html

<span class="badge primary">Span</span>
<a class="badge primary" href="#">Link</a>
<div class="badge primary">Div</div>

Color variants

The default badge style uses solid background colors with contrasting text. Add a contextual color class like .primary or .secondary to the base .badge class to apply appropriate styling.

Default Alternate Primary Secondary Neutral Danger Success Warning Info Black White

html

<span class="badge default">Default</span>
<span class="badge alternate">Alternate</span>
<span class="badge primary">Primary</span>
<span class="badge secondary">Secondary</span>
<span class="badge neutral">Neutral</span>
<span class="badge danger">Danger</span>
<span class="badge success">Success</span>
<span class="badge warning">Warning</span>
<span class="badge info">Info</span>
<span class="badge black">Black</span>
<span class="badge white">White</span>

Accessibility tip: Color alone shouldn't convey meaning as it's not perceived by assistive technology users. Ensure clarity through text with adequate contrast, ARIA attributes where needed, and consider using .visually-hidden for screen reader content.

Outline style

Add the .outline class to create badges with a transparent background, colored border and text.

Default Alternate Primary Secondary Neutral Danger Success Warning Info Black White

html

<span class="badge default outline">Default</span>
<span class="badge alternate outline">Alternate</span>
<span class="badge primary outline">Primary</span>
<span class="badge secondary outline">Secondary</span>
<span class="badge neutral outline">Neutral</span>
<span class="badge danger outline">Danger</span>
<span class="badge success outline">Success</span>
<span class="badge warning outline">Warning</span>
<span class="badge info outline">Info</span>
<span class="badge black outline">Black</span>
<span class="badge white outline">White</span>

Smooth style

Add the .smooth class to create badges with a subdued background color and matching text color, creating a softer, more subtle appearance.

Default Alternate Primary Secondary Neutral Danger Success Warning Info Black White

html

<span class="badge default smooth">Default</span>
<span class="badge alternate smooth">Alternate</span>
<span class="badge primary smooth">Primary</span>
<span class="badge secondary smooth">Secondary</span>
<span class="badge neutral smooth">Neutral</span>
<span class="badge danger smooth">Danger</span>
<span class="badge success smooth">Success</span>
<span class="badge warning smooth">Warning</span>
<span class="badge info smooth">Info</span>
<span class="badge black smooth">Black</span>
<span class="badge white smooth">White</span>

Size variants

Chassis provides three badge sizes to accommodate different design needs. Use the .small and .large classes to modify the size of the badge for compact spaces or greater emphasis.

Small Medium Large 2 2 2

html

<span class="badge small primary">Small</span>
<span class="badge primary">Medium</span>
<span class="badge large primary">Large</span>

<span class="badge small circle primary">2</span>
<span class="badge circle primary">2</span>
<span class="badge large circle primary">2</span>

Icons

Enhance badges with icons to provide additional visual meaning. Both SVG icons and icon fonts can be used within badges.

Small Medium Large Small Medium Large

html

<span class="badge default small">
  <svg class="icon" aria-hidden="true" role="img"><use xlink:href="#info-circle-solid"/></svg>
  <span>Small</span>
</span>
<span class="badge default">
  <svg class="icon" aria-hidden="true" role="img"><use xlink:href="#info-circle-solid"/></svg>
  <span>Medium</span>
</span>
<span class="badge default large">
  <svg class="icon" aria-hidden="true" role="img"><use xlink:href="#info-circle-solid"/></svg>
  <span>Large</span>
</span>

<span class="badge primary small">
  <span>Small</span>
  <span class="icon icon-info-circle-solid" aria-hidden="true"></span>
</span>
<span class="badge primary">
  <span>Medium</span>
  <span class="icon icon-info-circle-solid" aria-hidden="true"></span>
</span>
<span class="badge primary large">
  <span>Large</span>
  <span class="icon icon-info-circle-solid" aria-hidden="true"></span>
</span>

Icon spacing is automatically applied using :first-child and :last-child pseudo selectors. To ensure proper spacing, wrap the badge text in a <span> element.

Use cases

Badges can be integrated into various UI elements to enhance functionality and visual communication. The following examples demonstrate common implementation patterns.

With components

Badges work well inside buttons and other compoents to indicate counts, status, or other supplementary information.

html

<button type="button" class="button primary">
  Notifications
  <span class="badge secondary circle" role="status"
   aria-label="new notifications">2</span>
</button>

Unless the context is clear, always include additional context with visually hidden text.

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. Provide descriptions with aria-label to explain the badge's meaning. When needed, include additional context using <span class="visually-hidden">. For dynamic badges, ensure changes are announced properly to assistive technologies.

Positioned badges

Create notification-style indicators by positioning badges in the corners of elements:

html

<button type="button" class="button primary position-relative">
  Inbox
  <span class="badge secondary position-absolute top-0 start-100 translate-middle">
    99+ <span class="visually-hidden">unread messages</span>
  </span>
</button>

For a more minimal approach, create a simple indicator dot without a count:

html

<button type="button" class="button primary position-relative">
  Profile
  <span class="badge secondary p-xsmall rounded-circle
    position-absolute top-0 start-100 translate-middle">
    <span class="visually-hidden">New alerts</span>
  </span>
</button>

Custom corners

Beyond the default rounded appearance and the .circle modifier, you can use border-radius utility classes:

Sharp Blunt Soft Pill

html

<span class="badge primary rounded-zero">Sharp</span>
<span class="badge primary rounded-small">Blunt</span>
<span class="badge primary rounded-medium">Soft</span>
<span class="badge primary rounded-circle">Pill</span>

This approach gives you precise control over the visual style while maintaining consistent spacing and typography.

Adaptive sizing

The .badge-adaptive class creates responsive badges that automatically adjust their size based on their parent element's font size. This allows badges to appear appropriately sized in headings of different sizes, and ensures the same badge works consistently across various text contexts.

Example heading Adaptive Large

Extra small paragraph Adaptive Small

html

<h3>
  Example heading
  <span class="badge primary badge-adaptive">Adaptive</span>
  <span class="badge primary large">Large</span>
</h3>
<hr>
<p class="font-xsmall">
  Extra small paragraph
  <span class="badge primary badge-adaptive">Adaptive</span>
  <span class="badge primary small">Small</span>
</p>

Notice how the .badge-adaptive class makes badges properly scale with text sizes, while standard badges maintain their fixed sizes.

With wrappers

The .badge-adaptive class can be used on wrappers to make all badges use adaptive sizing.

Example heading New

html

<div class="badge-adaptive">
  <h1>Example heading <span class="badge primary">New</span></h1>
  <h2>Example heading <span class="badge primary">New</span></h2>
  <h3>Example heading <span class="badge primary">New</span></h3>
  <h4>Example heading <span class="badge primary">New</span></h4>
  <h5>Example heading <span class="badge primary">New</span></h5>
  <h6>Example heading <span class="badge primary">New</span></h6>
</div>

CSS

This component can be customized using CSS variables, allowing for styles to be modified dynamically on the page. These CSS variables are part of Chassis CSS's design token system, giving design teams control over component appearance. See the design tokens page for more details.

Custom properties

These CSS variables control the component's appearance and can be modified dynamically on the page. Components use cascading variables, allowing seamless variations in size, color, and style without redundant style declarations through component inheritance and the context class system.

Customize badges through CSS variables:

scss/_badge.scss

--#{$prefix}size: var(--#{$prefix}badge-size, #{$badge-medium-size});
--#{$prefix}padding-y: var(--#{$prefix}badge-padding-y, #{$badge-medium-padding-y});
--#{$prefix}padding-x: var(--#{$prefix}badge-padding-x, #{$badge-medium-padding-x + $badge-medium-nudge});
--#{$prefix}gap: var(--#{$prefix}badge-gap, #{$badge-medium-gap});
--#{$prefix}nudge: var(--#{$prefix}badge-nudge, #{$badge-medium-nudge});
--#{$prefix}border-width: var(--#{$prefix}badge-border-width, #{$badge-border-width});
--#{$prefix}border-radius: var(--#{$prefix}badge-border-radius, #{$badge-medium-border-radius});
--#{$prefix}icon-size: var(--#{$prefix}badge-icon-size, #{$badge-medium-icon-size});
@include map-font($badge-medium-font, badge); // e.g. --#{$prefix}[property-name]: var(--#{$prefix}badge-[propery-name], [value]);

Design tokens

These design tokens with $cx prefixes are managed by design teams in Figma using the Tokens Studio plugin. See the design tokens page for more details.

scss/tokens/_badge.scss

$badge-medium-font:                 $cx-font-badge-medium;
$badge-medium-size:                 $cx-size-badge-medium-main;
$badge-medium-icon-size:            $cx-size-badge-medium-icon;
$badge-medium-padding-y:            $cx-space-badge-medium-padding-y;
$badge-medium-padding-x:            $cx-space-badge-medium-padding-x;
$badge-medium-gap:                  $cx-space-badge-medium-gap;
$badge-medium-nudge:                  $cx-space-badge-medium-nudge;
$badge-medium-border-radius:        $cx-border-radius-badge-medium;

$badge-large-font:                  $cx-font-badge-large;
$badge-large-size:                  $cx-size-badge-large-main;
$badge-large-icon-size:             $cx-size-badge-large-icon;
$badge-large-padding-y:             $cx-space-badge-large-padding-y;
$badge-large-padding-x:             $cx-space-badge-large-padding-x;
$badge-large-gap:                   $cx-space-badge-large-gap;
$badge-large-nudge:                   $cx-space-badge-large-nudge;
$badge-large-border-radius:         $cx-border-radius-badge-large;

$badge-small-font:                  $cx-font-badge-small;
$badge-small-size:                  $cx-size-badge-small-main;
$badge-small-icon-size:             $cx-size-badge-small-icon;
$badge-small-padding-y:             $cx-space-badge-small-padding-y;
$badge-small-padding-x:             $cx-space-badge-small-padding-x;
$badge-small-gap:                   $cx-space-badge-small-gap;
$badge-small-nudge:                   $cx-space-badge-small-nudge;
$badge-small-border-radius:         $cx-border-radius-badge-small;

$badge-border-width:                $cx-border-width-badge-main;