Badge

A compact label for status, counts, and categories. Single-element like Button; status variants are soft tints derived from semantic tokens, so they re-theme everywhere.

Koala
Deployments
koala-docsfeat/badgeQueuednow
Ready2h
Failed5h
Ready1d
Ready2d
Failed3d

Try it yourself. This one is live, and its code is right below.

Online Betav2.4.0 main

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Add this component (its dependencies come along)npx koalaui-cli@latest add badge

Usage#

usage.tsxTSX
import { Badge } from "@/components/ui/badge"export function Example() {  return <Badge>New</Badge>}

Anatomy#

import { Badge, BadgeAvatar, BadgeCount, BadgeIcon, BadgeNumber, BadgeProgress, BadgeReveal, BadgeText } from "@/components/ui/badge"<BadgeReveal>  <Badge>    <BadgeAvatar />    <BadgeIcon />    <BadgeProgress />    <BadgeText />    <BadgeCount>      <BadgeNumber />    </BadgeCount>  </Badge></BadgeReveal>

Playground#

The whole control set is derived from the component’s recipe: change a tone or add a size and this follows on its own. Note that dismissal isn’t a flag but a handler, so the trailing button exists exactly when onRemove does.

In review
Playground
Props

The tone. Soft fills for status, solid for emphasis.

Fully rounded instead of the control radius.

The house default for a status badge.

Adds a trailing dismiss button via onRemove.

badge.tsxTSX
<Badge>In review</Badge>

Variants#

DefaultPrimarySecondaryOutline

Status#

Soft status variants pair a tinted background (the status hue at /10) with a darker text counterpart and no border, so the fill carries the color while the label stays legible. Both derive from one semantic token (--success, --warning, --info), so they re-theme across all four themes.

Approved Merged In review Pending Failed Running Skipped

Categorical#

Four extra hues for labeling categories, feature flags, and tags. All follow the same soft-tint pattern and re-theme across all four themes.

Beta New Featured DesignEngineeringFrontendDeprecated v1 Legacy

With dot#

The dot prop adds a leading status dot in the variant color - ideal for presence and at-a-glance state. The background is stripped so only the dot carries the color.

OnlineAwayBusyOfflineIn a callFocusedOn breakDo not disturb

Toggling the dot#

Drive dot from state and the change animates: the dot grows in and pushes the label over, the tint gives way to the hairline, and the label settles on foreground. Turning it off plays the same thing in reverse, back to the tinted badge. A badge that never passes dot renders no dot at all.

OnlineSyncingFocused

Custom color#

When the color arrives with the data (a dispatch call code with its category hex, a team, a label a user picked), pass it as color. The variant still picks the treatment: any page-ground tone gives the soft tint, with the label pulled toward the theme's foreground so a pale yellow still reads; primary (or secondary) gives a solid fill whose ink is chosen from the color itself, near-black on a light fill and white on a dark one; outline draws the hairline in the color. With dot the dot takes it.

10-3110-5010-1610-6010-9110-99
RobberyTrafficMedicalShots firedUnits free10-16

