List group

Render simple lists, linked actions, flush groups, numbered items, and horizontal groups.

Overview

List groups are flexible content containers. BCL uses bs-listgroup for the wrapper and bs-listgroup-item for every item, with group type attributes for links, buttons, and ordered lists.

Basic example

The most basic list group is a list wrapper with individual items. Use bs-listgroup and bs-listgroup-item for the standard stacked shape, then layer helper options or utilities only when the example calls for them.

  • An item
  • A second item
  • A third item
  • A fourth item
aspnet 

<bs-listgroup flex-direction="Column">
    <bs-listgroup-item>An item</bs-listgroup-item>
    <bs-listgroup-item>A second item</bs-listgroup-item>
    <bs-listgroup-item>A third item</bs-listgroup-item>
    <bs-listgroup-item>A fourth item</bs-listgroup-item>
</bs-listgroup>

Active items

Set is-active="true" to indicate the current item. Add aria-current when the active item represents the current page or current choice.

  • An active item
  • A second item
  • A disabled item
aspnet 

<bs-listgroup flex-direction="Column">
    <bs-listgroup-item is-active="true" aria-current="True">An active item</bs-listgroup-item>
    <bs-listgroup-item>A second item</bs-listgroup-item>
    <bs-listgroup-item disabled="true">A disabled item</bs-listgroup-item>
</bs-listgroup>

Links and buttons

Use group-type="Links" or group-type="Buttons" when items should behave as actions instead of static list rows. Active and disabled states carry through to those action items.

Links

Link list groups render anchor items. Disabled anchors are styled as unavailable, but application code should still avoid sending keyboard users to inactive destinations.

Getting startedButtonsFormsDisabled link
aspnet 

<bs-listgroup group-type="Links" flex-direction="Column">
    <bs-listgroup-item href="/Docs/GettingStarted" is-active="true">Getting started</bs-listgroup-item>
    <bs-listgroup-item href="/Docs/Buttons">Buttons</bs-listgroup-item>
    <bs-listgroup-item href="/Docs/Forms">Forms</bs-listgroup-item>
    <bs-listgroup-item href="#" disabled="true">Disabled link</bs-listgroup-item>
</bs-listgroup>

Buttons

Button list groups are appropriate for in-page actions and tab-like controls because the items are not navigation links.

aspnet 

<bs-listgroup group-type="Buttons" flex-direction="Column">
    <bs-listgroup-item is-active="true">The current button</bs-listgroup-item>
    <bs-listgroup-item>A second button item</bs-listgroup-item>
    <bs-listgroup-item>A third button item</bs-listgroup-item>
    <bs-listgroup-item disabled="true">A disabled button item</bs-listgroup-item>
</bs-listgroup>

Flush

Flush list groups remove outer borders and rounded corners so the group can sit edge-to-edge inside a parent container such as a card.

  • Flush item
  • Another flush item
  • Final flush item
aspnet 

<bs-listgroup flex-direction="Column" flush="true">
    <bs-listgroup-item>Flush item</bs-listgroup-item>
    <bs-listgroup-item>Another flush item</bs-listgroup-item>
    <bs-listgroup-item>Final flush item</bs-listgroup-item>
</bs-listgroup>

Numbered

Use an ordered list group when item order is meaningful. Bootstrap renders the numbers with generated content, so custom item layouts can keep the marker aligned with headings, badges, or supporting text.

  1. Subheading
    Content for list item
    14
  2. A second numbered item
  3. A third numbered item
aspnet 

<bs-listgroup group-type="OrderedList" flex-direction="Column" numbered="true">
    <bs-listgroup-item display="Flex" justify-content="Between" align-items="Start">
        <bs-div start-margin="Default2" end-margin="Auto">
            <bs-div font-weight="Bold">Subheading</bs-div>
            Content for list item
        </bs-div>
        <bs-badge badge-style="Primary" pill="true">14</bs-badge>
    </bs-listgroup-item>
    <bs-listgroup-item>A second numbered item</bs-listgroup-item>
    <bs-listgroup-item>A third numbered item</bs-listgroup-item>
