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"
    | "outlineNeutral"
    | "outlineNavy"
    | "outlineBerry"
    | "outlineSage"
    | "outlineOrange"
  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
• defaultNeutral / defaultNavy / defaultBerry / defaultSage / defaultOrange: Filled badges using primitive color tokens; use for status, categories, or emphasis by color.
• outlineNeutral / outlineNavy / outlineBerry / outlineSage / outlineOrange: Outline badges with a solid light background (50-step), colored border (200-step), and matching text; use for subtle tags or secondary emphasis.

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. Anatomy:

Default (filled) — 5 color variants

Outline — 5 color variants (solid light background, 1px border, matching text)

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>

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: April 22, 2026