The ink is read from hex (#rgb, #rrggbb, with or without alpha) and rgb(); any other form (a named color, hsl(), a var()) paints fine but gets white ink, so prefer hex for solid badges. The same choice is exported as readableInk(color), returning "dark" or "light", for your own surfaces.

Appearance#

variant picks the tone, appearance picks how it is painted. soft, the default, is a tint, surface adds a hairline in the tone's ink, solid fills it, and modern is a neutral surface where only the leading icon or dot carries the tone. Each tone carries its own ink and solid per theme, so light and cream read as crisp as dark.

ActiveIn reviewPendingActiveIn review Ready Building Queued Error

Live#

pulse turns the dot on and gives it a slow echo, for something that is happening right now. Keep it to one per view. It holds still under reduced motion.

DeployingLive

Animated#

Four client parts give the badge motion that carries meaning. Each one holds still under reduced motion.

State change

BadgeText rolls to its new string and eases the width to fit; BadgeIcon grows the new glyph in whenever swap changes. The tint crosses to the new tone on its own.

QueuedQueuedQueued

Rolling count

BadgeNumber turns each digit like a drum, up when the value grows and down when it shrinks; only the digits that change move.

Inbox online

Working

sweep passes the ink band through the label for open-ended work; BadgeProgress fills a ring when there is a number.

GeneratingUploading 0%0%

Enter and leave

BadgeReveal opens and closes the badge's slot in a row, so neighbours slide instead of jumping.

BetaFrontendDesignLegacyDocs

Sizes#

OnlineOnlineOnlinev2.4.0v2.4.0v2.4.0

Pill#

Set pill for fully rounded edges - pairs well with dot and icon badges.

DefaultOnline Betav2.4.0

With icon#

Verified Beta New Featured Private feature/auth

Avatar and flag#

BadgeAvatar and Flag sit first and size to the badge, with the start padding tightened so the picture keeps an even margin.

Elena Ruiz Jonas Spain Germany

Count#

BadgeCount nests a number at the end, tinted from the badge's own ink so it stays legible on every tone.

Inbox 12Open 3Failing 24

Dismissible#

Pass onRemove to render a trailing dismiss button. Give each a descriptive removeLabel for screen readers. For filters people toggle and clear, reach for Chip: it is the interactive sibling, with the same heights and tones.

DesignEngineeringMarketingResearch

As child#

Use asChild to render the badge styles on another element, such as a link. As a link it gains a hover fill, a focus ring, and a trailing arrow that nudges forward.

API reference#

Badge

A single <span> that labels a status, count or category. Forwards all native <span> props; accepts className, merged last.

PropTypeDefaultDescription
variant"default" | "primary" | "secondary" | "outline" | "success" | "warning" | "info" | "destructive" | "purple" | "pink" | "teal" | "orange" | "overlay" | "overlayLight""default"The fill: neutral, solid, outline, a soft status tint, a categorical hue, or a dark or light glass for media.
appearance"soft" | "surface" | "solid" | "modern""soft"How the tone is painted: a tint (the default), a tint with a hairline in the tone's ink, a solid fill (white ink, dark on amber and on dark themes), or a neutral surface where only the leading icon or dot takes the tone.
size"sm" | "md" | "lg""md"Fixed heights of 20, 24 and 28px, matching Chip xs, sm and the step above. Sets padding, type, corner and icon size.
pillbooleanfalseFully rounded ends.
dotboolean-A leading dot in the variant's tone; the fill gives way to a hairline. Passing a boolean (even false) keeps the slot mounted, so flipping it animates.
pulseboolean-Turns the dot on with a slow echo, for something live. Still under reduced motion.
colorstring-Any CSS color. Paints the variant's treatment from it: a soft tint for the page-ground tones, a solid fill with a computed dark or white ink for primary / secondary, the hairline for outline; the dot takes it as is. Ignored by the overlay* fills. The root gets data-color and, when solid, data-ink (dark | light). The exported readableInk(color) returns that same pick.
onRemove() => void-Renders a trailing dismiss button that calls it.
removeLabelstring"Remove"The accessible label of the dismiss button. Name the item ("Remove Design").
asChildbooleanfalseRenders the badge styles onto its single child (Radix Slot), such as a link. Ignores dot and onRemove. A link gets a hover fill, a focus ring and a nudging trailing arrow.

BadgeAvatar

A picture placed first inside the badge, sized to it. Forwards all native <img> props; alt defaults to empty since the label names the person.

PropTypeDefaultDescription
srcstring-The image URL.

BadgeCount

A number nested at the end of the badge, tinted from its ink. Forwards all native <span> props.

PropTypeDefaultDescription
childrenReactNode-The count.

BadgeText

Client. A label that rolls to its new string and eases the badge width to fit. Forwards native <span> props.

PropTypeDefaultDescription
childrenstring-The label. Changing it plays the roll.
sweepboolean-Passes the ink band through the label, for open-ended work.

BadgeIcon

Client. Wraps the leading glyph so it is sized and toned like a direct icon, and grows the new one in on swap.

PropTypeDefaultDescription
swapstring-Any key for the current glyph; changing it plays the swap.

BadgeNumber

Client. A number whose digits roll like drums when it changes. Labelled with its value for assistive tech.

PropTypeDefaultDescription
valuenumber-A non-negative integer.

BadgeProgress

Client. A ring that fills to the value, sized and toned like a leading icon. Exposes progressbar semantics.

PropTypeDefaultDescription
valuenumber-0 to 100.

BadgeReveal

Client. Wraps a badge in a row and opens or closes its slot, so neighbours slide. Hidden and inert while closed.

PropTypeDefaultDescription
showboolean-Whether the badge is in the row.

FAQ#

A Badge labels: it states status, a count, or a category and is not meant to be clicked. A Button performs an action. If a user is expected to interact, reach for Button (or a chip with an explicit control). The exception is asChild, which lets the badge styling wrap a link.