Components

Icon list

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

Passed WCAG 2.1 AA

Default

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

Simple content

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

Rich content

  • Donate cash when possible.

    Financial contributions to recognized disaster relief organizations are the fastest, most flexible and most effective method of donating. Organizations on the ground know what items and quantities are needed, often buy in bulk with discounts and, if possible, purchase through businesses local to the disaster, which supports economic recovery.

  • Confirm what donations are needed.

    Unneeded and unsolicited goods burden local organizations’ ability to meet survivors’ confirmed needs, drawing away valuable volunteer labor, transportation and warehouse space.

  • Talk to trusted organizations about volunteering.

    Financial contributions to recognized disaster relief organizations are the fastest, most flexible and most effective method of donating. Organizations on the ground know what items and quantities are needed, often buy in bulk with discounts and, if possible, purchase through businesses local to the disaster, which supports economic recovery.

Custom size with rich content

Here are a few easy ways you can help reduce energy use and costs while spending more time at home.

  • Let the sun shine.

    On sunny days, open your curtains to allow the sun to naturally warm the rooms of your home without using electricity. Natural sunlight can also lift your mood to help brighten your day. On warm days, close your curtains to help keep your house cool.

  • Adjust your schedule.

    Instead of running high-energy-use appliances such as dishwashers and clothes dryers during mid-afternoon or early evening hours, operate them early in the morning or late at night. Some utilities charge less at off-peak times, which will help reduce your costs.

  • Fill it up.

    Wash full loads, whether it’s clothes or dishes. Washing multiple small loads means you’re using and heating more water, which can increase your expenses. Using cold water for clothes washing can also help lower your costs.

Custom size

  • 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? 

<div class="grid-row grid-gap">
  <div class="tablet:grid-col">
    <h3 class="site-preview-heading border-top-1px border-base-light padding-top-1 margin-top-0">Default</h3>
    <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="/assets/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="/assets/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="/assets/img/sprite.svg#cancel"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">Avoid large gatherings</div>
  </li>
</ul>
  </div>
  <div class="tablet:grid-col">
    <h3 class="site-preview-heading border-top-1px border-base-light padding-top-1 tablet:margin-top-0">Simple content</h3>
    <p class="margin-bottom-2">Benefits of joining Global Entry program:</p>
    <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="/assets/img/sprite.svg#thumb_up_alt"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">No processing lines</div>
  </li>
  <li class="usa-icon-list__item">
    <div class="usa-icon-list__icon">
      <svg class="usa-icon" aria-hidden="true" role="img">
        <use href="/assets/img/sprite.svg#thumb_up_alt"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      Access to expedited entry benefits in other countries
    </div>
  </li>
  <li class="usa-icon-list__item">
    <div class="usa-icon-list__icon">
      <svg class="usa-icon" aria-hidden="true" role="img">
        <use href="/assets/img/sprite.svg#thumb_up_alt"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">Available at major U.S. airports</div>
  </li>
  <li class="usa-icon-list__item">
    <div class="usa-icon-list__icon">
      <svg class="usa-icon" aria-hidden="true" role="img">
        <use href="/assets/img/sprite.svg#thumb_up_alt"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">Reduced wait times</div>
  </li>
</ul>
  </div>
</div>
<div class="grid-row grid-gap">
  <div class="tablet:grid-col">
    <h3 class="site-preview-heading border-top-1px border-base-light padding-top-1">Rich content</h3>
    <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="/assets/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 are
        the fastest, most flexible and most effective method of donating.
        Organizations on the ground know what items and quantities are needed,
        often buy in bulk with discounts and, if possible, purchase through
        businesses local to the disaster, which supports economic recovery.
      </p>
    </div>
  </li>
  <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="/assets/img/sprite.svg#check_circle"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      <h4 class="usa-icon-list__title">Confirm what donations are needed.</h4>
      <p>
        Unneeded and unsolicited goods burden local organizations’ ability to
        meet survivors’ confirmed needs, drawing away valuable volunteer labor,
        transportation and warehouse space.
      </p>
    </div>
  </li>
  <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="/assets/img/sprite.svg#check_circle"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      <h4 class="usa-icon-list__title">
        Talk to trusted organizations about volunteering.
      </h4>
      <p>
        Financial contributions to recognized disaster relief organizations are
        the fastest, most flexible and most effective method of donating.
        Organizations on the ground know what items and quantities are needed,
        often buy in bulk with discounts and, if possible, purchase through
        businesses local to the disaster, which supports economic recovery.
      </p>
    </div>
  </li>
