Skip to main content

List groups

List groups are a flexible and powerful component for displaying a series of content. Modify and extend them to support just about any content within.

Idea React provides the ListGroup and ListGroupItem wrappers for these examples. Items render a <li> by default, an <a> when given href, and a <button> when given type.

Basic example

The most basic list group is an unordered list with list items. Build upon it with the options that follow, or with your own CSS as needed.

  • An item
  • A second item
  • A third item
  • A fourth item
  • And a fifth one

Active items

Add active to a ListGroupItem to indicate the current active selection. The wrapper also sets aria-current="true" for assistive technologies.

  • An active item
  • A second item
  • A third item
  • A fourth item
  • And a fifth one

Links and buttons

Pass href to render actionable <a> items, or type to render <button> items, and add action for hover, disabled, and active states. The action class is separate from the base item class so list groups built from non-interactive elements do not gain a click affordance.

Set disabled to make action items appear disabled and inform assistive technologies. Disabled items also receive .pe-none (pointer-events: none), so they cannot be activated with the pointer; links additionally drop their href and click handler, while buttons receive the native disabled attribute. Be sure to not use the standard btn classes here.

With buttons, you can also make use of the disabled attribute instead of the disabled class. Unlike <a>s, <button>s support it natively.

Flush

Add flush to remove some borders and rounded corners so items render edge-to-edge in a parent container, such as a card.

  • An item
  • A second item
  • A third item
  • A fourth item
  • And a fifth one

Numbered

Add numbered to opt into numbered list group items. Numbers are generated via CSS instead of the browser's default <ol> styling, which places them better inside list group items and allows for more customization.

  • A list item
  • A list item
  • A list item

Numbered items work great with custom content as well.

  • SubheadingContent for list item
    14
  • SubheadingContent for list item
    14
  • SubheadingContent for list item
    14

Horizontal

Set horizontal to change the layout of list group items from vertical to horizontal across all container sizes. Alternatively, pass a breakpoint (sm, md, lg, xl, or 2xl) to make the list group horizontal starting at that width.

Responsive variants use container queries, so wrap the list group in a query container with the contains-inline utility for them to take effect. Horizontal list groups currently cannot be combined with flush.

  • An item
  • A second item
  • A third item
  • An item
  • A second item
  • A third item
  • An item
  • A second item
  • A third item

Want equal-width items when horizontal? Add the flex-fill utility to each item.

  • An item
  • A second item
  • A third item

Variants

Use the theme prop on items to style them with a stateful background and color.

  • A simple default list group item
  • A simple primary list group item
  • A simple accent list group item
  • A simple secondary list group item
  • A simple success list group item
  • A simple danger list group item
  • A simple warning list group item
  • A simple info list group item
  • A simple light list group item
  • A simple dark list group item
  • A simple inverse list group item

For links and buttons

Themes also work with action items rendered as links or buttons. Notice the hover styles that are not present in the non-interactive example above. The active state is supported as well.

With badges

Add Badge elements to any list group item to show unread counts, activity, and more with the help of some flexbox utilities.

  • A list item 14

  • A second list item 2

  • A third list item 1

Custom content

Add nearly any HTML within an item, even for linked list groups, with the help of the same flexbox utilities.

Checkboxes and radios

Place Bootstrap's checkboxes and radios within list group items and customize as needed. You can use them without <label>s, but please remember to include an aria-label attribute and value for accessibility.

You can use the stretched-link utility on <label>s to make the whole list group item clickable.

JavaScript behavior

The wrapper covers list group markup and styles. To create tabbable list group panes, pair the items with an application-level tab implementation as described in the upstream list group documentation.

CSS

List group colors, borders, and spacing are driven by Bootstrap's .list-group CSS variables and Sass maps. See the upstream list group CSS for the variable reference.