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>

<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