List Groups

A list group is a bordered stack of items used for menus, notification feeds, settings panels and any list that needs more structure than plain bullets. Items can be links, buttons or static text, carry badges and custom content, and take contextual colors. This lesson covers every variant, including flush lists inside cards, horizontal lists, numbered lists and checkbox lists.

Basic List Group

html

<ul class="list-group">
  <li class="list-group-item">Inbox</li>
  <li class="list-group-item">Sent</li>
  <li class="list-group-item">Drafts</li>
</ul>

.list-group removes bullets and adds a border around the whole list; .list-group-item adds padding and borders between items. Mark the current item with .active plus aria-current="true", and disable one with .disabled (add aria-disabled="true" if it is a link or button).

Actionable Items

For clickable items, use <a> or <button> elements inside a <div class="list-group"> and add .list-group-item-action, which provides hover, focus and active styles:

html

<div class="list-group">
  <a href="/settings/profile" class="list-group-item list-group-item-action active" aria-current="true">Profile</a>
  <a href="/settings/security" class="list-group-item list-group-item-action">Security</a>
  <button type="button" class="list-group-item list-group-item-action">Sign out</button>
</div>

Use <a> for navigation and <button> for in-page actions. Do not put <a> inside <li> here; the action styling expects the link itself to be the item.

Flush, Numbered and Horizontal Lists

Flush lists inside cards

.list-group-flush removes the outer border and rounded corners so the list sits edge to edge inside a parent such as a card:

html

<div class="card" style="max-width: 320px">
  <div class="card-header">Team</div>
  <ul class="list-group list-group-flush">
    <li class="list-group-item">Ada</li>
    <li class="list-group-item">Grace</li>
    <li class="list-group-item">Linus</li>
  </ul>
</div>

Numbered lists

Use an <ol> with .list-group-numbered. Numbers are generated with CSS counters, so they stay aligned even with multi-line content:

html

<ol class="list-group list-group-numbered">
  <li class="list-group-item d-flex justify-content-between align-items-start">
    <div class="ms-2 me-auto">
      <div class="fw-bold">Install Node.js</div>
      Any current LTS release.
    </div>
    <span class="badge text-bg-secondary rounded-pill">2 min</span>
  </li>
  <li class="list-group-item">Run <code>npm install</code></li>
</ol>

Horizontal lists

.list-group-horizontal lays items out in a row. Add a breakpoint infix to stack on small screens and go horizontal from that size:

html

<ul class="list-group list-group-horizontal-md">
  <li class="list-group-item flex-fill">Overview</li>
  <li class="list-group-item flex-fill">Usage</li>
  <li class="list-group-item flex-fill">Billing</li>
</ul>

flex-fill gives every item equal width. Horizontal lists cannot be combined with .list-group-flush.

Contextual Colors

list-group-item-{color} tints an item with one of the theme colors: primary, secondary, success, danger, warning, info, light, dark. The colors adapt automatically in dark mode:

html

<ul class="list-group">
  <li class="list-group-item list-group-item-success">Payment received</li>
  <li class="list-group-item list-group-item-warning">Invoice due in 3 days</li>
  <li class="list-group-item list-group-item-danger">Card declined</li>
</ul>

Combined with .list-group-item-action, the hover state uses a darker shade of the same color.

Checkboxes and Radios

A list group is a tidy way to present a set of options. Put the input and label inside each item:

html

<div class="list-group">
  <label class="list-group-item d-flex gap-2">
    <input class="form-check-input flex-shrink-0" type="checkbox" value="email" checked>
    <span>Email <small class="d-block text-secondary">Weekly summary</small></span>
  </label>
  <label class="list-group-item d-flex gap-2">
    <input class="form-check-input flex-shrink-0" type="radio" name="plan" value="pro">
    <span>Pro plan</span>
  </label>
</div>

Because the whole <label> is the item, clicking anywhere on the row toggles the input.

List Groups as Tab Triggers

The tab plugin accepts list group items as triggers. Give each item data-bs-toggle="list" and a href pointing at the pane:

html

<div class="row">
  <div class="col-4">
    <div class="list-group" role="tablist">
      <a class="list-group-item list-group-item-action active" data-bs-toggle="list" href="#home" role="tab">Home</a>
      <a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#profile" role="tab">Profile</a>
    </div>
  </div>
  <div class="col-8">
    <div class="tab-content">
      <div class="tab-pane fade show active" id="home" role="tabpanel">Home content</div>
      <div class="tab-pane fade" id="profile" role="tabpanel">Profile content</div>
    </div>
  </div>
</div>

This is the standard pattern for vertical settings pages; the tab plugin is covered in detail in the navs lesson.

Common Mistakes

Using .list-group-item-action on <li>. Hover styles only make sense on links and buttons; use <div class="list-group"> with <a>/<button> children.
Forgetting aria-current. .active is visual only; screen readers need the attribute.
Combining flush with horizontal. The two variants are mutually exclusive.
Nesting cards inside items. Use the custom content pattern (d-flex, headings, small) instead.

Key Takeaways

.list-group with .list-group-item builds bordered lists; .active and .disabled mark states (with matching ARIA attributes).
.list-group-item-action on <a> or <button> items adds hover and focus styles.
.list-group-flush fits lists into cards; .list-group-numbered uses CSS counters; .list-group-horizontal{-bp} lays items in a row.
list-group-item-{color} applies theme colors that adapt to dark mode.
List items can host checkboxes, radios, badges, custom content and tab triggers via data-bs-toggle="list".

Next lesson: Navbars and Navigation - responsive navbars with brand, links, forms and collapsing menus.