LearnAI ToolsCareerPractice BuildsPlayContact
Lesson 2416 min read

List Groups

Learn how to build flexible list components with Bootstrap list groups, including active and disabled states and linked items.

Introduction

List groups are a versatile component for displaying a series of related items, from a simple bulleted list to an interactive, clickable navigation menu. The same .list-group / .list-group-item pattern can render a plain list, a set of links, a set of buttons, or a two-column layout with badges — all without writing custom CSS.

What You Will Learn
  • Building a basic list group from unordered list markup.
  • Marking items active or disabled.
  • Turning list items into links or buttons.
  • Flush and horizontal list group variants.
  • Adding contextual colors and badges to items.

Basic List Group

Wrap a <ul> with class="list-group" and give each <li> the class="list-group-item". Bootstrap removes the default bullet points and adds borders and padding automatically.

<ul class="list-group">
  <li class="list-group-item">HTML & CSS Basics</li>
  <li class="list-group-item">JavaScript Fundamentals</li>
  <li class="list-group-item">Responsive Design</li>
  <li class="list-group-item">Bootstrap Components</li>
</ul>
Result

Click Run to see what this code prints.

Active & Disabled Items

Add .active to highlight the currently selected item (with aria-current="true" for accessibility), and .disabled to gray out and functionally disable an item.

<ul class="list-group">
  <li class="list-group-item active" aria-current="true">Current Item</li>
  <li class="list-group-item">Regular Item</li>
  <li class="list-group-item disabled" aria-disabled="true">Disabled Item</li>
</ul>

Linked List Groups

Instead of <li> elements, use <a> tags with class="list-group-item list-group-item-action" wrapped in a <div class="list-group"> to turn the list into a set of clickable, hoverable navigation links.

<div class="list-group">
  <a href="#profile" class="list-group-item list-group-item-action active" aria-current="true">
    Profile
  </a>
  <a href="#settings" class="list-group-item list-group-item-action">Settings</a>
  <a href="#billing" class="list-group-item list-group-item-action">Billing</a>
  <a href="#" class="list-group-item list-group-item-action disabled">Archived (disabled)</a>
</div>

You can use <button> elements instead of <a> tags the same way — just add type="button" and swap the wrapping element to a <div>. Buttons are the right choice when the action is not real navigation to a new URL or hash.

Flush List Groups

Add .list-group-flush to remove the outer border and rounded corners, which is useful when a list group sits inside another container like a card that already provides its own border.

<div class="card">
  <div class="card-header">Recent Notifications</div>
  <ul class="list-group list-group-flush">
    <li class="list-group-item">New comment on your post</li>
    <li class="list-group-item">Your invoice is ready</li>
    <li class="list-group-item">Password changed successfully</li>
  </ul>
</div>

Horizontal List Groups

Add .list-group-horizontal (or a breakpoint variant like .list-group-horizontal-md) to lay items out in a row instead of a column on qualifying screen sizes.

<ul class="list-group list-group-horizontal-md">
  <li class="list-group-item">Step 1</li>
  <li class="list-group-item">Step 2</li>
  <li class="list-group-item">Step 3</li>
</ul>

Contextual Colors & Badges

Contextual classes like .list-group-item-success color individual items with meaning, and Bootstrap badges pair naturally with list items using flexbox utilities to sit at the end of the row.

<ul class="list-group">
  <li class="list-group-item list-group-item-success">Task completed</li>
  <li class="list-group-item list-group-item-warning">Needs review</li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Inbox
    <span class="badge text-bg-primary rounded-pill">14</span>
  </li>
</ul>

Custom Content

List group items are not limited to plain text — combine headings, paragraphs, and flex utilities inside each item for richer content, such as a chat message list or a to-do item with metadata.

<div class="list-group">
  <a href="#" class="list-group-item list-group-item-action">
    <div class="d-flex w-100 justify-content-between">
      <h6 class="mb-1">New message from Priya</h6>
      <small class="text-body-secondary">3 mins ago</small>
    </div>
    <p class="mb-1">Can you review the pull request when you get a chance?</p>
    <small class="text-body-secondary">Slack</small>
  </a>
</div>

Common Mistakes

Avoid These Mistakes
  • Mixing <li> children under a <div class="list-group"> — <li> requires a <ul>/<ol> parent; use <div>/<a>/<button> children under a <div> wrapper instead.
  • Forgetting .list-group-item-action on linked/button items, which leaves out the hover and focus styling that signals interactivity.
  • Using .disabled on a real <a href> without also removing/adjusting the href, since disabled links remain focusable and clickable via keyboard in some browsers.
  • Applying .active to more than one item when only a single selection makes sense.

Best Practices

  • Use <ul>/<li> for static, non-interactive lists and <div>/<a> or <div>/<button> for interactive ones.
  • Add aria-current="true" to the active item in a linked list group for screen reader clarity.
  • Use .list-group-flush when nesting inside cards or panels that already have borders.
  • Reach for contextual item classes sparingly, only where status genuinely needs to stand out.

Frequently Asked Questions

Yes. Use <button type="button" class="list-group-item list-group-item-action"> inside a <div class="list-group"> for actions that are not navigation, like opening a modal or toggling a selection.

Wrap it in a container with a fixed height and overflow-y: auto, e.g. a <div style="max-height: 300px; overflow-y: auto;"> around the list group.

.active is meant for the single currently selected item (solid background using the theme color), while .list-group-item-primary is a softer contextual tint you can apply to any number of items to convey status.

Key Takeaways

  • List groups use .list-group on the wrapper and .list-group-item on each item.
  • Swap <li> for <a>/<button> plus .list-group-item-action to make items interactive.
  • .active marks the current selection; .disabled turns an item off.
  • .list-group-flush and .list-group-horizontal-* adapt the component to different layouts.

Summary

List groups turn a simple list of items into anything from a static index to a fully interactive navigation menu, badge-driven notification list, or chat feed, using the same small set of classes throughout. Next, you will learn how to build pagination controls for splitting content across multiple pages.

Next Lesson →

Pagination