tabler/docs/content/ui/components/list-group.mdx

---
title: List group
summary: A list group shows a series of related items in one block. Use it for simple lists, navigation, settings, and lists of records inside a card.
description: Group related items in one list.
source: core/scss/ui/_lists.scss
css-vars: list-group
classnames:
  component:
    - class: list-group
      desc: Container element
  part:
    - class: list-group-item
      desc: One entry
    - class: list-group-header
      desc: Section label between entries
    - class: list-group-item-media
      desc: Slot for an icon, an avatar or an input on the leading edge of an entry
    - class: list-group-item-content
      desc: Main slot of an entry; its presence turns the entry into a row of slots
    - class: list-group-item-title
      desc: First line of the content, cut with an ellipsis
    - class: list-group-item-description
      desc: Second line of the content, in the secondary color
    - class: list-group-item-meta
      desc: Slot for a time, a count or a badge after the content
    - class: list-group-item-actions
      desc: Slot for controls on the trailing edge of an entry
    - class: list-group-selectable-check
      desc: Checkbox or radio that marks its entry when checked
    - class: list-group-nested
      desc: Block of indented entries under a parent entry, usually a collapse
    - class: list-group-item-toggle
      desc: Chevron of a parent entry, turned over while its nested entries are open
  size:
    - class: list-group-sm
      desc: Compact entries
    - class: list-group-lg
      desc: Roomy entries
  style:
    - class: list-group-flush
      desc: Removes the outer border, to sit flush in a card
    - class: list-group-transparent
      desc: Removes the background and the borders
    - class: list-group-numbered
      desc: Numbers the entries
    - class: list-separated
      desc: Spaces the entries apart instead of joining them with borders
  behavior:
    - class: list-group-hoverable
      desc: Highlights the entry under the cursor
    - class: list-group-item-action
      desc: Marks an entry as a link or a button
    - class: list-group-selectable
      desc: Gives an entry with a checked input the active look
  direction:
    - class: list-group-horizontal
      desc: Lays the entries out in a row; -{breakpoint} only above that width
  color:
    - class: list-group-item-{color}
      desc: Tints one entry, for example list-group-item-success
---
import Example from '@components/Example.astro';
import Icon from '@ui/Icon.astro';

## Overview

Use the `list-group` class on the container and `list-group-item` on each row. Items share one border and stack on top of each other.

<Example bg="surface-secondary" column>
<div class="list-group">
  <div class="list-group-item">First item</div>
  <div class="list-group-item">Second item</div>
  <div class="list-group-item">Third item</div>
</div>
</Example>

The container can be any element. Use `ul` with `li` items for a real list, or `nav` with `a` items for navigation.

<Example bg="surface-secondary" column>
<ul class="list-group">
  <li class="list-group-item">First item</li>
  <li class="list-group-item">Second item</li>
  <li class="list-group-item">Third item</li>
</ul>
</Example>

## Item layout

An item can hold more than one line of text. Put a `list-group-item-content` element in the item and it becomes a row of slots:

- `list-group-item-media` - an icon, an avatar or an input before the content,
- `list-group-item-content` - the main part, with `list-group-item-title` and `list-group-item-description`,
- `list-group-item-meta` - a time, a count or a badge after the content,
- `list-group-item-actions` - buttons and other controls at the end.

Only the content slot is required. The title and the description are cut with an ellipsis when they do not fit.

<Example bg="surface-secondary" column>
<div class="list-group">
  <div class="list-group-item">
    <div class="list-group-item-media">
      <span class="avatar" style="background-image: url(/static/avatars/000m.jpg)"></span>
    </div>
    <div class="list-group-item-content">
      <div class="list-group-item-title">Paweł Kuna</div>
      <div class="list-group-item-description">UI Designer</div>
    </div>
    <div class="list-group-item-meta">2 h</div>
    <div class="list-group-item-actions">
      <button type="button" class="btn btn-sm">Follow</button>
    </div>
  </div>
  <div class="list-group-item">
    <div class="list-group-item-media">
      <span class="avatar" style="background-image: url(/static/avatars/016f.jpg)"></span>
    </div>
    <div class="list-group-item-content">
      <div class="list-group-item-title">Alice Marlin</div>
      <div class="list-group-item-description">Frontend developer</div>
    </div>
    <div class="list-group-item-meta">3 d</div>
    <div class="list-group-item-actions">
      <button type="button" class="btn btn-sm">Follow</button>
    </div>
  </div>
</div>
</Example>

The item itself can be a link or a `label`. Use a `label` with a checkbox, a radio or a switch inside, so a click on the whole row changes the input.

