v4 Beta now available! Try it out! Feedback welcome!
Looking for v3 docs?

Lists

Lists allow for multiple ways to visually organize a series of content or navigation.

Page Contents

Overview #

Lists are a flexible component for displaying a series of content with various styling options. List items can be modified and extended to support just about any content within. They can also be used as navigation with the right modifier class.

Basic List #

In the basic form, a .list removes the default list-style and left margin on list items, but nested lists will be indented.

The use of the .list-item class is required for each <li> or simulated list item, for proper styling.

  • List item 1
  • List item 2
  • List item 3
<ul class="list">
<li class="list-item">List item 1</li>
<li class="list-item">List item 2</li>
<li class="list-item">List item 3</li>
</ul>

You can also use <div> containers to create a list.

List item 1
List item 2
List item 3
<div class="list">
<div class="list-item">List item 1</div>
<div class="list-item">List item 2</div>
<div class="list-item">List item 3</div>
</div>

Styled Lists #

Add some visual style to lists with a handful of modifier classes.

Bulleted List #

Add the .list-bulleted modifier to add a stylized bullet to each list item.

  • Bulleted list item 1
  • Bulleted list item 2
  • Bulleted list item 3
<ul class="list list-bulleted">
<li class="list-item">Bulleted list item 1</li>
<li class="list-item">Bulleted list item 2</li>
<li class="list-item">Bulleted list item 3</li>
</ul>
Bulleted list item 1
Bulleted list item 2
Bulleted list item 3
<div class="list list-bulleted">
<div class="list-item">Bulleted list item 1</div>
<div class="list-item">Bulleted list item 2</div>
<div class="list-item">Bulleted list item 3</div>
</div>

Ordered List #

Add the .list-ordered modifier to create a numerically ordered list.

  1. Ordered list item 1
  2. Ordered list item 2
  3. Ordered list item 3
<ol class="list list-ordered">
<li class="list-item">Ordered list item 1</li>
<li class="list-item">Ordered list item 2</li>
<li class="list-item">Ordered list item 3</li>
</ol>
Ordered list item 1
Ordered list item 2
Ordered list item 3
<div class="list list-ordered">
<div class="list-item">Ordered list item 1</div>
<div class="list-item">Ordered list item 2</div>
<div class="list-item">Ordered list item 3</div>
</div>

Nested Lists #

When nesting lists, you will need to add the .list class and any modifiers to each nested list to restyle as needed.

  • List item 1
  • List item 2
    • List item 1
    • List item 2
    • List item 3
  • List item 3
<ul class="list">
<li class="list-item">List item 1</li>
<li class="list-item">List item 2
<ul class="list">
<li class="list-item">List item 1</li>
<li class="list-item">List item 2</li>
<li class="list-item">List item 3</li>
</ul>
</li>
<li class="list-item">List item 3</li>
</ul>
  • Bulleted list item 1
  • Bulleted list item 2
    • Bulleted list item 1
    • Bulleted list item 2
    • Bulleted list item 3
  • List item 3
<ul class="list list-bulleted">
<li class="list-item">Bulleted list item 1</li>
<li class="list-item">Bulleted list item 2
<ul class="list list-bulleted">
<li class="list-item">Bulleted list item 1</li>
<li class="list-item">Bulleted list item 2</li>
<li class="list-item">Bulleted list item 3</li>
</ul>
</li>
<li class="list-item">List item 3</li>
</ul>
  1. Ordered list item 1
  2. Ordered list item 2
    1. Ordered list item 1
    2. Ordered list item 2
    3. Ordered list item 3
  3. List item 3
<ol class="list list-ordered">
<li class="list-item">Ordered list item 1</li>
<li class="list-item">Ordered list item 2
<ol class="list list-ordered">
<li class="list-item">Ordered list item 1</li>
<li class="list-item">Ordered list item 2</li>
<li class="list-item">Ordered list item 3</li>
</ol>
</li>
<li class="list-item">List item 3</li>
</ol>
  • List item 1
  • List item 2
    • Bulleted list item 1
    • Bulleted list item 2
    • Bulleted list item 3
  • List item 3
