Icon Badge

Preview

When to use

Use an icon badge to visually reinforce a concept, category, or status with a distinct, coloured icon container. It works well for:

• Highlighting a feature or benefit in a feature list or card (e.g., a shield icon for security).
• Representing status at a glance in a summary or dashboard context.
• Adding visual hierarchy to a section heading or notification item.

When not to use

• Don't use an icon badge to convey status that needs a text label — use a Tag or Notification instead.
• Avoid using it as a standalone interactive element. It is decorative; it does not receive focus or handle click events.
• Don't use multiple large icon badges in close proximity — they compete for attention and reduce clarity.

Behaviour

The icon badge is a static, non-interactive element. It displays an icon centred within a coloured circular background. It does not have hover, focus, or active states.

Anatomy

• Container — a circular background in the chosen colour, sized to one of the six available sizes.
• Icon — centred within the container. The icon is always the same colour within each colour variant; it does not change independently.

Variants

Size — six sizes are available:

Choose the size that fits the surrounding content hierarchy — xSmall and Small suit dense lists, Large through 2xLarge suit prominent feature sections.

Colour — six semantic colours are available:

• White — neutral; use on coloured backgrounds.
• Green — positive, success, or confirmation.
• Soft — neutral or informational; the lowest visual emphasis.
• Warning — signals caution or a condition requiring attention.
• Critical — signals an important issue.
• Destructive — signals danger or an irreversible action.

States

The icon badge has no interactive states. It is always in its default, static state.

Placement & layout

Align the icon badge to the left or above the text it relates to. In a feature list, all badges in a column should use the same size for visual consistency.

Maintain adequate whitespace between the badge and adjacent text. At Medium size and above, a minimum gap of 12 px is recommended.

Accessibility

Icon badges are decorative by default. The icon inside does not carry standalone meaning for screen readers — ensure that the accompanying text provides the full message.

If an icon badge is used without adjacent text (e.g., as a standalone category marker), add a visually hidden label or aria-label to the container.

Related components

• Tag — for labelling items with text-based status or category markers.
• Notification — for feedback messages that require user attention.
• Image — for visual media that is content, not decorative decoration.