<Example bg="surface-secondary" column>
<div class="list-group">
  <label class="list-group-item">
    <span class="list-group-item-media"><Icon name="mail" color="muted" /></span>
    <span class="list-group-item-content">
      <span class="list-group-item-title">Email</span>
      <span class="list-group-item-description">A summary every morning</span>
    </span>
    <span class="list-group-item-actions">
      <span class="form-check form-switch m-0"><input type="checkbox" role="switch" class="form-check-input" checked /></span>
    </span>
  </label>
  <label class="list-group-item">
    <span class="list-group-item-media"><Icon name="device-mobile" color="muted" /></span>
    <span class="list-group-item-content">
      <span class="list-group-item-title">Push</span>
      <span class="list-group-item-description">Mentions and direct messages</span>
    </span>
    <span class="list-group-item-actions">
      <span class="form-check form-switch m-0"><input type="checkbox" role="switch" class="form-check-input" /></span>
    </span>
  </label>
</div>
</Example>

### Longer text

The slots are centered and the description stays on one line. For longer text add the `align-items-start` utility to the item and `text-wrap` to the description.

<Example bg="surface-secondary" column>
<div class="list-group">
  <div class="list-group-item align-items-start">
    <div class="list-group-item-media">
      <span class="avatar" style="background-image: url(/static/avatars/000m.jpg)"></span>
    </div>
    <div class="list-group-item-content">
      <div class="list-group-item-title">Paweł Kuna</div>
      <div class="list-group-item-description text-wrap">The new list layout works well on the dashboard. Can we use the same slots for the search results?</div>
    </div>
    <div class="list-group-item-meta">2 h</div>
  </div>
</div>
</Example>

## Sizes

Add `list-group-sm` for compact items or `list-group-lg` for items with more room. The classes change the vertical padding of the items and the gap between the slots.

<Example bg="surface-secondary" column>
<div class="list-group list-group-sm mb-3">
  <div class="list-group-item">Small item</div>
  <div class="list-group-item">Small item</div>
</div>
<div class="list-group mb-3">
  <div class="list-group-item">Default item</div>
  <div class="list-group-item">Default item</div>
</div>
<div class="list-group list-group-lg">
  <div class="list-group-item">Large item</div>
  <div class="list-group-item">Large item</div>
</div>
</Example>

## Variants

### Flush

Add `list-group-flush` to remove the outer border and the rounded corners. Use it when the list sits inside another element, for example a card.

<Example bg="surface-secondary" column>
<div class="card">
  <div class="list-group list-group-flush">
    <div class="list-group-item">First item</div>
    <div class="list-group-item">Second item</div>
    <div class="list-group-item">Third item</div>
  </div>
</div>
</Example>

### Links and buttons

Add `list-group-item-action` to items that the user can click. It adds a hover and focus state. Use it on `a` or `button` elements only.

<Example bg="surface-secondary" column>
<div class="list-group">
  <a href="#" class="list-group-item list-group-item-action">Profile</a>
  <a href="#" class="list-group-item list-group-item-action">Billing</a>
  <a href="#" class="list-group-item list-group-item-action">Notifications</a>
</div>
</Example>

### Active and disabled

Mark the current item with `active`. Tabler shows it with a thicker border on the start side. Use `disabled` for an item the user cannot pick.

<Example bg="surface-secondary" column>
<div class="list-group">
  <a href="#" class="list-group-item list-group-item-action active" aria-current="true"> Active item </a>
  <a href="#" class="list-group-item list-group-item-action">Normal item</a>
  <a class="list-group-item list-group-item-action disabled" aria-disabled="true" tabindex="-1"> Disabled item </a>
</div>
</Example>

### Selectable items

Add `list-group-selectable` to the container and `list-group-selectable-check` to the checkbox or radio in each item. A checked input gives its item the same look as `active`, with no JavaScript. Use a `label` as the item, so a click on the whole row changes the input.

<Example bg="surface-secondary" column>
<div class="list-group list-group-selectable">
  <label class="list-group-item">
    <span class="list-group-item-media"><input type="checkbox" class="form-check-input list-group-selectable-check m-0" checked /></span>
    <span class="list-group-item-content">
      <span class="list-group-item-title">Paweł Kuna</span>
      <span class="list-group-item-description">UI Designer</span>
    </span>
  </label>
  <label class="list-group-item">
    <span class="list-group-item-media"><input type="checkbox" class="form-check-input list-group-selectable-check m-0" /></span>
    <span class="list-group-item-content">
      <span class="list-group-item-title">Alice Marlin</span>
      <span class="list-group-item-description">Frontend developer</span>
    </span>
  </label>
