Badge Group

A wrapping layout container for related badges.

Component

Use fd-badge-group when several static badges belong to one visible set and need consistent wrapping. The group manages layout and optional shared naming, not interactivity.

When to use

• Related tag sets — when several badges describe one record, application, or page state.
• Dense metadata summaries — when compact labels need a consistent, responsive wrapper.
• Optional shared semantics — when the set benefits from a label such as “Account tags”.

When not to use

• One badge — a single badge does not need a grouping wrapper.
• Dismissible sets — use Chip Group when each item has a remove action.
• Action clusters — fd-badge-group is not a toolbar or menu substitute.

Examples

Badge groups wrap related static badges and can expose an optional shared label. View in Storybook →

Properties

Name	Type	Default	Description
label	string | undefined	undefined	Adds role="group" and aria-label when the badge set benefits from a shared accessible name.

Slots

Name	Description
(default)	One or more fd-badge elements.

CSS custom properties

Name	Default	Description
--fd-badge-group-gap	var(--fdic-spacing-2xs, 4px)	Gap between badges in the wrapping layout.

Shadow parts

Name	Description
container	Internal wrapping flex container.

Best practices

Do

Group related labels together

Badges are easier to scan when they all describe the same entity or section.

Don't

Use badge groups for actions

If users need to act on the items, move to chips, buttons, or another interactive pattern.

Content guidelines

• Keep the label set coherent. Avoid mixing unrelated statuses and tags in the same visual group.
• Use a shared group label only when it adds meaning. “Account tags” is useful; repeating what the badges already say is not.

Accessibility

• fd-badge-group is presentational by default.
• When label is provided, the internal wrapper gets role="group" and aria-label.
• The component preserves DOM order as badges wrap, so reading order and scan order stay stable.
• The group does not imply interactivity for its children.

Known limitations

• fd-badge-group does not enforce that every child is an fd-badge.
• The component is a layout wrapper only; list semantics and richer set management stay out of scope for v1.

Related components

• Badge — static pill used inside the group
• Chip Group — layout wrapper for dismissible chips
• Alert — use alerts instead when the information is time-sensitive or requires attention