Icon

Preview

Usage

How this component works

This web component provides access to the full suite of U.S. Web Design System iconography as well as additions specific to the VA. The list of available icons is a foundational element of the Design System.

Choosing between icons

Each icon has a chosen semantic meaning and should be used in a manner that is consistent with that meaning. For example, a clock icon is used to represent time and thus should not be ambiguously used to represent a date. Some icons are intentionally used in different applications because they share the same meaning.

Before introducing a new icon check the list to be see if the meaning of the icon you need corresponds to an existing icon. If you have questions about a new icon, or icon usage, feel free to reach out to the Design System team.

Icon Color

By default, the web component icon will display as --vads-color-base which is the base color set across VA.gov. If a different icon color is needed, a color style can be applied directly to the web component element using CSS. You may also add a background-color as seen in the example below.

.icon {
    color: var(--vads-color-white);
    background-color: var(--vads-color-primary);
    border-radius: 50%;
    padding: units(1);
}

<va-icon size="3" icon="medical_services" class="icon" />

Icon Sizing Reference

Accessibility considerations

Icon usage typically falls into two categories, decorative and semantic.

• Decorative icons are icons that are only used for visual reinforcement. If these were removed from the page, users would still be able to understand and use the page.
• Semantic icons are icons that convey meaning, rather than only being decorative. This includes icons without text next to them that are used as interactive elements such as buttons.

Using decorative icons

If your icons are only decorative, do not include srtext on the component. The component will add an aria-hidden attribute to the icon for accessibility.

Icon buttons containing a decorative icon plus a visual label are supported with Button - Icon, but with limited options. Rather than supporting any text and icon combination, these will be added on a case-by-case basis. Generally, we feel that icons in buttons are not necessary.

Using semantic icons

We do not advise using icons as links or buttons on their own. Links and buttons should always have a visible label.

Exceptions to this are a close button on a modal or an alert. However, it is advised to use the design system component for these scenarios, as they are coded with the proper accessibility attributes.

Requesting a new icon

If your team needs a new icon and wants to suggest adding it to the design system, follow these steps:

1. Check Existing VADS Icons: Look through the entire icon set to ensure a similar icon does not already exist. We aim to maintain consistency in semantic use by avoiding duplicating similar icons.
2. Explore USWDS Icons: Search USWDS Icon to see if another existing icon suits your needs. Preferably, choose generic icons that could be reused in various applications.

   If VADS and USWDS do not contain a suitable icon, you may search Material Icons or browse the official Material Design Icons Figma plugin by Google. Note that we typically use the "filled" icon style.

3. Submit Your Icon: Once you've found a suitable icon for VADS, submit it using the following link:

   Request a new addition to the Design System

Code usage