Components

List

A list organizes information into discrete sequential sections.

Unordered list

  • Unordered list item
  • Unordered list item
  • Unordered list item

Ordered list

  1. Ordered list item
  2. Ordered list item
  3. Ordered list item

Unstyled list

  • Unstyled list item
  • Unstyled list item
  • Unstyled list item
<div class="grid-row grid-gap">
  <div class="mobile-lg:grid-col-4">
    <h3 class="site-preview-heading margin-0">Unordered list</h3>
    <ul class="usa-list">
      <li>Unordered list item</li>
      <li>Unordered list item</li>
      <li>Unordered list item</li>
    </ul>
  </div>
  <div class="mobile-lg:grid-col-4 margin-top-4 mobile-lg:margin-top-0">
    <h3 class="site-preview-heading margin-0">Ordered list</h3>
    <ol class="usa-list">
      <li>Ordered list item</li>
      <li>Ordered list item</li>
      <li>Ordered list item</li>
    </ol>
  </div>
  <div class="mobile-lg:grid-col-4 margin-top-4 mobile-lg:margin-top-0">
    <h3 class="site-preview-heading margin-0">Unstyled list</h3>
    <ul class="usa-list usa-list--unstyled">
      <li>Unstyled list item</li>
      <li>Unstyled list item</li>
      <li>Unstyled list item</li>
    </ul>
  </div>
</div>

Guidance

When to use the list component

  • Ordered list: Use an ordered list when you need to display text in some ranking, hierarchy, or series of steps.
  • Unordered list: Use unordered lists to display text in no specific order.

When to consider something else

  • If you need to communicate long lists of narrative text.

Usability guidance

  • Use sentence case and begin lists with a capital letter.
  • Use punctuation appropriate to the text. Do not leave sentences without periods.

Using the list component

  • Remove list styles with the unstyled variant. For unstyled lists, either add the .usa-list--unstyled class or use the Sass mixin: @include unstyled-list.

List settings

This component has no settings.

List variants

Variant Description

.usa-list--unstyled

Remove list styles.

Package

  • Package usage: @forward "usa-list";

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2023-11-20 N/A
  • Guidance
No

Added documentation for usa-list--unstyled variant. More information: uswds-site#2162

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656