</bs-listgroup>

With badges

List group items can contain other BCL components, including bs-badge, when rows need counts, statuses, or compact metadata.

  • Inbox 14
  • Profile 2
  • Messages 1
aspnet 

<bs-listgroup flex-direction="Column">
    <bs-listgroup-item display="Flex" justify-content="Between" align-items="Center">
        Inbox
        <bs-badge badge-style="Primary" pill="true">14</bs-badge>
    </bs-listgroup-item>
    <bs-listgroup-item display="Flex" justify-content="Between" align-items="Center">
        Profile
        <bs-badge badge-style="Primary" pill="true">2</bs-badge>
    </bs-listgroup-item>
    <bs-listgroup-item display="Flex" justify-content="Between" align-items="Center">
        Messages
        <bs-badge badge-style="Primary" pill="true">1</bs-badge>
    </bs-listgroup-item>
</bs-listgroup>

Horizontal

Set horizontal-breakpoint to switch from stacked list items to a horizontal list group at a breakpoint. Horizontal list groups should not be combined with flush list groups.

  • First
  • Second
  • Third
aspnet 

<bs-listgroup horizontal-breakpoint="Small">
    <bs-listgroup-item>First</bs-listgroup-item>
    <bs-listgroup-item>Second</bs-listgroup-item>
    <bs-listgroup-item>Third</bs-listgroup-item>
</bs-listgroup>

Variants

Contextual variants add semantic color to individual list group items. Do not rely on color alone; include visible text or supporting content that communicates the same meaning.

  • A simple default list group item
  • A simple primary 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
aspnet 

<bs-listgroup flex-direction="Column">
    <bs-listgroup-item>A simple default list group item</bs-listgroup-item>
    <bs-listgroup-item item-style="Primary">A simple primary list group item</bs-listgroup-item>
    <bs-listgroup-item item-style="Secondary">A simple secondary list group item</bs-listgroup-item>
    <bs-listgroup-item item-style="Success">A simple success list group item</bs-listgroup-item>
    <bs-listgroup-item item-style="Danger">A simple danger list group item</bs-listgroup-item>
    <bs-listgroup-item item-style="Warning">A simple warning list group item</bs-listgroup-item>
    <bs-listgroup-item item-style="Info">A simple info list group item</bs-listgroup-item>
    <bs-listgroup-item item-style="Light">A simple light list group item</bs-listgroup-item>
    <bs-listgroup-item item-style="Dark">A simple dark list group item</bs-listgroup-item>
</bs-listgroup>

For links and buttons

Contextual item classes also work on link and button list groups. Pair color with active and disabled states carefully so current and unavailable actions remain clear.

A primary link itemA success link itemA danger link item
aspnet 

<bs-listgroup group-type="Links" flex-direction="Column">
    <bs-listgroup-item href="#" action="true" item-style="Primary">A primary link item</bs-listgroup-item>
    <bs-listgroup-item href="#" action="true" item-style="Success">A success link item</bs-listgroup-item>
    <bs-listgroup-item href="#" action="true" item-style="Danger">A danger link item</bs-listgroup-item>
</bs-listgroup>

Custom content

Link and button list group items can carry headings, timestamps, paragraphs, and badges. Keep the whole item target coherent when the row is interactive.

List group item heading

3 days ago

Some placeholder content in a paragraph.

And some small print.

List group item heading

3 days ago

Some placeholder content in a paragraph.

And some muted small print.
aspnet 