</ul>
  </div>
  <div class="tablet:grid-col">
    <h3 class="site-preview-heading border-top-1px border-base-light padding-top-1">Custom size with rich content</h3>
    <p class="margin-bottom-2">Here are a few easy ways you can help reduce energy use and costs while spending more time at home.</p>
    <ul class="usa-icon-list usa-icon-list--size-lg">
  <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="/assets/img/sprite.svg#attach_money"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      <h4 class="usa-icon-list__title">Let the sun shine.</h4>
      <p>
        On sunny days, open your curtains to allow the sun to naturally warm the
        rooms of your home without using electricity. Natural sunlight can also
        lift your mood to help brighten your day. On warm days, close your
        curtains to help keep your house cool.
      </p>
    </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="/assets/img/sprite.svg#attach_money"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      <h4 class="usa-icon-list__title">Adjust your schedule.</h4>
      <p>
        Instead of running high-energy-use appliances such as dishwashers and
        clothes dryers during mid-afternoon or early evening hours, operate them
        early in the morning or late at night. Some utilities charge less at
        off-peak times, which will help reduce your costs.
      </p>
    </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="/assets/img/sprite.svg#attach_money"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      <h4 class="usa-icon-list__title">Fill it up.</h4>
      <p>
        Wash full loads, whether it’s clothes or dishes. Washing multiple small
        loads means you’re using and heating more water, which can increase your
        expenses. Using cold water for clothes washing can also help lower your
        costs.
      </p>
    </div>
  </li>
</ul>
  </div>
</div>
<div class="grid-row grid-gap">
  <div class="tablet:grid-col">
    <h3 class="site-preview-heading border-top-1px border-base-light padding-top-1">Custom size</h3>
    <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="/assets/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>
  <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="/assets/img/sprite.svg#help"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      <span class="text-bold">Funding.</span> Do I have enough money to launch a
      business?
    </div>
  </li>
  <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="/assets/img/sprite.svg#help"></use>
      </svg>
    </div>
    <div class="usa-icon-list__content">
      <span class="text-bold">Need.</span> Will this business fill a real need
      for my customers?
    </div>
  </li>
</ul>
  </div>
</div>

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. This can be effective in a list, or pair of lists, that describe actions users should do or not do. A pair of icons with clear and opposite meaning, like check_circle () and cancel (), create an effective do-and-don’t list.
  • 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, like a checklist of items to pack or documents to complete.
  • Printable checklists. Users may wish to print a page and use it as a physical checklist. This kind of static checklist is not an interactive form. Use an icon like check_box_outline_blank () to provide a space for physical checking.

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.
  • Using complex iconography or graphics. Use the graphic list if you plan on using different large, complex, or multicolored images with each list item. The icon should only reinforce the text of the list item. If the image needs to convey unique meaning, this is a job for an illustration not an icon.
  • Improving readability of running text. The standard unordered list is best for displaying simple lists that are part of running text.

Usability guidance

  • Use consistent headings. Headings should be written with parallel structure. For example, start each with an action verb. When possible, keep headings short enough to fit on one or two lines.
  • Add rich content sparingly. Each list item can display rich text content like HTML, images, and even other components. Be succinct. Too much complexity distracts from the impact of an icon list.
  • Use similar icons. Use the same icon for each list item unless variation is meaningful, as with our check_circle icon () and cancel icon (). Icons should come from the same icon library and have a similar look and feel.

Accessibility guidance

Test the icon list component in your own project.

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

Use icon list accessibility tests
  • 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.
  • Use colors with accessible contrast. While the icons in an icon list might be considered decorative progressive enhancement, aim for accessible AA contrast. This assures legibility on printed pages as well.
  • Hide most icons from screen readers. This component uses the aria-hidden="true" and role=”img” attributes because the icons are used solely as a visual progressive enhancement. The icon’s meaning is redundant with the list content.
  • If you wish to expose icons to screen readers:
    • Provide descriptive text for each icon.
    • Remove the aria-hidden="true" attribute and add a aria-labelledby attribute with a value that matches the id of a title element added inside the svg. 
      <a href="https://twitter.com/uswds">
<svg aria-labelledby="twitter-title" role="img">
  <title id="twitter-title">The USWDS Twitter account</title>
  <use href="/path/to/sprite.svg#twitter"></use>
</svg>
</a>

Using the icon list component

Icon list 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.

Icon list 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.

[responsive_variant]:usa-icon-list--size-[size]

Add a responsive breakpoint prefix separated with a : to target a utility at a responsive breakpoint and higher, following a mobile-first methodology.

Accessibility test status

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

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
7 1 0 6 0

Overview of recent accessibility test results:

  • Passed: 1
  • Passed with exceptions: 0
  • Conditional: 6
  • Failed: 0

Learn more on the icon list accessibility tests page.

Package

  • Package usage: @forward "usa-icon-list";
  • Dependencies: uswds-fonts, usa-input

Latest updates

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

Date USWDS version Affects Breaking Description
2024-12-18 N/A
  • Guidance
 No

Removed deprecated xlink references from code samples. More information: uswds-site#2926

2024-12-18 3.11.0
  • Markup
 No

Replaced deprecated xlink:href references with href. More information: uswds#6165

2024-12-13 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#3008

2023-11-20 N/A
  • Guidance
 No

Updated the value list for icon list variants. 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

2021-03-17 N/A
  • Guidance
 No

Added icon list documentation. More information: uswds-site#1180

2021-03-17 2.11.0
  • Guidance
  • Markup
  • Styles
 No

Added the icon list component. An icon list reinforces the meaning and visibility of individual list items with a leading icon. More information: uswds#4099