Components

List

A list organizes information into discrete sequential sections.

Passed WCAG 2.1 AA

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.

Accessibility guidance

Test the list component in your own project.

USWDS tested the list component for accessibility. You should test your implementation, too.

Use list accessibility tests

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.

Accessibility test status

The USWDS team did 5 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:

Total tests	Passed	Passed with exceptions	Conditional	Failed
5	5	0	0	0

Overview of recent accessibility test results:

• Passed: 5
• Passed with exceptions: 0
• Conditional: 0
• Failed: 0

Learn more on the list accessibility tests page.

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
2024-08-13	N/A	Guidance	No	Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2746
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