</div>
</Example>

### Nested items

Put the child items in a `list-group-nested` element right after their parent item. The nested items are indented and have no borders between them. Make the element a `collapse` and the parent item its toggle to open and close the group. Add `list-group-item-toggle` to the chevron, and it turns over while the group is open.

<Example bg="surface-secondary" column>
<div class="list-group">
  <button type="button" class="list-group-item list-group-item-action" data-bs-toggle="collapse" data-bs-target="#list-nested-projects" aria-expanded="true" aria-controls="list-nested-projects">
    <span class="list-group-item-media"><Icon name="folder" color="muted" /></span>
    <span class="list-group-item-content">
      <span class="list-group-item-title">Projects</span>
    </span>
    <span class="list-group-item-meta"><Icon name="chevron-down" class="list-group-item-toggle" /></span>
  </button>
  <div class="list-group-nested collapse show" id="list-nested-projects">
    <a href="#" class="list-group-item list-group-item-action">Website redesign</a>
    <a href="#" class="list-group-item list-group-item-action">Mobile app</a>
  </div>
  <a href="#" class="list-group-item list-group-item-action">
    <span class="list-group-item-media"><Icon name="settings" color="muted" /></span>
    <span class="list-group-item-content">
      <span class="list-group-item-title">Settings</span>
    </span>
  </a>
</div>
</Example>

The indent is the `--tblr-list-group-nested-indent` variable. Its default matches an icon in the media slot.

### Section header

Use `list-group-header` to split a long list into groups. The header is a small uppercase label with its own background.

<Example bg="surface-secondary" column>
<div class="list-group list-group-flush">
  <div class="list-group-header">Today</div>
  <div class="list-group-item">Report generated</div>
  <div class="list-group-item">New comment</div>
  <div class="list-group-header">Yesterday</div>
  <div class="list-group-item">Invoice paid</div>
</div>
</Example>

### Hoverable items with actions

Add `list-group-hoverable` to the container to highlight the row under the pointer. Inside an item, put extra controls in a `list-group-item-actions` element. They stay hidden and appear on hover. Add the `show` class to keep an action always visible.

<Example bg="surface-secondary" column>
<div class="list-group list-group-hoverable">
  <div class="list-group-item">
    <div class="list-group-item-content">
      <div class="list-group-item-title">Change deprecated html tags</div>
    </div>
    <a href="#" class="list-group-item-actions" aria-label="Add to favorites"><Icon name="star" color="muted" /></a>
  </div>
  <div class="list-group-item">
    <div class="list-group-item-content">
      <div class="list-group-item-title">Fix spacing in the navbar</div>
    </div>
    <a href="#" class="list-group-item-actions show" aria-label="Remove from favorites"><Icon name="star" color="yellow" /></a>
  </div>
</div>
</Example>

### Transparent

Add `list-group-transparent` to drop the background and the borders. Icons inside the items turn gray. This variant works well as a side menu.

<Example bg="surface-secondary" column>
<div class="list-group list-group-transparent">
  <a href="#" class="list-group-item list-group-item-action d-flex align-items-center"> <Icon name="user" class="me-2" /> Account </a>
  <a href="#" class="list-group-item list-group-item-action d-flex align-items-center active"> <Icon name="settings" class="me-2" /> Settings </a>
  <a href="#" class="list-group-item list-group-item-action d-flex align-items-center"> <Icon name="bell" class="me-2" /> Notifications </a>
</div>
</Example>

### Numbered

Use an `ol` element with `list-group-numbered` to number the items. The numbers come from CSS, so you do not write them in the markup.

<Example bg="surface-secondary" column>
<ol class="list-group list-group-numbered">
  <li class="list-group-item">Create an account</li>
  <li class="list-group-item">Confirm your email</li>
  <li class="list-group-item">Invite your team</li>
</ol>
</Example>

### Horizontal

Add `list-group-horizontal` to place the items in a row. Use a breakpoint, for example `list-group-horizontal-md`, to switch from a column to a row on wider screens.

<Example bg="surface-secondary" column>
<div class="list-group list-group-horizontal">
  <div class="list-group-item">First</div>
  <div class="list-group-item">Second</div>
  <div class="list-group-item">Third</div>
</div>
</Example>

### Contextual colors

Use `list-group-item-*` with a theme color to give one item a background. See the [full list of available colors](/ui/base/colors) for more details.

<Example bg="surface-secondary" column>
<div class="list-group">
  <div class="list-group-item list-group-item-primary">Primary item</div>
  <div class="list-group-item list-group-item-success">Success item</div>
  <div class="list-group-item list-group-item-warning">Warning item</div>
  <div class="list-group-item list-group-item-danger">Danger item</div>
