Components

Icon

Icons help communicate meaning, actions, status, or feedback.

Passed WCAG 2.1 AA

About the icon component

Icons are simple symbols that attract attention, aid navigation, signal an action, add emphasis, or provide feedback. Icons serve as recognizable cues that users can understand easily — typically without thinking too hard.

Icons must be used consistently across a site or service in order to accomplish their purpose well. For example, using an envelope icon for both email and a mailing address would likely confuse people. Viewers should be able to trust that a certain icon always means the same thing, no matter where it’s used.

Type to filter icons

243 icons. Click an icon to copy its code snippet.

Guidance

When to use the icon component

• Draw attention to actions. Icons, when paired with text, grab attention and show actions to take. Make sure each icon directly relates to any text it accompanies.
• Help readers find key information. Use icons as scannable, easy-to-understand visual cues for key information, like a phone number or email address.
• Enhance an actionable target. Icons make great touch or click targets. Use an icon for common actions, like opening a menu or sharing an article.

When to consider something else

• Meaning is ambiguous. Use icons only in a common or conventional way. Icon utility hinges on people quickly recognizing what each icon means. If you suspect that an icon’s intent isn’t perfectly clear, consider removing it or adding accompanying text.
• Compensating for page structure. Don’t rely on an icon to help draw attention to something important that’s otherwise hard to find. Icons don’t fix unclear page hierarchy or confusing content organization.
• You need illustrative artwork. Icons have a specific, functional meaning. Avoid using icons for illustrative purposes. For example, don’t use the “visibility” eye icon () to illustrate an actual eye. If you want to enhance the appearance of your content or visually explain a concept, use an illustration instead of an icon.

Usability guidance

• Combine icons with text. Only a few icons are consistently understood across the digital-using public of the world, among them home (), print (), and search (). Combine icons with text to improve clarity, and test your icons for recognition and memorability with your particular audience.
• Be consistent with icon meaning. Icons used more than once in an application or site must be used to represent the same thing, and have the same text description in every instance. For example, if an icon of a blank piece of paper means “new document” on most screens, choose a different icon to communicate “reformat document.” Consistency helps people with some cognitive disabilities, helps people who might be distracted or scanning, and creates a better user experience for all.
• Combine interactive icons with other components. If the icon is part of an interactive element, it should be implemented within another functional component. For example, make an icon part of a button or list.

Accessibility guidance

Test the icon component in your own project.

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

Use icon accessibility tests

• Hide decorative icons from screen readers. Icons are decorative if they don’t provide meaningful information to the user. Usually, decorative icons are accompanied by text. Announcing a decorative icon is redundant and can be annoying. Use the aria-hidden="true" and role="img", as in the following code:

  <a href="https://twitter.com/uswds">
    <svg class="usa-icon" aria-hidden="true" role="img">
      <use href="/assets/img/sprite.svg#arrow_forward"></use>
    </svg>
    USWDS' Twitter account
  </a>
  

• Provide descriptive text if a standalone icon has meaning or provides functionality. If an icon provides information or functionality that people cannot understand from accompanying text, you need to make the icon perceivable to people who use screen readers. Remove the aria-hidden="true" attribute and add an aria-labelledby attribute with a value that matches the id of a <title> element added inside the SVG, as in the following code:

  <a href="https://twitter.com/uswds">
    <svg aria-labelledby="twitter-title" role="img">
      <title id="twitter-title">USWDS' Twitter account</title>
      <use href="/path/to/sprite.svg#twitter"></use>
    </svg>
  </a>
  

• Check for good color contrast. Make sure that the icon has a minimum contrast ratio of 3:1 against its background. See the USWDS color and accessibility page as well as WCAG 2.1 Techniques: Ensuring that a contrast ratio of 3:1 is provided for icons for more information.
• Place icons inside links. If icons accompany a text link, place the icon inside the link to prevent screen readers from announcing the link twice.

Using the icon component

• Don’t alter icons. You shouldn’t customize, combine, or change USWDS icons (other than updating the color) due to their license.
• Active icons are found in dist/img/usa-icons. The icons in this directory will be packaged into an SVG sprite. The complete set of available icons are located in two directories: dist/img/material-icons and dist/img/uswds-icons. Copy icons into a usa-icons directory within your project images directory, and rebuild the SVG sprite using uswds-compile.
• Using color in icons. Icons use currentColor, so the color of the icon will be the text color of its parent element. Change colors with the color utility.
• Relative to font size. By default, icons will scale with font size. If you want to specify an icon size, use one of the component’s size variants.
• Icon names are identifiers. To use an icon, simply change the identifier after the pound sign in the sprite path to that icon’s name. For example, to use the accessibility_new icon, the path will be <use href="/path/to/sprite.svg#accessibility_new">, or to use the info icon, the path will be <use href="/path/to/sprite.svg#info">.

Icon settings

This component has no settings.

Icon variants

