Badge

Overview

Badge is one of the most common display primitives in the brand dashboard.

It is the default pill-style label for:

• entity and workflow status
• metadata qualifiers such as roles, categories, and types
• compact icon-plus-label chips in tables, cards, and panels
• short clickable pills in secondary interactions

The primitive itself is intentionally small:

• one required label
• optional color
• optional Icon or imageSrc
• optional onRemove
• optional onClick

Most of the meaning comes from the calling feature mapping domain values to badge labels and colors.

Basic Usage

import { Badge } from '@fsai/shared-ui';

<Badge label="Active" color="green" />
<Badge label="Pending Review" color="orange" />
<Badge label="Draft" color="gray" />

With Icon Or Image

Use Icon for compact semantic reinforcement:

<Badge label="Registered" color="green" Icon="CircleCheck" />
<Badge label="Operations" color="blue" Icon="Suitcase" />

Use imageSrc when the badge should show a tiny image or avatar-like thumbnail. imageSrc takes precedence over Icon.

<Badge
  label="Jane Applicant"
  imageSrc={leadAvatar}
  color="white"
/>

Colors

Badge does not have semantic variants like success or warning. Instead, product code maps business meaning to one of the supported badge colors:

Keep these mappings close to the feature or domain config instead of scattering ad hoc inline choices everywhere.

Props

Common Usage Patterns

Status Badge

The most common pattern is a small mapping helper:

const PROJECT_STATUS_CONFIG = {
  active: { label: 'Active', color: 'green' },
  paused: { label: 'Paused', color: 'orange' },
  archived: { label: 'Archived', color: 'gray' },
} as const;

<Badge
  label={PROJECT_STATUS_CONFIG[status].label}
  color={PROJECT_STATUS_CONFIG[status].color}
/>

This keeps label and color decisions consistent across tables, panels, and cards.

Metadata Pill

For roles, types, categories, and other qualifiers, badges are often neutral or lightly emphasized:

<Badge label="Operations" color="blue" Icon="Suitcase" />
<Badge label="Pending Invite" color="orange" />

Clickable Secondary Badge

Some screens use Badge as a small clickable affordance:

<Badge
  label={lead.name}
  imageSrc={lead.imageSrc}
  color="white"
  onClick={() => openLeadPanel(lead.id)}
  className="hover:bg-gray-bg-accent transition"
/>

This is acceptable for secondary interactions, but Badge is still not a native button component.

One important use case is related-entity navigation in dense surfaces such as panel headers, where the badge gives a compact way to jump to the linked entity without adding a larger row or card.

Brand Dashboard Usage Patterns

Representative usages:

Important Conventions

• Badge is a generic display primitive. It does not know your domain statuses by itself.
• Prefer a small config object or helper to map domain values to badge label, color, and optional Icon.
• imageSrc overrides Icon.
• The root element is a span, not a button. If the badge becomes a meaningful action, make sure the interaction remains accessible.
• Long labels truncate inside the pill, so keep labels short and stable.
• Some features use specialized badge-like components such as VendorTypeBadge, InlineEntityManager.Badge, or other local wrappers. Use the primitive Badge when you need the generic platform pill rather than a domain-specific abstraction.
• For cross-linking to related entities, Badge is best when the relationship is secondary metadata. Use a real button or richer row/card when the relationship is more important than a compact pill can comfortably express.

Guidelines

• Do use Badge for short status and metadata labels in lists, tables, cards, and panels
• Do centralize color-and-label mappings for business enums
• Do keep labels short enough to survive narrow columns
• Do use an icon when it adds meaning, not just decoration
• Don't treat Badge as a primary action control
• Don't invent ad hoc pill styles when the standard badge already fits