<ul class="list">
<li class="list-item">List item 1</li>
<li class="list-item">List item 2
<ul class="list list-bulleted">
<li class="list-item">Bulleted list item 1</li>
<li class="list-item">Bulleted list item 2</li>
<li class="list-item">Bulleted list item 3</li>
</ul>
</li>
<li class="list-item">List item 3</li>
</ul>
  • List item 1
  • List item 2
    1. Ordered list item 1
    2. Ordered list item 2
    3. Ordered list item 3
  • List item 3
<ul class="list">
<li class="list-item">List item 1</li>
<li class="list-item">List item 2
<ol class="list list-ordered">
<li class="list-item">Ordered list item 1</li>
<li class="list-item">Ordered list item 2</li>
<li class="list-item">Ordered list item 3</li>
</ol>
</li>
<li class="list-item">List item 3</li>
</ul>
  • Bulleted list item 1
  • Bulleted list item 2
    • Ordered list item 1
    • Ordered list item 2
    • Ordered list item 3
  • Bulleted list item 3
<ul class="list list-bulleted">
<li class="list-item">Bulleted list item 1</li>
<li class="list-item">Bulleted list item 2
<ul class="list list-ordered">
<li class="list-item">Ordered list item 1</li>
<li class="list-item">Ordered list item 2</li>
<li class="list-item">Ordered list item 3</li>
</ul>
</li>
<li class="list-item">Bulleted list item 3</li>
</ul>
  • Ordered list item 1
  • Ordered list item 2
    • Bulleted list item 1
    • Bulleted list item 2
    • Bulleted list item 3
  • Ordered list item 3
<ul class="list list-ordered">
<li class="list-item">Ordered list item 1</li>
<li class="list-item">Ordered list item 2
<ul class="list list-bulleted">
<li class="list-item">Bulleted list item 1</li>
<li class="list-item">Bulleted list item 2</li>
<li class="list-item">Bulleted list item 3</li>
</ul>
</li>
<li class="list-item">Ordered list item 3</li>
</ul>

Divided List #

Place a rule between list items with the .list-divided modifier.

  • Divided list item 1
  • Divided list item 2
  • Divided list item 3
<ul class="list list-divided">
<li class="list-item">Divided list item 1</li>
<li class="list-item">Divided list item 2</li>
<li class="list-item">Divided list item 3</li>
</ul>

Divided lists also work with <div> containers.

Divided list item 1
Divided list item 2
Divided list item 3
<div class="list list-divided">
<div class="list-item">Divided list item 1</div>
<div class="list-item">Divided list item 2</div>
<div class="list-item">Divided list item 3</div>
</div>

Ruled List #

Place a rule at the top and bottom of a list, and between list items with the .list-ruled modifier.

  • Ruled list item 1
  • Ruled list item 2
  • Ruled list item 3
<ul class="list list-ruled">
<li class="list-item">Ruled list item 1</li>
<li class="list-item">Ruled list item 2</li>
<li class="list-item">Ruled list item 3</li>
</ul>

Similar to divided lists, ruled lists also work with <div> containers.

Ruled list item 1
Ruled list item 2
Ruled list item 3
<div class="list list-ruled">
<div class="list-item">Ruled list item 1</div>
<div class="list-item">Ruled list item 2</div>
<div class="list-item">Ruled list item 3</div>
</div>

List Group #

Visually group list content by adding a border all around with the .list-group modifier.

  • List item
  • List item
  • List item
<ul class="list list-group">
<li class="list-item">List item</li>
<li class="list-item">List item</li>
<li class="list-item">List item</li>
</ul>

Similar to the above examples, this will also work with <div> containers.

