Bootstrap Badge: Colors, Pills and Notification Counters

A Bootstrap badge is a small colored label: a “New” tag next to a menu item, an unread count on a bell icon, a status such as “Paid”, or a category on a blog post. Badges are pure CSS. This guide covers the class, colors, pill badges, badges in headings and buttons, notification counters and dots, subtle badges, custom colors, and the Bootstrap 4 class names that no longer work. Everything is for Bootstrap 5.3.

A badge

<span class="badge text-bg-primary">New</span>

.badge sets the size, padding, and bold text. text-bg-primary sets the background color and a readable text color together. A badge with no text is hidden automatically, so an empty counter doesn’t show as a colored dot.

Colors

<span class="badge text-bg-primary">Primary</span>
<span class="badge text-bg-secondary">Secondary</span>
<span class="badge text-bg-success">Paid</span>
<span class="badge text-bg-danger">Overdue</span>
<span class="badge text-bg-warning">Pending</span>
<span class="badge text-bg-info">Beta</span>
<span class="badge text-bg-light">Draft</span>
<span class="badge text-bg-dark">Archived</span>

Use text-bg-* rather than bg-*: with bg-warning or bg-light, the badge keeps white text, which is hard to read. Color alone doesn’t reach everyone, so let the word carry the meaning (“Overdue”, not only red).

Pill badges

<span class="badge rounded-pill text-bg-success">Active</span>

rounded-pill gives fully rounded ends. Other corner sizes are in the borders and shadows guide.

Subtle badges

For a softer look, use the subtle background and the matching dark text color:

<span class="badge bg-primary-subtle text-primary-emphasis border border-primary-subtle">Design</span>
<span class="badge bg-success-subtle text-success-emphasis border border-success-subtle">Published</span>
<span class="badge bg-danger-subtle text-danger-emphasis border border-danger-subtle">Failed</span>

These colors adjust themselves in dark mode, so they stay readable on dark backgrounds.

Badges in headings and text

A badge is sized in em, so it scales with the text around it:

<h2>Release notes <span class="badge text-bg-secondary">v2.4</span></h2>
<p>Exports now support Sass maps <span class="badge text-bg-info">Beta</span></p>

Badges in buttons

<button type="button" class="btn btn-primary">
  Messages <span class="badge text-bg-light">4</span>
</button>

A screen reader reads this as “Messages 4”, which is unclear. Add hidden text so it says what the number is:

<button type="button" class="btn btn-primary">
  Messages <span class="badge text-bg-light">4 <span class="visually-hidden">unread</span></span>
</button>

More button patterns are in the Bootstrap buttons guide.

Notification counter on an icon

Position the badge on the corner of a button with the position utilities:

<button type="button" class="btn btn-light position-relative" aria-label="Notifications">
  <i class="bi bi-bell"></i>
  <span class="position-absolute top-0 start-100 translate-middle badge rounded-pill text-bg-danger">
    12 <span class="visually-hidden">new notifications</span>
  </span>
</button>

position-relative on the button lets the badge sit at its top-right corner, and translate-middle centers the badge on that corner. Write “99+” for large numbers so the badge stays small. The bell comes from Bootstrap Icons.

A status dot

For a dot without a number, such as “online” on an avatar:

<span class="position-relative d-inline-block">
  <img src="avatar.jpg" class="rounded-circle" width="40" height="40" alt="Ana Lopez">
  <span class="position-absolute bottom-0 end-0 p-1 bg-success border border-2 border-white rounded-circle">
    <span class="visually-hidden">Online</span>
  </span>
</span>

The dot has no .badge class, because an empty badge would be hidden; the visually hidden text keeps it accessible.

Badges in lists and navigation

A count at the end of each list item:

<ul class="list-group">
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Inbox <span class="badge text-bg-primary rounded-pill">14</span>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Drafts <span class="badge text-bg-secondary rounded-pill">2</span>
  </li>
</ul>

d-flex justify-content-between pushes the badge to the right. A “New” badge after a link in a navbar works the same way as in text.

Badges as links

<a href="/tags/sass/" class="badge text-bg-secondary text-decoration-none">Sass</a>

Tag badges on blog posts are often links. Make them big enough to tap on phones, for example with fs-6 or extra padding.

Custom badge colors and sizes

Badges use CSS variables:

.badge-brand {
  --bs-badge-padding-x: .75em;
  --bs-badge-padding-y: .4em;
  --bs-badge-font-weight: 600;
  --bs-badge-border-radius: .5rem;
  background-color: #2f55ff;
  color: #fff;
}

For a larger badge, add a font size utility such as fs-6, because the badge scales with its own font size. In Sass, $badge-font-size (.75em), $badge-font-weight, $badge-padding-y, $badge-padding-x, and $badge-border-radius set the defaults. New theme colors you add in Sass get text-bg-* classes automatically; see how to customize Bootstrap 5 colors.

Bootstrap 4 badge classes

Bootstrap 4	Bootstrap 5
badge-primary	text-bg-primary (or bg-primary)
badge-pill	rounded-pill
badge-light	text-bg-light

The old badge-* color classes and badge-pill were removed in Bootstrap 5, so a copied Bootstrap 4 badge shows up with no background.

FAQ

How do I add a badge in Bootstrap 5?

Use a <span class="badge text-bg-primary">New</span>. Swap primary for any theme color, such as success, danger, or secondary. Badges need no JavaScript.

How do I make a rounded pill badge in Bootstrap?

Add rounded-pill to the badge, as in <span class="badge rounded-pill text-bg-success">Active</span>. In Bootstrap 4 this was badge-pill, which no longer exists.

How do I put a notification badge on an icon in Bootstrap?

Give the button or icon wrapper position-relative, then add a badge with position-absolute top-0 start-100 translate-middle rounded-pill. Include visually hidden text, such as “new notifications”, for screen readers.

Why does my Bootstrap badge have no background color?

You’re probably using a Bootstrap 4 class such as badge-primary, which was removed in Bootstrap 5. Use text-bg-primary or bg-primary instead.

How do I make a Bootstrap badge bigger?

Badges are sized relative to their font size, so add a larger font size with a utility such as fs-6 or fs-5, or put the badge in a heading. You can also change the --bs-badge-padding-x and --bs-badge-padding-y variables.