Lists

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.

<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.

<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.

<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>

<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.

<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>

<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.

<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>

<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>

<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>

<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>

<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>

<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>

<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.

<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.

<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.

<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.

<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.

<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.

<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.

<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.

<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.

<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. Horizontal lists will also adjust the list marker to be inside the bounds of a 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>

Inner Markers

.list-marker-inner is availabe to adjust the list marker to be within the visual bounds of the list item. This can be helpful when used with the bordered list variants.

<ul class="list list-ruled list-bulleted list-marker-inner">
  <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-divided list-ordered list-marker-inner">
  <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.

<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.

To convey the active state to assistive technologies, use the aria-current attribute — using the page value for the current page, or true for the current item in a set.

<ul class="list">
  <li class="list-item active" aria-current="true">Active list item</li>
  <li class="list-item">List item 2</li>
  <li class="list-item">List item 3</li>
</ul>

<div class="list">
  <div class="list-item active" aria-current="true">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).

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

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

Links and Buttons

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" aria-current="true">Active list item</a>
  <a href="#" class="list-item list-item-action">List item 2</a>
  <a class="list-item list-item-action disabled" 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" aria-current="true">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.

<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 bg-info">7</span>
  </li>
  <li class="list-item d-flex flex-between flex-items-center">
    Dapibus ac facilisis in
    <span class="badge bg-info">12</span>
  </li>
  <li class="list-item d-flex flex-between flex-items-center">
    Morbi leo risus
    <span class="badge bg-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" aria-current="true">
    <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>

You can even bring in your ordered list numbers into your list group. The use of .list-marker-inner will keep the number inside the visual borders of the list item.

<div class="list list-spaced list-group list-ordered list-marker-inner" style="max-width: 25rem;">
  <div class="list-item d-flex flex-items-start flex-between">
    <div class="ms-0_25 me-auto">
      <div class="font-weight-bold">List item heading</div>
      Donec id elit non mi porta.
    </div>
    <span class="badge bg-info radius-pill">12</span>
  </div>
  <div class="list-item d-flex flex-items-start flex-between">
    <div class="ms-0_25 me-auto">
      <div class="font-weight-bold">List item heading</div>
      Donec id elit non mi porta.
    </div>
    <span class="badge bg-info radius-pill">12</span>
  </div>
  <div class="list-item d-flex flex-items-start flex-between">
    <div class="ms-0_25 me-auto">
      <div class="font-weight-bold">List item heading</div>
      Donec id elit non mi porta.
    </div>
    <span class="badge bg-info radius-pill">12</span>
  </div>
</div>

Checkbox and Radio Inputs

Place checkboxes and radios within list group items and customize as needed. You can also use them without <label>s, but you should include an aria-label attribute and value for accessibility.

<ul class="list list-spaced list-group">
  <li class="list-item">
    <input type="checkbox" value="" id="firstCheckbox">
    <label class="form-check-label" for="firstCheckbox">First checkbox</label>
  </li>
  <li class="list-item">
    <input type="checkbox" value="" id="secondCheckbox">
    <label class="form-check-label" for="secondCheckbox">Second checkbox</label>
  </li>
  <li class="list-item">
    <input type="checkbox" value="" id="thirdCheckbox">
    <label class="form-check-label" for="thirdCheckbox">Third checkbox</label>
  </li>
</ul>

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 type="checkbox" value="">
    First checkbox
  </label>
  <label class="list-item ps-2">
    <input class="ms-n1" type="checkbox" value="">
    Third checkbox with a really long section of example text for the label to show how the label text can be wrapped and remain aligned using utility classes.
  </label>
  <label class="list-item">
    <input type="checkbox" value="">
    Third checkbox
  </label>
</div>

Custom checkbox and radio buttons using .form-checkradio are also supported within lists.

<ul class="list list-spaced list-group">
  <li class="list-item">
    <div class="form-check form-checkradio">
      <input class="form-check-input" type="checkbox" value="" id="fisrtFormCheck">
      <label class="form-check-label" for="fisrtFormCheck">First checkbox</label>
    </div>
  </li>
  <li class="list-item">
    <div class="form-check form-checkradio">
      <input class="form-check-input" type="checkbox" value="" id="secondFormCheck">
      <label class="form-check-label" for="secondFormCheck">Second checkbox</label>
    </div>
  </li>
  <li class="list-item">
    <div class="form-check form-checkradio">
      <input class="form-check-input" type="checkbox" value="" id="thirdFormCheck">
      <label class="form-check-label" for="thirdFormCheck">Third checkbox</label>
    </div>
  </li>
</ul>

Create large hit areas for .form-checkradio inputs by using .link-stretch on the <label> to make the entire list group item clickable.

<ul class="list list-spaced list-group">
  <li class="list-item">
    <div class="form-check form-checkradio">
      <input class="form-check-input" type="checkbox" value="" id="fisrtFormCheckStretch">
      <label class="form-check-label link-stretch" for="fisrtFormCheckStretch">First checkbox</label>
    </div>
  </li>
  <li class="list-item">
    <div class="form-check form-checkradio">
      <input class="form-check-input" type="checkbox" value="" id="secondFormCheckStretch">
      <label class="form-check-label link-stretch" for="secondFormCheckStretch">Second checkbox</label>
    </div>
  </li>
  <li class="list-item">
    <div class="form-check form-checkradio">
      <input class="form-check-input" type="checkbox" value="" id="thirdFormCheckStretch">
      <label class="form-check-label link-stretch" for="thirdFormCheckStretch">Third checkbox</label>
    </div>
  </li>
</ul>

Contextual Classes

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

<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">Info 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-light">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.

<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>

Color Variants

Use color utility classes to style lists with color.

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.

<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>

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.

<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>

SASS Reference

Variables

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

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, $active-bg, $active-color, $active-border);