Badge

A small status label — for counts, tags, and state indicators.

Last updated

NewError
Show code
<Badge color="primary" variant="solid">New</Badge>
<Badge color="critical" variant="solid">Error</Badge>

Add

npx @ava-ui/apogee add badge

No component dependencies.

Usage

---
import Badge from '@/components/apogee/Badge/Badge.astro'
---
<Badge color="primary" variant="solid">New</Badge>

API

@composable — exposed to Content Editors in AVA. Any other native <span> attribute passes through.

Prop Type Default Description
color 'primary' | 'neutral' | 'critical' | 'positive' | 'warning' 'neutral' The hue.
variant 'solid' | 'faded' | 'outline' 'faded' The fill style.
size 'small' | 'medium' | 'large' 'medium' Height: 20 / 24 / 28px.
rounded boolean false Fully round ends.
highlighted boolean false Stronger fill for an active filter or selected state.
truncate boolean false Clamps long labels (max 10rem) with an ellipsis.
class string — Extra classes, appended last.

Slots: start and end for a small icon.

Variants × colors

Every variant for every color:

PrimaryNeutralCriticalPositiveWarning
PrimaryNeutralCriticalPositiveWarning
PrimaryNeutralCriticalPositiveWarning
Show code
<Badge color="primary" variant="solid">Primary</Badge>
<Badge color="neutral" variant="solid">Neutral</Badge>
<Badge color="critical" variant="solid">Critical</Badge>
<Badge color="positive" variant="solid">Positive</Badge>
<Badge color="warning" variant="solid">Warning</Badge>

<Badge color="primary">Primary</Badge>
<Badge color="neutral">Neutral</Badge>
<Badge color="critical">Critical</Badge>
<Badge color="positive">Positive</Badge>
<Badge color="warning">Warning</Badge>

<Badge color="primary" variant="outline">Primary</Badge>
<Badge color="neutral" variant="outline">Neutral</Badge>
<Badge color="critical" variant="outline">Critical</Badge>
<Badge color="positive" variant="outline">Positive</Badge>
<Badge color="warning" variant="outline">Warning</Badge>

Sizes

SmallMediumLargeRounded
Show code
<Badge size="small">Small</Badge>
<Badge size="medium">Medium</Badge>
<Badge size="large">Large</Badge>
<Badge rounded>Rounded</Badge>

Padding

The side that holds an icon pads less:

PlainVerifiedNext
Show code
<Badge>Plain</Badge>
<Badge><Check slot="start" />Verified</Badge>
<Badge>Next<Check slot="end" /></Badge>

States

FilterFilterLiveLiveA label far too long to fit in a small chip
Show code
<Badge color="primary">Filter</Badge>
<Badge color="primary" highlighted>Filter</Badge>
<Badge variant="solid" color="positive">Live</Badge>
<Badge variant="solid" color="positive" highlighted>Live</Badge>
<Badge truncate>A label far too long to fit in a small chip</Badge>

With no content a Badge renders as a dot indicator:

Show code
<Badge color="critical" />
<Badge color="positive" />

BadgeContainer

Anchors a Badge on the corner of an avatar, icon or button.

ALAT3
Show code
<BadgeContainer>
<Avatar name="Ada Lovelace" />
<Badge slot="badge" color="critical" />
</BadgeContainer>
<BadgeContainer position="bottom-end" overlap>
<Avatar name="Alan Turing" />
<Badge slot="badge" variant="solid" color="positive" rounded size="small">3</Badge>
</BadgeContainer>
Prop Type Default Description
position 'top-end' | 'bottom-end' 'top-end' Corner the badge sits on.
overlap boolean false Pushes the badge outward for round elements.
class string — Extra classes on the wrapper.

Static — a <span>, not a control. No hover/focus/disabled states. If a badge needs to be clickable (a removable filter chip), wrap it in a <button> yourself; Badge doesn’t provide one.

Examples

With a leading icon — like Button, the child SVG auto-sizes:

Verified
Show code
<Badge color="primary" variant="solid"><Check /> Verified</Badge>

As a count next to a label:

<span class="flex items-center gap-2">
  Inbox
  <Badge color="critical" variant="solid">12</Badge>
</span>

Accessibility

Native semantics, no extra ARIA needed for a static label. If a badge’s count updates live (e.g. an unread counter), pass aria-live="polite" via passthrough so assistive tech picks up the change.

Tokens

Token Used for
--background-{hue}-faded / --foreground-{hue} faded variant, per color
--background-{hue} / --on-{hue} solid variant
--border-{hue} / --foreground-{hue} outline variant

Do / Don’t

  • Do keep badge text to one or two words, or a short number.
  • Do reserve danger for genuinely negative states (errors, overdue) — not just to draw attention.
  • Don’t use Badge as a button — it has no focus or press states.
  • Don’t wrap long sentences in a Badge; it doesn’t wrap gracefully and isn’t meant to hold prose.

Content

  • Sentence case or a single number, no ending period. Prefer a status word (“Active”, “Beta”, “12”) over a phrase.

Related

TagA chip for labels and categories. Optionally a link, optionally removable.
AvatarA user image, with an initials fallback derived from name.
StatDisplays a labelled metric with an optional trend indicator. For dashboards and summary rows.