Icon

Accessibility

Accessibility considerations

When using a decorative icon, it shouldn’t be read out to screen-reader users because it doesn’t add to their understanding. Icons should be accompanied with text.

All interactive accessible icons must be keyboard accessible and touch accessible as well as clickable via a mouse.

When to use role=”img”

If an icon is being used alone (without support text), it should have a role="img" AND appropriate ARIA markup OR screen reader only descriptive text.

When to use

If an icon is being used with visual (and assistive device) text, it should have role="presentation".

• Hide decorative icons from screen readers. Use the aria-hidden=”true” and role=”img” attributes if the icon is redundant and used solely as visual progressive enhancement.

• Provide descriptive text if a standalone icon has semantic meaning. If you need to expose an icon to screen readers, remove the aria-hidden=”true” attribute and add an aria-labelledby attribute with a value that matches the id of a

• Place icons inside links. If icons accompany a text link, place the icon inside the link to prevent the screen reader from announcing the link twice.

Using the icon component

• Don’t alter icons. You shouldn’t customize, combine, or change the icons (other than updating the color) due to their license, as described on GitHub.

• 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 individual, simply change the identifier after the pound sign in the sprite path to the icon name. For example, to use the accessibility_new icon, the path will be <use xlink:href="/path/to/sprite.svg#accessibility_new">, or to use the info icon, the path will be <use xlink:href="/path/to/sprite.svg#info">.