Badge

Import

import { Badge } from "@timelycare/helix-ui"

Props

interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
  variant?:
    | "default"
    | "secondary"
    | "outline"
    | "destructive"
    | "ghost"
    | "link"
    | "defaultNeutral"
    | "defaultNavy"
    | "defaultBerry"
    | "defaultSage"
    | "defaultOrange"
    | "defaultSky"
    | "defaultSand"
    | "outlineNeutral"
    | "outlineNavy"
    | "outlineBerry"
    | "outlineSage"
    | "outlineOrange"
    | "outlineSky"
    | "outlineSand"
    | "success"
    | "warning"
    | "info"
    | "outlineSuccess"
    | "outlineWarning"
    | "outlineInfo"
  asChild?: boolean
  className?: string
  children: React.ReactNode
}

Variants

Choosing a Variant

• Default: Main categories, active status, primary labels
• Secondary: Tags, neutral metadata, less important info
• Outline: Minimal styling, subtle indicators, bordered tags
• Destructive: Errors, removal actions, critical status
• Ghost: Ultra-minimal, no background or border
• Link: Navigational badges with underline on hover
• success / warning / info: Filled status badges. Reach for these first when the badge reports a state — they read as the state rather than as a colour, and they match the names Alert already uses.
• outlineSuccess / outlineWarning / outlineInfo: The same three states in the quieter outline treatment.
• defaultNeutral / defaultNavy / defaultBerry / defaultSage / defaultOrange / defaultSky / defaultSand: Filled badges using primitive color tokens; use for categories, brand emphasis, or any decorative chip that a status name would mislabel. These colour names are permanent — a defaultNavy category chip is not info.
• outlineNeutral / outlineNavy / outlineBerry / outlineSage / outlineOrange / outlineSky / outlineSand: Outline badges with a solid light background (50-step), colored border (200-step), and matching text; use for subtle tags or secondary emphasis.

The six status names are aliases, not new looks: each resolves to exactly the same class string as the colour variant beside it in the table above, so the two can never drift apart.

Badge's filled warning is a lighter ramp step than Alert's, and that is deliberate. Alert uses its tone as a rail (3:1, WCAG 1.4.11); Badge uses its tone as a text background (4.5:1, WCAG 1.4.3). tc-orange-300 + black measures 14.08:1; matching Alert's tc-orange-700 with white would be 4.20:1 — an AA failure at Badge's 12px text. Different bars, different steps.

Styling

Typography

Dimensions

All badges use the full rounded (pill) shape. Do not use rounded-sm or other radii for badge components.

Color variants (primitive tokens)

Filled (default) and outline variants use Helix primitive color scales. Every colour ships in both treatments; the table below is the authority on how many there are. Anatomy:

Default (filled) — one row per color

defaultSky and defaultSand join the light filled recipe (light fill + black text, as defaultOrange does) rather than the dark one. sky-600 would have been the tightest pair in the family against the navy fill (#16538E) by more than double — ΔE76 26.8, while sitting only ΔE 19.1 from sky-400 itself, i.e. nearly as close to a different tone as to another step of its own ramp. sky-400 sits ΔE 43.0 from navy.

Outline — one row per color (solid light background, 1px border, matching text)

The house recipe is -50 fill / -200 border / the first text step clearing 4.5:1. For sky and sand that step is forced to -700, not chosen: sky-600 on sky-50 measures 4.49:1 (misses by 0.01) and light-sand-600 on light-sand-50 measures 4.02:1. Badge text is text-xs (12px), so the WCAG large-text allowance does not apply. Do not simplify these back to -600 — it is the same call already made for outlineBerry.

Icons

Size: size-3 (12×12px) — automatic via [&>svg]:size-3 Spacing: gap-1 (4px) — built into badge flex layout

States

Common Patterns

Basic Variants

<Badge>Default</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="outline">Outline</Badge>
<Badge variant="destructive">Destructive</Badge>

Status Badges

<Badge variant="success">Active</Badge>
<Badge variant="warning">Expiring</Badge>
<Badge variant="info">Scheduled</Badge>
<Badge variant="outlineSuccess">Verified</Badge>

With Icons

import { Check, ArrowRight } from "lucide-react"

<Badge>
  <Check />
  Approved
</Badge>

<Badge>
  Link
  <ArrowRight />
</Badge>

Notification Count (Badge Number)

// Single digit - circular
<Badge className="size-5 rounded-full p-0 justify-center">8</Badge>

// Double digit
<Badge className="h-5 min-w-5 rounded-full px-1.5 justify-center">99</Badge>

// Overflow
<Badge className="rounded-full px-2">20+</Badge>

Pending/Processing

<Badge variant="outline" className="gap-1">
  <LoaderCircle className="size-3 animate-spin" />
  Processing
</Badge>

In Context

// With card title
<div className="flex items-center gap-2">
  <CardTitle>Article Title</CardTitle>
  <Badge variant="secondary">New</Badge>
</div>

// User status
<div className="flex items-center gap-2">
  <Avatar />
  <span>Username</span>
  <Badge className="gap-1">
    <BadgeCheck />
    Verified
  </Badge>
</div>

Component Structure

{/* Standard Badge */}
<span className="inline-flex items-center justify-center gap-1 rounded-full bg-primary px-2 py-0.5 text-xs font-semibold text-primary-foreground">
  {/* Optional left icon */}
  <Check className="size-3" />
  
  {/* Badge text */}
  Badge
  
  {/* Optional right icon */}
  <ArrowRight className="size-3" />
</span>

{/* Badge Number (circular) */}
<span className="inline-flex size-5 items-center justify-center rounded-full bg-primary p-0 text-xs font-semibold text-primary-foreground">
  8
</span>

Accessibility

• Styled inline element — no interactive behavior
• Screen reader: reads badge text content automatically
• Use aria-label if badge meaning isn't clear from text alone
• No keyboard interaction (non-interactive element)
• Use asChild to render as a different element (e.g., anchor for linked badges)

Gotchas

See Also

• Related Components: Avatar (avatar with status badge), Button (actionable badges)
• Tokens: Colors — Theme-aware color tokens

Last updated: August 19, 2026