List group
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.
Basic example
The most basic list group combines ListGroup with ListGroupItem children. Build upon it with the props that follow, or with your own CSS as needed.
- An item
- A second item
- A third item
- A fourth item
- And a fifth one
<ListGroup>
<ListGroupItem>
An item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
<ListGroupItem>
A fourth item
</ListGroupItem>
<ListGroupItem>
And a fifth one
</ListGroupItem>
</ListGroup>Active items
Set active on ListGroupItem to indicate the current selection.
- An active item
- A second item
- A third item
- A fourth item
- And a fifth one
<ListGroup>
<ListGroupItem
active
aria-current="true"
>
An active item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
<ListGroupItem>
A fourth item
</ListGroupItem>
<ListGroupItem>
And a fifth one
</ListGroupItem>
</ListGroup>Links and buttons
Set action on ListGroupItem to create an interactive item with hover, disabled, and active states. Non-interactive items do not display a click or tap affordance.
Set disabled on ListGroupItem to disable interaction and communicate the disabled state to assistive technologies.
Do not use Button styles for list group items.
<ListGroup as="div">
<ListGroupItem
action
active
aria-current="true"
href="#"
>
{' '}The current link item{' '}
</ListGroupItem>
<ListGroupItem
action
href="#"
>
A second link item
</ListGroupItem>
<ListGroupItem
action
href="#"
>
A third link item
</ListGroupItem>
<ListGroupItem
action
href="#"
>
A fourth link item
</ListGroupItem>
<ListGroupItem
action
aria-disabled="true"
disabled
href="#"
>
A disabled link item
</ListGroupItem>
</ListGroup>For button items, ListGroupItem passes disabled to the native button. Link items do not support the native disabled attribute, so the wrapper disables navigation and keyboard focus.
<ListGroup as="div">
<ListGroupItem
action
active
aria-current="true"
type="button"
>
{' '}The current button{' '}
</ListGroupItem>
<ListGroupItem
action
type="button"
>
A second button item
</ListGroupItem>
<ListGroupItem
action
type="button"
>
A third button item
</ListGroupItem>
<ListGroupItem
action
type="button"
>
A fourth button item
</ListGroupItem>
<ListGroupItem
action
disabled
type="button"
>
A disabled button item
</ListGroupItem>
</ListGroup>Flush
Set flush on ListGroup to remove some borders and rounded corners so its items sit 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
<ListGroup flush>
<ListGroupItem>
An item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
<ListGroupItem>
A fourth item
</ListGroupItem>
<ListGroupItem>
And a fifth one
</ListGroupItem>
</ListGroup>Numbered
Set numbered on ListGroup to number its items; use as="ol" when an ordered-list element is also appropriate. Numbers are generated with CSS for better placement and customization.
The numbered prop uses CSS counters to generate and place the item numbers.
- A list item
- A list item
- A list item
<ListGroup
as="ol"
numbered
>
<ListGroupItem>
A list item
</ListGroupItem>
<ListGroupItem>
A list item
</ListGroupItem>
<ListGroupItem>
A list item
</ListGroupItem>
</ListGroup>These work great with custom content as well.
- 14SubheadingContent for list item
- 14SubheadingContent for list item
- 14SubheadingContent for list item
<ListGroup
as="ol"
numbered
>
<ListGroupItem className="d-flex justify-content-between align-items-start">
<div className="ms-2 me-auto">
<div className="fw-bold">
Subheading
</div>
{' '}Content for list item{' '}
</div>
<Badge theme="primary">
14
</Badge>
</ListGroupItem>
<ListGroupItem className="d-flex justify-content-between align-items-start">
<div className="ms-2 me-auto">
<div className="fw-bold">
Subheading
</div>
{' '}Content for list item{' '}
</div>
<Badge theme="primary">
14
</Badge>
</ListGroupItem>
<ListGroupItem className="d-flex justify-content-between align-items-start">
<div className="ms-2 me-auto">
<div className="fw-bold">
Subheading
</div>
{' '}Content for list item{' '}
</div>
<Badge theme="primary">
14
</Badge>
</ListGroupItem>
</ListGroup>Horizontal
Set horizontal on ListGroup to display items in a row at all sizes, or set it to a breakpoint such as sm or md to switch to a row at that breakpoint.
The responsive variants use container queries, so place the list group in a query container with the contains-inline utility applied through the parent's className. Currently horizontal list groups cannot be combined with flush list groups.
ProTip: For equal-width horizontal items, apply the flex-fill utility through each ListGroupItem's className.
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
<Stack gap={3}>
<div className="contains-inline">
<ListGroup horizontal>
<ListGroupItem>
An item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
</ListGroup>
</div>
<div className="contains-inline">
<ListGroup horizontal="sm">
<ListGroupItem>
An item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
</ListGroup>
</div>
<div className="contains-inline">
<ListGroup horizontal="md">
<ListGroupItem>
An item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
</ListGroup>
</div>
<div className="contains-inline">
<ListGroup horizontal="lg">
<ListGroupItem>
An item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
</ListGroup>
</div>
<div className="contains-inline">
<ListGroup horizontal="xl">
<ListGroupItem>
An item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
</ListGroup>
</div>
<div className="contains-inline">
<ListGroup horizontal="2xl">
<ListGroupItem>
An item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
</ListGroup>
</div>
</Stack>Drag the handle to resize the container below and watch the list group switch between vertical and horizontal layouts as the container—not the viewport—crosses the md breakpoint.
- An item
- A second item
- A third item
<div className="contains-inline">
<ListGroup horizontal="md">
<ListGroupItem>
An item
</ListGroupItem>
<ListGroupItem>
A second item
</ListGroupItem>
<ListGroupItem>
A third item
</ListGroupItem>
</ListGroup>
</div>Variants
Set the theme prop on ListGroupItem to give an item a contextual 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 dark list group item
- A simple light list group item
- A simple inverse list group item
<ListGroup>
<ListGroupItem>
A simple default list group item
</ListGroupItem>
<ListGroupItem theme="primary">
A simple primary list group item
</ListGroupItem>
<ListGroupItem theme="accent">
A simple accent list group item
</ListGroupItem>
<ListGroupItem theme="secondary">
A simple secondary list group item
</ListGroupItem>
<ListGroupItem theme="success">
A simple success list group item
</ListGroupItem>
<ListGroupItem theme="danger">
A simple danger list group item
</ListGroupItem>
<ListGroupItem theme="warning">
A simple warning list group item
</ListGroupItem>
<ListGroupItem theme="info">
A simple info list group item
</ListGroupItem>
<ListGroupItem theme="dark">
A simple dark list group item
</ListGroupItem>
<ListGroupItem theme="light">
A simple light list group item
</ListGroupItem>
<ListGroupItem theme="inverse">
A simple inverse list group item
</ListGroupItem>
</ListGroup>For links and buttons
Theme colors also work with interactive ListGroupItem components. Notice the hover styles not present in the previous example. Set active to indicate the selected item.
<ListGroup as="div">
<ListGroupItem
action
href="#"
>
A simple default list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="primary"
>
A simple primary list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="accent"
>
A simple accent list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="secondary"
>
A simple secondary list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="success"
>
A simple success list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="danger"
>
A simple danger list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="warning"
>
A simple warning list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="info"
>
A simple info list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="dark"
>
A simple dark list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="light"
>
A simple light list group item
</ListGroupItem>
<ListGroupItem
action
href="#"
theme="inverse"
>
A simple inverse list group item
</ListGroupItem>
</ListGroup>Using color to add meaning only provides a visual indication. Include text or a visually hidden label so assistive technologies can convey the same information.
With badges
Add badges to any list group item to show unread counts, activity, and more with the help of some utilities.
- A list item 14
- A second list item 2
- A third list item 1
<ListGroup>
<ListGroupItem className="d-flex justify-content-between align-items-center">
{' '}A list item{' '}
<Badge theme="primary">
14
</Badge>
</ListGroupItem>
<ListGroupItem className="d-flex justify-content-between align-items-center">
{' '}A second list item{' '}
<Badge theme="primary">
2
</Badge>
</ListGroupItem>
<ListGroupItem className="d-flex justify-content-between align-items-center">
{' '}A third list item{' '}
<Badge theme="primary">
1
</Badge>
</ListGroupItem>
</ListGroup>Custom content
Add nearly any HTML within, even for linked list groups like the one below, with the help of flexbox utilities.
List group item heading
3 days agoSome placeholder content in a paragraph.
And some small print.List group item heading
3 days agoSome placeholder content in a paragraph.
And some muted small print.List group item heading
3 days agoSome placeholder content in a paragraph.
And some muted small print.<ListGroup as="div">
<ListGroupItem
action
active
aria-current="true"
href="#"
>
<div className="d-flex w-100 justify-content-between">
<h5 className="mb-1">
List group item heading
</h5>
<small>
3 days ago
</small>
</div>
<p className="mb-1">
Some placeholder content in a paragraph.
</p>
<small>
And some small print.
</small>
</ListGroupItem>
<ListGroupItem
action
href="#"
>
<div className="d-flex w-100 justify-content-between">
<h5 className="mb-1">
List group item heading
</h5>
<small className="fg-2">
3 days ago
</small>
</div>
<p className="mb-1">
Some placeholder content in a paragraph.
</p>
<small className="fg-2">
And some muted small print.
</small>
</ListGroupItem>
<ListGroupItem
action
href="#"
>
<div className="d-flex w-100 justify-content-between">
<h5 className="mb-1">
List group item heading
</h5>
<small className="fg-2">
3 days ago
</small>
</div>
<p className="mb-1">
Some placeholder content in a paragraph.
</p>
<small className="fg-2">
And some muted small print.
</small>
</ListGroupItem>
</ListGroup>Checkboxes and radios
Place Checkbox and Radio components inside list group items and customize them as needed. If there is no visible label, provide an aria-label.
<ListGroup>
<ListGroupItem>
<FormField>
<Checkbox
id="firstCheckbox"
value=""
/>
<label htmlFor="firstCheckbox">
First checkbox
</label>
</FormField>
</ListGroupItem>
<ListGroupItem>
<FormField>
<Checkbox
id="secondCheckbox"
value=""
/>
<label htmlFor="secondCheckbox">
Second checkbox
</label>
</FormField>
</ListGroupItem>
<ListGroupItem>
<FormField>
<Checkbox
id="thirdCheckbox"
value=""
/>
<label htmlFor="thirdCheckbox">
Third checkbox
</label>
</FormField>
</ListGroupItem>
</ListGroup><ListGroup>
<ListGroupItem>
<FormField>
<Radio
defaultChecked
id="firstRadio"
name="listGroupRadio"
value=""
/>
<label htmlFor="firstRadio">
First radio
</label>
</FormField>
</ListGroupItem>
<ListGroupItem>
<FormField>
<Radio
id="secondRadio"
name="listGroupRadio"
value=""
/>
<label htmlFor="secondRadio">
Second radio
</label>
</FormField>
</ListGroupItem>
<ListGroupItem>
<FormField>
<Radio
id="thirdRadio"
name="listGroupRadio"
value=""
/>
<label htmlFor="thirdRadio">
Third radio
</label>
</FormField>
</ListGroupItem>
</ListGroup>Apply the stretched-link utility through the item's className when the entire item should be clickable.
<ListGroup>
<ListGroupItem>
<FormField>
<Checkbox
id="firstCheckboxStretched"
value=""
/>
<label
className="stretched-link"
htmlFor="firstCheckboxStretched"
>
First checkbox
</label>
</FormField>
</ListGroupItem>
<ListGroupItem>
<FormField>
<Checkbox
id="secondCheckboxStretched"
value=""
/>
<label
className="stretched-link"
htmlFor="secondCheckboxStretched"
>
Second checkbox
</label>
</FormField>
</ListGroupItem>
<ListGroupItem>
<FormField>
<Checkbox
id="thirdCheckboxStretched"
value=""
/>
<label
className="stretched-link"
htmlFor="thirdCheckboxStretched"
>
Third checkbox
</label>
</FormField>
</ListGroupItem>
</ListGroup>Use the checkable and radio props for the corresponding list group variants. Add listGroup to FormCheck to apply the input styling used by checkable groups.
<Stack gap={3}>
<ListGroup
as="div"
checkable
>
<FormCheck
id="checkableListOne"
listGroup
name="checkableList"
type="radio"
/>
<ListGroupItem
as="label"
htmlFor="checkableListOne"
>
First option
</ListGroupItem>
</ListGroup>
<ListGroup
as="div"
radio
>
<FormCheck
id="radioListOne"
name="radioList"
type="radio"
/>
<ListGroupItem
as="label"
htmlFor="radioListOne"
>
First option
</ListGroupItem>
</ListGroup>
</Stack>CSS
Variables
Use CSS custom properties on the component to customize its appearance without recompiling Bootstrap.
.list-group {
--bs-list-group-color: var(--bs-fg-body);
--bs-list-group-bg: var(--bs-bg-body);
--bs-list-group-border-color: var(--bs-border-color);
--bs-list-group-border-width: var(--bs-border-width);
--bs-list-group-border-radius: var(--bs-radius-5);
--bs-list-group-item-padding-x: var(--bs-spacer);
--bs-list-group-item-padding-y: var(--bs-spacer-2);
--bs-list-group-action-color: var(--bs-fg-2);
--bs-list-group-action-hover-color: var(--bs-fg-1);
--bs-list-group-action-hover-bg: var(--bs-bg-1);
--bs-list-group-action-active-color: var(--bs-fg-body);
--bs-list-group-action-active-bg: var(--bs-bg-2);
--bs-list-group-disabled-color: var(--bs-fg-3);
--bs-list-group-disabled-bg: var(--bs-bg-body);
--bs-list-group-active-color: var(--bs-primary-contrast);
--bs-list-group-active-bg: var(--bs-primary-bg);
--bs-list-group-active-border-color: var(--bs-primary-bg);
}
JavaScript behavior
Use the Tab plugin to create tabbable list group panes.