Badge

Usage

• Use Badge for a read-only category, quantity, or status that the system sets rather than the user — in table cells, list items, form labels, or page headings.
• Use Tag instead for a user-created categorization, such as a filter identifier, that a user can create, edit, and remove.
• Pair color with descriptive text. Never rely on color alone to carry the meaning.
• Use the same color for the same or similar status everywhere in the application. Never pick a color to fit a theme, and never use two colors for one status.
• Reserve the status indicator dot for an operational or lifecycle state such as online, running, or syncing. Never add it to a static category or tier, which has no state to indicate.

Types

• Base — no status indicator. Use for categorization, metadata, tiers, or numeric values that don't change with a lifecycle state.
• Status (showStatusIndicator) — adds a colored dot. Use for a process state within a lifecycle, such as success or failure. Requires bold to remain true.

Appearance

Variant

• variant — controls the visual style: subtle (default), solid, or outline.
  • subtle — lightly filled background matching the color (default for most uses).
  • solid — fully filled background with contrasting text; use for high emphasis.
  • outline — transparent background with a colored border and text; use for low emphasis.

Color

• color — accepts palette hues and semantic aliases. Default is neutral.
• Palette hues: red, rose, pink, orange, yellow, olive, lime, verdant, green, teal, sky, blue, violet, fuchsia, brown, silver, gray.
• Semantic aliases: neutral = gray, accent = teal, information = blue, success = green, caution = yellow, critical = red, feature = violet.
• Use a semantic alias when the color carries meaning; use a raw hue for purely decorative categorization.
• neutral — the default — marks a badge with no categorical meaning, such as a count.
• Default to a semantic value when using showStatusIndicator — a status dot usually implies the color carries meaning.

Migration from old color values

• Old color="accent" (solid teal) → variant="solid" color="accent" or variant="solid" color="teal".
• Old color="neutral-outline" → variant="outline" color="neutral".
• Old color="accent-outline" → variant="outline" color="accent".

Behaviors

• A Badge sizes itself to its content and wraps its text to a second line when the container is too narrow.
• Truncation (truncate) keeps the Badge on a single line and clips overflowing text with an ellipsis — use it in a fixed-width context such as a table column. Keep the label short enough to stay understandable when clipped.

Content

• Write Badge text in sentence case. Never use title case or all caps.
• Limit text to one or two words, or a number, that accurately describes the category or status.
• Never write a full phrase or sentence — a Badge sits inline with supporting text.

Implementation Notes

• Content — React passes badge text as children. Ember passes it through the default block: <PlumaBadge>Text</PlumaBadge>.
• The design docs' "light" font weight maps to bold={false}; there is no weight prop.
• showStatusIndicator requires bold to stay true (the default). Combining it with bold={false} throws a runtime error.
• showStatusIndicator is supported for all colors.
• Omitting color with showStatusIndicator resolves to neutral, which renders a gray dot.
• Each semantic alias renders as its underlying hue: neutral = gray, accent = teal, information = blue, success = green, caution = yellow, critical = red, feature = violet. Test helpers report semantic values via getSemanticColor() and the underlying hue via getColor(). getVariant() returns the active variant.
• Badge extends Box, so truncate and the other Box sprinkle props are available on it. Badge does not define truncate itself.
• Badge renders a <span>, valid in text flow (paragraphs, headings, links, buttons). Pass as to render a different element where the surrounding document structure calls for one.