Variant	Description
.usa-icon--size-3	3 unit x 3 unit icon.
.usa-icon--size-4	4 unit x 4 unit icon.
.usa-icon--size-5	5 unit x 5 unit icon.
.usa-icon--size-6	6 unit x 6 unit icon.
.usa-icon--size-7	7 unit x 7 unit icon.
.usa-icon--size-8	8 unit x 8 unit icon.
.usa-icon--size-9	9 unit x 9 unit icon.

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	0	0	5	0

Overview of recent accessibility test results:

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

Learn more on the icon accessibility tests page.

Package

• Package usage: @forward "usa-icon";
• Dependencies: uswds-core

Disclaimer

Use of any social media icons placed on this page are subject to separate terms and conditions that govern the use of said icons. The General Services Administration (GSA) does not review and evaluate such agreements for anything beyond the GSA’s needs, and users should make their own decisions regarding the use of such services for their own purposes. In addition, a reference to any non-federal entity does not constitute or imply its endorsement, recommendation, or favoring by GSA.

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-06-07	N/A	Guidance	No	Added clarity to icon guidance. More information: uswds-site#2643
2024-03-20	N/A	Guidance	No	Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2518
2023-11-09	3.7.0	Assets	No	Added the X social media icon. We also preserved the legacy Twitter icon to allow teams to make the decision on when to update their social media information. More information: uswds#5589
2023-10-20	N/A	Guidance	No	Added note about icon color contrast. More information: uswds-site#2258
2023-09-29	N/A	Guidance	No	Added social media icon disclaimer. This disclaimer explains that social media icons are subject to separate terms and conditions, and that our inclusion of these icons does not constitute an endorsement of these services. More information: uswds-site#2292
2022-10-19	3.2.0	JavaScript	No	Updated our SVG sprite compiler to fix potential incompatibility with ARM-based Macs. This should resolve potential dependency incompatibilities on computers with ARM processors. More information: uswds#4665
2022-08-05	3.1.0	Assets	No	Added LinkedIn icon. We now have a LinkedIn icon included in our default icon sprite as linkedin. More information: uswds#4872
2022-08-05	3.1.0	Assets	Breaking	Breaking Added unmodified social media icons. We now provide simpler social media icons, and removed any decoration not in the original icon. This means that the new icons are not in an enclosing circle unless the original icon is enclosed in a circle. More information: uswds#4872
2022-06-17	3.0.2	Assets	No	Updated us_flag_small to be high resolution. More information: uswds#4792
2022-06-17	3.0.2	Assets	No	Added fax to the default set. More information: uswds#4797
2022-06-17	3.0.2	Assets	No	Added remove_circle to the default set. More information: uswds#4791
2022-06-17	3.0.2	Assets Styles	No	Navigate_far icons now accept custom color. We fixed the navigate_far_before and navigate_far_next icons to allow a customColor fill. More information: uswds#4780
2022-04-28	3.0.0	Assets JavaScript Styles	Breaking	Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656
2022-03-10	N/A	Guidance	No	Replaced uswds-gulp with uswds-compile. More information: uswds-site#1424
2022-03-07	2.13.2	Assets	No	Fixed GitHub icon to prevent CSP flag. Resolves an error which can occur when using the USWDS icon component SVG sprite in combination with a Content Security Policy (CSP), where the presence of an inline style tag within the GitHub icon can violate most common CSPs which do not include the unsafe-inline style-src directive. More information: uswds#4487
2021-12-14	2.13.0	Accessibility Assets Markup	Breaking	Breaking Improved resilience of icon-only functionality. We updated a couple components that use icon-only buttons so that they provide a text equivalent if the image path is broken and does not load. More information: uswds#4211
2021-04-28	2.11.2	Assets	Breaking	Breaking Fixed the size of some of our icons. The view box on some or our icons was 20px instead of 24px. We updated these icons to use the proper view box. This may result in small changes to the display of icons, but will result in a more consistent placement and appearance across all icons in our icon set. More information: uswds#4139
2021-04-28	2.11.2	Assets	No	Swapped thumb icons in our sprite for consistency. We replaced thumb_down_off_alt with thumb_down_off in our icon sprite for consistency with its thumb_up pair. More information: uswds#4139
2021-04-28	2.11.2	Assets	Breaking	Breaking Removed duplicate eye icon. Removes remove_red_eye icon from usa-icons and sprite. Use visibility instead. More information: uswds#4139
2021-03-17	N/A	Guidance	No	Updated and improved guidance for icons. More information: uswds-site#1180
2021-03-17	2.11.1	Assets	No	Restored missing white icons. Restored add--white, check_circle--white, error--white, expand_more--white, info--white, remove--white, and warning--white icons. More information: uswds#4106
2021-03-17	2.11.0	Assets Styles	No	Provided better support for color icons that adapt to theme settings. Now the color of the alert icon will update automatically to adapt to the alert background, or to the color of the alert text. More information: uswds#4079
2021-03-02	2.10.2	Assets	No	Introduced white add, remove, and expand_more icons. More information: uswds#4061