<bs-listgroup group-type="Links" flex-direction="Column">
    <bs-listgroup-item href="#" is-active="true">
        <bs-div display="Flex" bs-width="Relative100" justify-content="Between">
            <bs-heading heading-level="Three" bottom-margin="Default1" heading-style-level="Six">List group item heading</bs-heading>
            <bs-small>3 days ago</bs-small>
        </bs-div>
        <bs-p bottom-margin="Default1">Some placeholder content in a paragraph.</bs-p>
        <bs-small>And some small print.</bs-small>
    </bs-listgroup-item>
    <bs-listgroup-item href="#">
        <bs-div display="Flex" bs-width="Relative100" justify-content="Between">
            <bs-heading heading-level="Three" bottom-margin="Default1" heading-style-level="Six">List group item heading</bs-heading>
            <bs-small body-text-color="Secondary">3 days ago</bs-small>
        </bs-div>
        <bs-p bottom-margin="Default1">Some placeholder content in a paragraph.</bs-p>
        <bs-small body-text-color="Secondary">And some muted small print.</bs-small>
    </bs-listgroup-item>
</bs-listgroup>

Checkboxes and radios

Combine list group items with checks or radios when each row is a selectable option. Keep the form control and label inside the item so the row reads as one option.

aspnet 

<bs-listgroup flex-direction="Column">
    <bs-listgroup-item>
        <bs-check bottom-margin="None">
            <bs-input />
            <bs-label>First checkbox</bs-label>
        </bs-check>
    </bs-listgroup-item>
    <bs-listgroup-item>
        <bs-check bottom-margin="None">
            <bs-input />
            <bs-label>Second checkbox</bs-label>
        </bs-check>
    </bs-listgroup-item>
    <bs-listgroup-item>
        <bs-radio value="First" bottom-margin="None">
            <bs-label>First radio</bs-label>
        </bs-radio>
    </bs-listgroup-item>
</bs-listgroup>

JavaScript behavior

Use Bootstrap's list tab plugin by adding data-bs-toggle="list", href, and matching tab panes. BCL list group items pass data attributes through, while bs-tab-content-container and bs-tab-content render the pane structure.

Home tab content.
Profile tab content.
Messages tab content.
aspnet 

<bs-row x-gutter="Default3" y-gutter="Default3">
    <bs-div span-md="Four">
        <bs-listgroup group-type="Links" flex-direction="Column" id="docs-list-tab" role="tablist">
            <bs-listgroup-item href="#docs-list-home" is-active="true" data-bs-toggle="list" role="tab" aria-controls="docs-list-home">Home</bs-listgroup-item>
            <bs-listgroup-item href="#docs-list-profile" data-bs-toggle="list" role="tab" aria-controls="docs-list-profile">Profile</bs-listgroup-item>
            <bs-listgroup-item href="#docs-list-messages" data-bs-toggle="list" role="tab" aria-controls="docs-list-messages">Messages</bs-listgroup-item>
        </bs-listgroup>
    </bs-div>
    <bs-div span-md="Eight">
        <bs-tab-content-container id="docs-nav-tabContent">
            <bs-tab-content id="docs-list-home" is-active="true">Home tab content.</bs-tab-content>
            <bs-tab-content id="docs-list-profile">Profile tab content.</bs-tab-content>
            <bs-tab-content id="docs-list-messages">Messages tab content.</bs-tab-content>
        </bs-tab-content-container>
    </bs-div>
</bs-row>

Via JavaScript

List groups use Bootstrap's tab plugin APIs when list items are configured as tab triggers.

javascript 

const triggerTabList = document.querySelectorAll('#docs-list-tab a')
triggerTabList.forEach(triggerEl => {
const tabTrigger = new bootstrap.Tab(triggerEl)

triggerEl.addEventListener('click', event => {
    event.preventDefault()
    tabTrigger.show()
})
})

Fade effect

Add .fade to tab panes when list item changes should animate.

Methods

Bootstrap exposes show, dispose, getInstance, and getOrCreateInstance for list-triggered tab instances.

Events

List tab changes raise the tab plugin events: hide.bs.tab, hidden.bs.tab, show.bs.tab, and shown.bs.tab.