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.

Appearance

• Color (color) — grey, accent, neutral-outline, accent-outline, red, raspberry, clementine, yellow, green, teal, blue, plum, purple, plus the semantic values neutral, critical, caution, success, and information. Defaults to neutral (grey).
• Use a semantic value (neutral, critical, caution, success, information) when the color conveys meaning, since those carry consistent meaning across the application. Use the raw hues for non-semantic categorization.
• Font weight (bold) — defaults to true. Set bold={false} where the Badge should be less visually prominent. Light text is not available on a status Badge.

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 restricts color to red, yellow, green, blue, purple, grey, or a semantic value. Any other color throws a runtime error.
• showStatusIndicator requires bold to stay true (the default). Combining it with bold={false} throws a runtime error.
• Omitting color with showStatusIndicator resolves to neutral, which renders a grey dot.
• Each semantic value renders identically to an underlying hue: neutral = grey, critical = red, caution = yellow, success = green, information = blue. purple is the one indicator color with no semantic alias. Test helpers report semantic values via getSemanticColor() and the underlying hue via getColor().
• 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.