Badge

Badges display small amounts of non-interactive information like counts, status indicators, or notifications.

Active

Failed

Overview

Badges are used to highlight an item’s status for quick recognition. They are non-interactive and are typically used to convey information such as a count, status, or category.

Usage

forge-badge communicates a status, count, or short label through theme, strong, and dot. Reserve badges for glanceable, non-interactive information; reach for a chip instead when the element needs to support selection or filtering.

Rules

Use consistent color meanings across your application so users can learn and recognize status patterns.

Position badges consistently in relation to their associated content.

Keep badge content to a word, short label, or number.

Use the default, muted theme when many badges appear on screen, such as in a long table.

Reserve strong for views where only a few badges need extra emphasis.

Limit to one badge per record.

Don't

Don’t mix color meanings.

Don't use a badge for a long phrase or sentence.

Don't stack more than one badge on a single record.

Don't use a badge for interactive selection or filtering — use a chip instead.

Don’t override established color conventions without good reason.

Theme

Badges default to a neutral theme. Use a semantic theme — success, warning, error, info — to reinforce the meaning of the status being shown, or primary/secondary/tertiary to match the badge to its surrounding context.

Every theme in its default, muted appearance.

<div style="display: flex; gap: 8px;">
  <forge-badge theme="default">
    Default
  </forge-badge>
  <forge-badge theme="primary">
    Primary
  </forge-badge>
  <forge-badge theme="secondary">
    Secondary
  </forge-badge>
  <forge-badge theme="tertiary">
    Tertiary
  </forge-badge>
  <forge-badge theme="success">
    Success
  </forge-badge>
  <forge-badge theme="error">
    Error
  </forge-badge>
  <forge-badge theme="warning">
    Warning
  </forge-badge>
  <forge-badge theme="info">
    Info
  </forge-badge>
  <forge-badge theme="info-secondary">
    Info (secondary)
  </forge-badge>
</div>

Strong

Set the strong attribute for a bolder fill when a badge needs to stand out. Reserve it for views where only a few badges are visible at once — overusing strong across a dense view defeats the emphasis.

The same themes rendered with strong for more visual weight.

<div style="display: flex; gap: 8px;">
  <forge-badge strong theme="default">
    Default
  </forge-badge>
  <forge-badge strong theme="primary">
    Primary
  </forge-badge>
  <forge-badge strong theme="secondary">
    Secondary
  </forge-badge>
  <forge-badge strong theme="tertiary">
    Tertiary
  </forge-badge>
  <forge-badge strong theme="success">
    Success
  </forge-badge>
  <forge-badge strong theme="error">
    Error
  </forge-badge>
  <forge-badge strong theme="warning">
    Warning
  </forge-badge>
  <forge-badge strong theme="info">
    Info
  </forge-badge>
  <forge-badge strong theme="info-secondary">
    Info (secondary)
  </forge-badge>
</div>

With an icon

Pair a badge’s label with a leading icon via the start slot to reinforce its meaning.

An icon in the start slot reinforces the badge's label.

<forge-badge theme="default">
  <forge-icon name="alert" slot="start">
  </forge-icon>
  <span>
    Warning
  </span>
</forge-badge>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconAlert } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconAlert]);
</script>

On an icon button

Pass a badge into an icon button’s badge slot to overlay a count, most often for unread or new content.

A numeric badge overlaid on an icon button.

<forge-icon-button>
  <forge-icon name="notifications">
  </forge-icon>
  <forge-badge slot="badge" theme="default">
    1
  </forge-badge>
</forge-icon-button>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconNotifications } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconNotifications]);
</script>

Dot

Set dot to render the badge as a small dot with no visible content — useful for signaling unread content without a count.

A dot badge signals unread content without a count.

<forge-icon-button aria-label="Notifications">
  <forge-icon name="bell">
  </forge-icon>
  <forge-badge slot="badge" dot>
  </forge-badge>
</forge-icon-button>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconBell } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconBell]);
</script>

Badges display small amounts of non-interactive information like counts, status indicators, or notifications.

import "@tylertech/forge/badge";

Properties

Property	Attribute	Type	Default	Description
`dot`	—	`boolean`	`false`	Controls whether the badge will be a small dot without any content visible.
`theme`	—	`BadgeTheme`	`'default'`	The theme of the badge.
`strong`	—	`boolean`	`false`	Controls whether the badge will have a stronger visual appearance.
`hide`	—	`boolean`	`false`	Controls whether the badge is visible.

Slots

Name	Description
`(default)`	Default content placed inside the badge.
`start`	Content placed before the default content.
`end`	Content placed after the default content.

CSS Custom Properties

Name	Description
`--forge-badge-background`	The background color.
`--forge-badge-color`	The text color.
`--forge-badge-shape`	The shape radius.
`--forge-badge-padding-inline`	The inline padding.
`--forge-badge-padding-block`	The block padding.
`--forge-badge-border-width`	The border width.
`--forge-badge-border-color`	The border color.
`--forge-badge-border-style`	The border style.
`--forge-badge-gap`	The spacing between the content within the badge.

Color and contrast

A badge conveys status largely through color — pair that color with an icon or other visual cue for users with color vision deficiencies, and make sure its foreground text meets WCAG 2.2 contrast requirements against the background.