Badge

Usage

• Use Badges to indicate status or categorize items with short descriptive text (e.g., "Active", "Draft"), or to display numeric quantities (e.g., notification counts).
• Use Tags, not Badges, for user-generated, interactive categorization that users can create, edit, or remove. Badges are read-only system indicators.
• Badge replaces the deprecated Label component. Never use Label in new code.

Variants

• Base (default) — no status indicator dot. Use for numeric quantities and for categorical attributes that describe what something is: types, tiers, roles, tags.
• Status (showStatusIndicator) — includes a colored dot. Use for operational status that describes where something is in its lifecycle: online/offline, running/stopped, active/draft.

Appearance

• color — available values: neutral, accent, neutral-outline, accent-outline, red, raspberry, clementine, yellow, green, teal, blue, plum, purple, grey, plus the semantic values critical, caution, success, information. Default is neutral.
• Use the semantic values (critical = red, caution = yellow, success = green, information = blue) when the color conveys meaning; use the raw colors only for decorative categorization.
• Default to a semantic value when using showStatusIndicator — a status dot usually implies the color carries meaning. But when the surrounding usage pairs the indicator with colors that have no semantic value (purple, grey), the context is established as non-semantic — follow the raw color values there for consistency.
• Use color consistently across the application for the same or similar statuses. Never use color purely for decoration.
• Status indicator semantic mapping: red = critical/destructive, yellow = warning, green = success/functional, blue = info, grey = neutral; purple is also supported in code but has no documented semantic meaning.
• Font weight (bold) — defaults to true. Use light text (bold={false}) where the Badge should be less visually prominent. Light text is not compatible with status indicators.
• isOutline and isEmphasized are deprecated. Use color="neutral-outline" instead of isOutline, color="accent" instead of isEmphasized, and color="accent-outline" instead of the combination. Never use the deprecated props in new code.

Content

• Limit text to one or two words, or a number.
• Use sentence case.
• Accurately describe the category or status.
• Never use long phrases or full sentences.

Implementation Notes

• Label-family colors (red–grey) render Label's squarer shape; neutral, accent, and the outline colors render as a fully-rounded pill. There is no shape prop — shape is derived from the color.
• The design docs' "light" font weight maps to bold={false} — there is no weight prop.
• showStatusIndicator restricts color to red, yellow, green, blue, purple, grey, or a semantic value. Other colors throw a runtime error.
• Semantic color values render identically to their underlying colors — test helpers report them via getSemanticColor(), while getColor() reports the underlying color.
• showStatusIndicator requires bold to remain true (the default). Setting bold={false} with showStatusIndicator throws a runtime error.
• The color prop cannot be combined with the deprecated isOutline/isEmphasized props — doing so throws a runtime error.
• Content — React uses children for badge text. Ember uses {{yield}} (default block) via <PlumaBadge>Text</PlumaBadge>.
• Badge extends Box — it renders as a <div> by default and can be changed via the as prop.
• Use as="span" when the badge sits in text flow (paragraphs, headings, links, buttons) — a <div> is invalid phrasing content there and the HTML parser closes an open <p> at a <div>. The deprecated Label rendered a <span>, so Label call sites in text flow must gain as="span" when migrated to Badge.