Components
Icon
Use with caution: availablePreview
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
3
4
5
6
7
8
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:
- 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.
-
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.
-
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
Attributes and Properties
icon
icon
string
The name of the icon to use
size
size
number
The size variant of the icon,
an integer between 3 and 9 inclusive
spriteLocation
sprite-location
string
The location (url) of the icon sprite file.
If not set, uses the global or default location.
The path must be loaded from the same origin as you application, cannot traverse the file system using `..` and must be a `.svg` file.
srtext
srtext
string
Screen-reader text if the icon has semantic meaning
and is not purely decorative.
Component checklist
Maturity
-
Guidance - Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
-
Research - VFS team conducted research on this component which is linked from this page.
-
Stability - Component has been in production for more than 3 months with no significant issues found.
- Note: This component was converted from React to a web-component in August 2022.
-
Adoption - Multiple teams have adopted this component.
Accessibility
While this component has been previously tested against older criteria, it has not yet been audited with the updated testing criteria.
Code assets
-
Variations - Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
-
Responsive - Component depicted in all responsive breakpoints.
-
Interactive states - Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
-
Tokens - All design attributes (color, typography, layout, etc.) are available as tokens.
-
Internationalization - Describes i18n attributes.
Visual assets
-
Variations - Figma library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
-
Responsive - Component designed to work in all responsive breakpoints.
-
Interactive states - Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
-
Tokens - All design attributes (color, typography, layout, etc.) are available as tokens.
Legend:
-
Complete -
Incomplete -
Not applicable