List item
List item
List item
<div class="list list-group">
<div class="list-item">List item</div>
<div class="list-item">List item</div>
<div class="list-item">List item</div>
</div>

Spaced #

Easily add some spacing to lists. Adding .list-spaced will provide padding on all sides of each list item.

List item 1
List item 2
List item 3
<div class="list list-spaced list-ruled">
<div class="list-item">List item 1</div>
<div class="list-item">List item 2</div>
<div class="list-item">List item 3</div>
</div>

Add only vertical padding with .list-spaced-y.

List item 1
List item 2
List item 3
<div class="list list-spaced-y list-ruled">
<div class="list-item">List item 1</div>
<div class="list-item">List item 2</div>
<div class="list-item">List item 3</div>
</div>

Need only horizontal padding, then use .list-spaced-x.

List item 1
List item 2
List item 3
<div class="list list-spaced-x list-ruled">
<div class="list-item">List item 1</div>
<div class="list-item">List item 2</div>
<div class="list-item">List item 3</div>
</div>

Horizontal Lists #

Place the items in the list in a horizontal layout with .list-horizontal.

  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
  • List item
<ul class="list list-horizontal">
<li class="list-item">List item</li>
<li class="list-item">List item</li>
<li class="list-item">List item</li>
</ul>

<ul class="list list-horizontal list-bulleted">
<li class="list-item">List item</li>
<li class="list-item">List item</li>
<li class="list-item">List item</li>
</ul>

<ul class="list list-horizontal list-ordered">
<li class="list-item">List item</li>
<li class="list-item">List item</li>
<li class="list-item">List item</li>
</ul>

<ul class="list list-horizontal list-divided">
<li class="list-item">List item</li>
<li class="list-item">List item</li>
<li class="list-item">List item</li>
</ul>

<ul class="list list-horizontal list-ruled">
<li class="list-item">List item</li>
<li class="list-item">List item</li>
<li class="list-item">List item</li>
</ul>

<ul class="list list-horizontal list-group">
<li class="list-item">List item</li>
<li class="list-item">List item</li>
<li class="list-item">List item</li>
</ul>

Inline List #

Add the .flex-wrap utility class onto a horizontal list to wrap to the next row as needed.

  • Inline list item
  • Inline list item
  • Inline list item
  • Inline list item
  • Inline list item
  • Inline list item
  • Inline list item
  • Inline list item
  • Inline list item
  • Inline list item
<ul class="list list-horizontal flex-wrap">
<li class="list-item">Inline list item</li>
<li class="list-item">Inline list item</li>
<li class="list-item">Inline list item</li>
<li class="list-item">Inline list item</li>
<li class="list-item">Inline list item</li>
<li class="list-item">Inline list item</li>
<li class="list-item">Inline list item</li>
<li class="list-item">Inline list item</li>
<li class="list-item">Inline list item</li>
<li class="list-item">Inline list item</li>
</ul>

List Content #

Active Items #

Add .active to a .list-item to indicate the current active selection.

  • Active list item
  • List item 2
  • List item 3
<ul class="list">
<li class="list-item active">Active list item</li>
<li class="list-item">List item 2</li>
<li class="list-item">List item 3</li>
</ul>
Active list item
List item 2
List item 3
<div class="list">
<div class="list-item active">Active list item</div>
<div class="list-item">List item 2</div>
<div class="list-item">List item 3</div>
</div>

Disabled Items #

Add .disabled to a <li> or .list-item to make it out to appear disabled. Note that some elements with .disabled will also require custom JavaScript to fully disable their click events (e.g., links).

Disabling Anchors

Please refer to the Accessiblity notes about disabled anchors.

  • Disabled list item
  • List item 2
  • List item 3
