Skip to main content

Icon List

An icon list reinforces the meaning and visibility of individual list items with a leading icon.


Default Icon List

Component Preview

  • Wash your hands for 20 seconds with soap
  • Stay six feet away from others
  • Avoid large gatherings

Component Code

<ul class="usa-icon-list">
  <li class="usa-icon-list__item">
    <div class="usa-icon-list__icon text-green">
      <svg class="usa-icon" aria-hidden="true" role="img">
        <use href="/civic-guide/uswds/img/sprite.svg#check_circle"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">Wash your hands for 20 seconds with soap</div>
  </li>
  <li class="usa-icon-list__item">
    <div class="usa-icon-list__icon text-green">
      <svg class="usa-icon" aria-hidden="true" role="img">
        <use href="/civic-guide/uswds/img/sprite.svg#check_circle"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">Stay six feet away from others</div>
  </li>
  <li class="usa-icon-list__item">
    <div class="usa-icon-list__icon text-red">
      <svg class="usa-icon" aria-hidden="true" role="img">
        <use href="/civic-guide/uswds/img/sprite.svg#cancel"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">Avoid large gatherings</div>
  </li>
</ul>

Simple Content Icon List

Component Preview

Benefits of joining Global Entry program:

  • No processing lines
  • Access to expedited entry benefits in other countries
  • Available at major U.S. airports
  • Reduced wait times

Component Code

<ul class="usa-icon-list usa-icon-list--primary">
  <li class="usa-icon-list__item">
    <div class="usa-icon-list__icon">
      <svg class="usa-icon" aria-hidden="true" role="img">
        <use href="/civic-guide/uswds/img/sprite.svg#thumb_up_alt"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">No processing lines</div>
  </li>
  <!-- More items... -->
</ul>

Rich Content Icon List

Component Preview

  • Donate cash when possible.

    Financial contributions to recognized disaster relief organizations are the fastest, most flexible and most effective method of donating.

  • Confirm what donations are needed.

    Unneeded and unsolicited goods burden local organizations' ability to meet survivors' confirmed needs.

  • Talk to trusted organizations about volunteering.

    Organizations on the ground know what items and quantities are needed.


Component Code

<ul class="usa-icon-list">
  <li class="usa-icon-list__item">
    <div class="usa-icon-list__icon text-ink">
      <svg class="usa-icon" aria-hidden="true" role="img">
        <use href="/civic-guide/uswds/img/sprite.svg#check_circle"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      <h4 class="usa-icon-list__title">Donate cash when possible.</h4>
      <p>Financial contributions to recognized disaster relief organizations...</p>
    </div>
  </li>
</ul>

Custom Size Icon List

Component Preview

  • Timing. Is now the right time to start a business?
  • Funding. Do I have enough money to launch a business?
  • Need. Will this business fill a real need for my customers?

Component Code

<ul class="usa-icon-list usa-icon-list--size-lg">
  <li class="usa-icon-list__item">
    <div class="usa-icon-list__icon text-blue">
      <svg class="usa-icon" aria-hidden="true" role="img">
        <use href="/civic-guide/uswds/img/sprite.svg#help"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      <span class="text-bold">Timing.</span> Is now the right time to start a business?
    </div>
  </li>
</ul>


Guidance

When to use the icon list component

Do-and-don't lists.
Icon lists help reinforce the message of a list item using a visual cue as a progressive enhancement.
Features and metadata.
Use an icon list to enhance a list of features, like a campsite's amenities or other lists where icons might help users understand content at a glance.
Important tasks or requirements.
Use an icon list to help users find, distinguish, and verify related steps or tasks that can be completed in any order.

When to consider something else

Multi-step forms or wizards.
The step indicator is best for communicating progress through a form or process that spans several different pages.
Sequential steps.
Use a standard ordered list or process list if the items must be completed sequentially.

Usability guidance

Use consistent headings.
Headings should be written with parallel structure. For example, start each with an action verb.
Use similar icons.
Use the same icon for each list item unless variation is meaningful.

Accessibility guidance

Don't rely on the icons alone to convey meaning.
Use text and context to establish the meaning of your list, and use the icon to reinforce that meaning as a progressive enhancement.
Hide most icons from screen readers.
This component uses aria-hidden="true" because the icons are used solely as a visual progressive enhancement.

USWDS Documentation

For more guidance, view the USWDS Icon List Component Documentation.



Settings

Variable Description
$theme-icon-list-font-family

Font family of the content text.
$theme-icon-list-title-font-family

Font family of the content title.


Variants

Variant Description

.usa-icon-list--[color]

Change the color of all the list's icons by updating [color] to any theme or state color token.

.usa-icon-list--size-[size]

Change the size of the text and icon by updating [size] to a font size token.
Looking for U.S. government information and services?
Visit USA.gov