Components
Icon
Use with caution: available Web, Mobile appPreview
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
When to request a new icon
Consider requesting a new icon to be added to the Design System when:
- No existing icon conveys the intended meaning: After thoroughly searching both VADS and USWDS icon libraries, you cannot find an icon that clearly represents the concept or action you need to communicate.
- The icon serves a broad, reusable purpose: The icon would be useful across multiple VA applications and teams, not just for a single, specific use case.
When not to request a new icon
Avoid requesting a new icon when:
- An existing icon is “close enough”: If an existing icon can reasonably represent your concept, use it instead of requesting a similar variation
- It’s purely decorative: Icons that serve only visual decoration and don’t convey meaning should use existing options
- It’s highly specific to one use case: Icons that would only be useful in a single application or context should be handled locally rather than added to the system
- It duplicates existing functionality: Multiple icons that serve the same semantic purpose create inconsistency and confusion
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 Request: If you've identified an icon that meets your needs and aligns with VADS guidelines, you can propose its addition to the Design System using the link below:
If your request is part of an experimental initiative, please link any related tickets to provide context and ensure visibility for the Design System team.Request a new addition to the Design System
Code usage
Web
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.
Mobile app
Props
name
string
Name of the icon to display from the VA icon library
size
number
24
Size of the icon in pixels
fill
string
Color to fill the icon
testID
string
Optional test ID for test suites
Component checklist
Web Platform
9 of 10 complete
Mobile App Platform
0 of 13 complete
Maturity
-
Guidance
-
Web Mobile app
Examples, usage, code usage, content considerations, and accessibility considerations are all complete. -
Research
-
Web Mobile app
VFS team conducted research on this component which is linked from this page. -
Stability
-
Web Mobile app
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
-
Web Mobile app
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
-
Web Mobile app
Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.) -
Responsive
-
Web Mobile app
Component depicted in all responsive breakpoints. -
Interactive states
-
Web Mobile app
Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled). -
Tokens
-
N/A Web
Mobile app
All design attributes (color, typography, layout, etc.) are available as tokens. -
Internationalization
-
N/A Web
Mobile app
Describes i18n attributes.
Visual assets
-
Variations
-
Web Mobile app
Figma library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.) -
Responsive
-
Web Mobile app
Component designed to work in all responsive breakpoints. -
Interactive states
-
Web Mobile app
Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled). -
Tokens
-
N/A Web
Mobile app
All design attributes (color, typography, layout, etc.) are available as tokens.
Legend:
-
Complete -
Incomplete - N/A Not applicable
Provide feedback
Share your feedback, report issues, or suggest improvements for the Icon component. Your input helps us make the design system better for everyone.
- Get immediate support in #platform-design-system for technical or urgent issues.
- Explore all feedback channels for additional ways to share your input.