<ul class="list">
<li class="list-item disabled" aria-disabled="true">Disabled list item</li>
<li class="list-item">List item 2</li>
<li class="list-item">List item 3</li>
</ul>
Disabled list item
List item 2
List item 3
<div class="list">
<div class="list-item disabled" aria-disabled="true">Disabled list item</div>
<div class="list-item">List item 2</div>
<div class="list-item">List item 3</div>
</div>

Use <a>s or <button>s to create actionable list items with hover, disabled, and active states by adding .list-item-action. We separate these pseudo-classes to ensure lists made of non-interactive elements (like <li>s or <div>s) don't provide a click or tap affordance.

Be sure to not use the standard .btn classes here.

<div class="list">
<a href="#" class="list-item list-item-action active">Active list item</a>
<a href="#" class="list-item list-item-action">List item 2</a>
<a href="#" class="list-item list-item-action disabled" tabindex="-1" aria-disabled="true">Disabled list item</a>
</div>

With <button>s, you can also make use of the disabled attribute instead of the .disabled class. Sadly, <a>s don't support the disabled attribute.

<div class="list">
<button type="button" class="list-item list-item-action active">Active list item</button>
<button type="button" class="list-item list-item-action">List item 2</button>
<button type="button" class="list-item list-item-action" disabled>Disabled list item</button>
</div>

Adding Badges #

Add badges to any list item to show unread counts, activity, and more with the help of some flexbox utility classes.

  • Cras justo odio 7
  • Dapibus ac facilisis in 12
  • Morbi leo risus 3
<ul class="list list-spaced list-group" style="max-width: 25rem;">
<li class="list-item d-flex flex-between flex-items-center">
Cras justo odio
<span class="badge badge-info">7</span>
</li>
<li class="list-item d-flex flex-between flex-items-center">
Dapibus ac facilisis in
<span class="badge badge-info">12</span>
</li>
<li class="list-item d-flex flex-between flex-items-center">
Morbi leo risus
<span class="badge badge-info">3</span>
</li>
</ul>

Custom Content #

Add nearly any HTML within, even for linked lists like the one below, using flexbox utilities for layout.

<div class="list list-spaced list-group" style="max-width: 25rem;">
<a href="#" class="list-item list-item-action flex-column flex-start active">
<div class="d-flex w-100 flex-between flex-items-center mb-0_5">
<h5 class="mb-0">List item heading</h5>
<small>3 days ago</small>
</div>
<p class="mb-0_25">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p>
<small>Donec id elit non mi porta.</small>
</a>
<a href="#" class="list-item list-item-action flex-column flex-start">
<div class="d-flex w-100 flex-between flex-items-center mb-0_5">
<h5 class="mb-0">List item heading</h5>
<small class="text-muted">3 days ago</small>
</div>
<p class="mb-0_25">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p>
<small class="text-muted">Donec id elit non mi porta.</small>
</a>
<a href="#" class="list-item list-item-action flex-column flex-start">
<div class="d-flex w-100 flex-between flex-items-center mb-0_5">
<h5 class="mb-0">List item heading</h5>
<small class="text-muted">3 days ago</small>
</div>
<p class="mb-0_25">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p>
<small class="text-muted">Donec id elit non mi porta.</small>
</a>
</div>

Checkbox and Radio Inputs #

Use <label>s as the .list-item and place checkboxes and radios within them to create large hit areas, then customize as needed.

<div class="list list-spaced list-group">
<label class="list-item">
<input class="form-check-input" type="checkbox" value="">
Cras justo odio
</label>
<label class="list-item ps-2">
<input class="form-check-input ms-n1" type="checkbox" value="">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed suscipit volutpat quam id dictum in fermentum libero vel orci hendrerit fermentum
</label>
<label class="list-item">
<input class="form-check-input" type="checkbox" value="">
Morbi leo risus
</label>
<label class="list-item">
<input class="form-check-input" type="checkbox" value="">
Porta ac consectetur ac
</label>
<label class="list-item">
<input class="form-check-input float-left mr-2" type="checkbox" value="">
Vestibulum at eros
</label>
</div>

