Skip to content

List Group ​

Overview ​

List Groups display a collection of related items in a structured, vertical format. They can be used to present static content or function as interactive navigation elements.

List Groups work well when items are semantically related and benefit from consistent formatting.

Guidelines ​

Dos ​

  • Use List Groups to display related items in a clear, scannable list.
  • Limit List Groups to 5–7 items for optimal readability.
  • Use consistent structure and formatting across all items in a group.
  • Use badges to display counts or quantitative information when helpful.

Don’ts ​

  • Don’t use List Groups for long or unbounded lists without pagination or filtering.
  • Don’t mix different content types (e.g., links, actions, metadata) within the same List Group.
  • Don’t use List Groups for primary page actions.
  • Don’t include badges without clear meaning or context.
  • Don’t present unrelated or unordered items together.

Variants ​

VariantDescriptionExample Use
Static List GroupNon-interactive list of related contentSummaries, read-only lists
Linked List GroupInteractive list where each item navigatesNavigation menus, drill-down views
List Group with BadgesList items enhanced with count indicatorsItem totals, notifications
Active item.active on a linked item for a persistent selected stateThe current category in a filter list

Structure ​

List Groups should follow a clear and predictable structure.

  • Use a single List Group container per collection.
  • Ensure all items follow the same layout and hierarchy.
  • Order items logically (alphabetical, chronological, or by priority).

Interaction ​

When List Groups are interactive:

  • Each item should act as a single clickable target.
  • Provide clear hover, active, and selected states.
  • Add .active to the linked item that represents the current selection (for example the active category in a filter list) — it gets a blue tint and stops receiving pointer events.
  • Avoid embedding additional interactive elements inside list items.

Badges ​

Badges may be used within List Groups to show counts or status.

  • Place badges consistently within each item (typically aligned right).
  • Ensure badge values are meaningful and clearly labeled by context.
  • Avoid using badges as the sole indicator of importance.

Badges — Count and status indicators.

List Group ​