</div>
</Example>

## Examples

### List group in a card

Add `card-list-group` to the list inside a card. The items then use the card padding, and the borders on the sides are removed. A border is added between the card body and the list.

<Example bg="surface-secondary" column>
<div class="card">
  <div class="card-header"><h3 class="card-title">Team</h3></div>
  <div class="list-group card-list-group">
    <div class="list-group-item">
      <div class="row align-items-center">
        <div class="col-auto">
          <span class="avatar" style="background-image: url(/static/avatars/000m.jpg)"></span>
        </div>
        <div class="col text-truncate">
          <div>Paweł Kuna</div>
          <div class="text-secondary text-truncate">UI Designer</div>
        </div>
      </div>
    </div>
    <div class="list-group-item">
      <div class="row align-items-center">
        <div class="col-auto">
          <span class="avatar" style="background-image: url(/static/avatars/016f.jpg)"></span>
        </div>
        <div class="col text-truncate">
          <div>Alice Marlin</div>
          <div class="text-secondary text-truncate">Frontend developer</div>
        </div>
      </div>
    </div>
  </div>
</div>
</Example>

### Notifications list

This pattern joins several variants: a flush list inside a card, hoverable rows, and an action that shows on hover.

<Example bg="surface-secondary" column>
<div class="card">
  <div class="card-header"><h3 class="card-title">Notifications</h3></div>
  <div class="list-group list-group-flush list-group-hoverable">
    <div class="list-group-item">
      <div class="list-group-item-media">
        <span class="status-dot status-dot-animated bg-red"></span>
      </div>
      <div class="list-group-item-content">
        <a href="#" class="list-group-item-title">Build failed</a>
        <div class="list-group-item-description">The last deploy did not finish</div>
      </div>
      <a href="#" class="list-group-item-actions" aria-label="Add to favorites"><Icon name="star" color="muted" /></a>
    </div>
    <div class="list-group-item">
      <div class="list-group-item-media"><span class="status-dot"></span></div>
      <div class="list-group-item-content">
        <a href="#" class="list-group-item-title">New comment</a>
        <div class="list-group-item-description">Alice replied in the design thread</div>
      </div>
      <a href="#" class="list-group-item-actions show" aria-label="Remove from favorites"><Icon name="star" color="yellow" /></a>
    </div>
  </div>
</div>
</Example>

## Inline list

`list-inline` is a separate, simpler pattern for a row of items - for example a footer or a page header with a few links. It is not a `list-group`: items have no border or background, only spacing between them.

Use `list-inline` on a `ul` and `list-inline-item` on each `li`.

<Example bg="surface-secondary" column>
<ul class="list-inline mb-0">
  <li class="list-inline-item">Documentation</li>
  <li class="list-inline-item">License</li>
  <li class="list-inline-item">Source code</li>
</ul>
</Example>

Add `list-inline-dots` to separate items with a centered dot instead of relying on spacing alone. Tabler uses this pattern in its own footer.

<Example bg="surface-secondary" column>
<ul class="list-inline list-inline-dots mb-0">
  <li class="list-inline-item">Documentation</li>
  <li class="list-inline-item">License</li>
  <li class="list-inline-item">Source code</li>
</ul>
</Example>

## Separated list

`list-separated` stacks its children with a gap between them instead of a border. Use it when each item is a block of its own - a card, a media object, a row of details - rather than a row in a bordered list.

<Example>
<ul class="list-separated">
  <li class="d-flex align-items-center">
    <span class="avatar me-3" style="background-image: url(/static/avatars/029m.jpg)"></span>
    <div>
      <div class="fw-medium">Egan Poetz</div>
      <div class="text-secondary">Product Manager</div>
    </div>
  </li>
  <li class="d-flex align-items-center">
    <span class="avatar me-3" style="background-image: url(/static/avatars/035f.jpg)"></span>
    <div>
      <div class="fw-medium">Paweł Kuna</div>
      <div class="text-secondary">UI Designer</div>
    </div>
  </li>
</ul>
</Example>

## Accessibility

- Pick the right element. Use `ul` or `ol` with `li` for a list of items, `nav` with `a` for navigation, and `button` for actions on the page.
- Mark the current item with `aria-current="true"` next to the `active` class. The color alone is not enough.
- A `disabled` class does not block clicks on a link. Remove the `href`, add `aria-disabled="true"`, and set `tabindex="-1"`.
- Actions in `list-group-item-actions` appear on hover only. They stay in the tab order, but they are invisible while focused, so do not put the only way to do something there. Add the `show` class when an action must always be visible.