You can also use them without <label>s, but you should include an aria-label attribute and value for accessibility.

  • Cras justo odio
  • Dapibus ac facilisis in
  • Morbi leo risus
  • Porta ac consectetur ac
  • Vestibulum at eros
<ul class="list list-spaced list-group">
<li class="list-item">
<input class="form-check-input" type="checkbox" value="" aria-label="...">
Cras justo odio
</li>
<li class="list-item">
<input class="form-check-input" type="checkbox" value="" aria-label="...">
Dapibus ac facilisis in
</li>
<li class="list-item">
<input class="form-check-input" type="checkbox" value="" aria-label="...">
Morbi leo risus
</li>
<li class="list-item">
<input class="form-check-input" type="checkbox" value="" aria-label="...">
Porta ac consectetur ac
</li>
<li class="list-item">
<input class="form-check-input" type="checkbox" value="" aria-label="...">
Vestibulum at eros
</li>
</ul>

Color Variants #

Use color utility classes to style lists with color.

Conveying Meaning to Assistive Technologies

Please refer to the Accessiblity notes about conveying meaning with color.

Rule Color #

Divided and Ruled list items are defined with border-{side}-color: inherit;, allowing for easy recoloring of the borders by setting the border-color on the .list itself. Setting a border-color on a .list-item will only update the border color for that specific list item.

  • List item
  • List item
  • List item
<ul class="list list-spaced list-ruled border-primary">
<li class="list-item">List item</li>
<li class="list-item">List item</li>
<li class="list-item">List item</li>
</ul>

Inverse List #

Set a background color on a list. In some cases you may want to use additional color utility classes to adjust text or border color.

  • List item
  • List item
  • List item
<ul class="list list-spaced list-divided bg-dark text-light border-secondary">
<li class="list-item">List item</li>
<li class="list-item">List item</li>
<li class="list-item">List item</li>
</ul>

Contextual Classes #

Use contextual classes to style list items with a stateful background and color.

  • Default list item
  • Primary list item
  • Secondary list item
  • Success list item
  • Inof list item
  • Warning list item
  • Danger list item
  • Light list item
  • Dark list item
<ul class="list list-spaced list-ruled">
<li class="list-item">Default list item</li>
<li class="list-item list-item-primary">Primary list item</li>
<li class="list-item list-item-secondary">Secondary list item</li>
<li class="list-item list-item-success">Success list item</li>
<li class="list-item list-item-info">Inof list item</li>
<li class="list-item list-item-warning">Warning list item</li>
<li class="list-item list-item-danger">Danger list item</li>
<li class="list-item list-item-light">Light list item</li>
<li class="list-item list-item-dark">Dark list item</li>
</ul>

Contextual classes also work with .list-item-action. Note the addition of the hover styles here not present in the previous example.

<div class="list list-spaced list-ruled">
<a href="#" class="list-item list-item-action">Default list item</a>
<a href="#" class="list-item list-item-action list-item-primary">Primary list item</a>
<a href="#" class="list-item list-item-action list-item-secondary">Secondary list item</a>
<a href="#" class="list-item list-item-action list-item-success">Success list item</a>
<a href="#" class="list-item list-item-action list-item-info">Info list item</a>
<a href="#" class="list-item list-item-action list-item-warning">Warning list item</a>
<a href="#" class="list-item list-item-action list-item-danger">Danger list item</a>
<a href="#" class="list-item list-item-action list-item-list">Light list item</a>
<a href="#" class="list-item list-item-action list-item-dark">Dark list item</a>
</div>

Also supported is the .active state; apply it to indicate an active selection on a contextual list item. This is available with or without the use of .list-item-action.

  • Default list item
  • Primary list item
  • Success list item
  • Info list item
  • Warning list item
  • Danger list item
  • Light list item
  • Dark list item
