Badge
A static text-first pill for tags, categories, and lightweight status labels.
Component
Use fd-badge when you need a compact visible label without adding another button or link to the interface. The text stays primary; color only supports scanning.
When to use
- Status labels — short states like “Approved” or “Past due”.
- Categorical tags — compact labels such as “Small business” or “Branch office”.
- Dense supporting context — when users benefit from a lightweight visual cue that does not add interaction.
When not to use
- Dismissible items — use Chip when the user must remove one item from a visible set.
- Clickable pills —
fd-badgeintentionally does not expose host-level interaction in v1. - Critical warnings or recovery guidance — use a fuller message pattern when the user needs explanation, prevention, or next steps.
Examples
Properties
| Name | Type | Default | Description |
|---|---|---|---|
type | "neutral" | "cool" | "warm" | "positive" | "alert" | neutral | Visual tone for the badge surface. |
Slots
| Name | Description |
|---|---|
| (default) | Visible badge label text. |
CSS custom properties
| Name | Default | Description |
|---|---|---|
--fd-badge-height | 28px | Minimum badge height. |
--fd-badge-padding-inline | var(--fdic-spacing-sm, 12px) | Horizontal badge padding. |
--fd-badge-radius | 9999px | Pill corner radius. |
--fd-badge-font-size | var(--fdic-font-size-body-small, 1rem) | Label font size. |
--fd-badge-text-color | var(--fdic-color-text-primary, #212123) | Shared text color across tones. |
--fd-badge-bg-neutral | light-dark(var(--fdic-color-neutral-200), var(--fdic-color-neutral-800)) | Neutral badge background. Uses stronger neutral surfaces in light and dark themes so neutral badges remain visually comparable with semantic badge types. |
--fd-badge-bg-cool | var(--fdic-color-info-050, #f1f8fe) | Cool badge background. |
--fd-badge-bg-warm | var(--fdic-color-secondary-050, #f8efda) | Warm badge background. |
--fd-badge-bg-positive | var(--fdic-color-success-050, #e8f5e9) | Positive badge background. |
--fd-badge-bg-alert | var(--fdic-color-error-050, #fdedea) | Alert badge background. |
Shadow parts
| Name | Description |
|---|---|
container | Outer pill container. |
label | Visible label wrapper. |
Tone guidance
Choose the tone that supports scanning without replacing the label text:
| Tone | When to use | Example labels |
|---|---|---|
neutral | Default. General-purpose tags and categories with no semantic weight. | "Branch office", "Q4 2025" |
cool | Informational context that benefits from a subtle blue tint. | "New", "Updated" |
warm | Items that need mild visual emphasis without implying risk. | "Pending review", "Draft" |
positive | Conditions that represent a good or completed state. | "Approved", "Active" |
alert | Conditions that need attention, without reaching alert-level urgency. | "Past due", "Expiring soon" |
The text must carry the meaning on its own. Tone only supports scanning — if the badge text says "Approved", the positive tone reinforces that at a glance, but a user who cannot perceive color still understands the status.
Best practices
Do
Keep the badge readable without color
The text should still carry the meaning if the user cannot perceive the tone.
Don't
Style a badge like a button
If the user can act on it, choose a component with real interaction semantics instead of a static badge.
Do
Use short, scannable labels
Compact phrases keep the badge lightweight and help avoid wrapping in dense layouts.
Don't
Treat a badge as your only warning copy
High-stakes conditions still need fuller surrounding text or message guidance.
Content guidelines
- Prefer plain language. Use direct terms like “Approved”, “Needs follow-up”, or “Small business”.
- Keep the label stable. Badges work best when the meaning does not change rapidly or require announcement behavior.
- Choose tone intentionally. Neutral is the baseline; use semantic tones only when the text also expresses that meaning.
Accessibility
fd-badgeis static by default. It does not expose a host button, link, or keyboard behavior in v1.- The visible label stays the primary meaning source. Tone is supportive, not sufficient on its own.
- Forced-colors support preserves a readable label and a visible pill boundary.
- The Figma source includes non-removable hover, pressed, and focus explorations. That host-level interactivity is intentionally out of scope for
fd-badgev1.
Known limitations
fd-badgeis not a clickable badge or notification counter in v1.- The component does not support built-in leading icons, avatars, or numeric-dot variants.
- Host-level hover, pressed, and focus visuals from the non-removable Figma exploration are intentionally not shipped in v1.
Choosing between Badge, Chip, and Alert
These three components are frequently confused. Use the right one:
- Badge (this component) = static metadata label. The user reads it but cannot act on it. Use for tags, categories, and status indicators.
- Chip = user-removable token. The user can dismiss it from a visible set. Use for active filters and selected items.
- Alert = system message requiring attention. Use for time-sensitive or high-priority information that changes the user's next step.
If the user can dismiss it, use a chip. If it communicates something urgent, use an alert. For everything else, use a badge.
Related components
- Chip — dismissible pill with a real remove button
- Badge Group — wrapping layout for related badges
- Chip Group — wrapping layout for related chips
- Alert — page-level or section-level messaging for time-sensitive information