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>

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