<ul class="list list-spaced list-ruled">
<li class="list-item active">Default list item</li>
<li class="list-item list-item-primary active">Primary list item</li>
<li class="list-item list-item-success active">Success list item</li>
<li class="list-item list-item-info active">Info list item</li>
<li class="list-item list-item-warning active">Warning list item</li>
<li class="list-item list-item-danger active">Danger list item</li>
<li class="list-item list-item-light active">Light list item</li>
<li class="list-item list-item-dark active">Dark list item</li>
</ul>

SASS Reference #

Variables #

The available Customization options, or Sass variables, that can be customized for list component.

Name Type Default Description
$enable-list boolean true Enable the generation of the list component classes. Smaller segements of the list component classes can be disabled with the following $enable-* variables.
$enable-list-bulleted boolean true Enable the generation of styled bulleted lists.
$enable-list-ordered boolean true Enable the generation of styled ordered lists.
$enable-list-divided boolean true Enable the generation of styled divided lists.
$enable-list-ruled boolean true Enable the generation of styled ruled lists.
$enable-list-group boolean true Enable the generation of list groups.
$enable-list-spaced boolean true Enable the generation of spaced lists.
$enable-list-spaced-y boolean true Enable the generation of vertically spaced lists.
$enable-list-spaced-x boolean true Enable the generation of horizontally spaced lists.
$enable-list-horizontal boolean true Enable the generation of styled horizontal lists.
$enable-list-item-action boolean true Enable the generation of list item actions.
$enable-list-item-colors boolean true Enable the generation of list item color variants.
$list-margin-left string 1.25rem Width of margin to indent lists.
$list-margin-bottom string 1rem Spacing below lists.
$list-item-bg string transparent Background color for list items.
$list-item-disabled-bg string $list-item-bg Background color for disabled list items.
$list-item-disabled-color string $component-disabled-color Text color for disabled list items.
$list-item-active-bg string $component-active-bg Background color for active list items.
$list-item-active-color string $component-active-color Text color for active list items.
$list-item-active-border string $component-active-border-color Border color for active list items.
$list-item-action-color string $component-action-color Text color for list item actions.
$list-item-hover-color string $list-item-hover-color Text color for list item actions when hovered or focused.
$list-item-hover-bg string $component-hover-bg Background color for list item actions when hovered or focused.
$list-border-width string $border-width Border width for list items with borders.
$list-border-color string $component-border-color Border color for list items with borders.
$list-group-border-radius string $border-radius Border radisu for list groups.
$list-bulleted-content string "\25cf\00a0" Visual content to use for bullets. Default content is a black circle and a space.
$list-ordered-delimeter string "\25cf\00a0" Visual content to use as a delimeter after the order value. Default content is a space.
$list-horizontal-padding string .5em Horizontal padding to use between list items in a horizontal list.
$list-spaced-item-padding-y string .75em Vertical padding for list items in a spaced list.
$list-spaced-item-padding-x string 1em Horizontal padding for list items in a spaced list.
$list-themes map () Map of color schemes for lists.
$list-colors list $base-colors Colors to mix and merge into $list-themes
$list-levels map $level-context Levels to mix list colors with.

Mixins #

Here are the mixins related to lists that we use to help generate our CSS. You can also uses these mixins to generate your own custom components or utilities.

list-unstyled() #

List with no left padding or list item markers.

@include list-unstyled();

list-item-variant() #

Create a contextual color variant for a list item.

@include list-item-variant($state, $bg, $color, $border, $hover-bg, $hover-color, $hover-border);
Argument Type Default Description
$state string '' The value appended to generate the class .list-item-#{$state}.
$bg string none Background color for a list item.
$color string none Text color for a list item.
$border string none Border color for a list item.
$hover-bg string none Background color for a list item in active, hover, and focus states.
$hover-color string none Text color for a list item in active, hover, and focus states..
$hover-border string none Border color for a list item in active, hover, and focus states..