Skip to main content

An official website of the United States government

Here's how you know

An official website of the United States government

Here's how you know

Theme:

Design system switcher

Version:

Design system switcher

Theme:

Design system switcher

Version:

Design system switcher

Icon

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

Examples

The <SvgIcon> component is a re-usable component that wraps its children in an <svg> element. This component is used by each individual icon component listed below.

Loading

Changing icon color

Icon components support a few built-in color options that can be applied by using one of the following utility classes.

If you need a different color for an icon, you can pass a custom class to an icon component through the class prop. Then, in your application CSS, set the color prop.

ColorCSS utility ClassExample
Primaryds-c-icon-color--primary
Inverseds-c-icon-color--inverse
Errords-c-icon-color--error
Warnds-c-icon-color--warn
Successds-c-icon-color--success

Changing icon size

Icon components use ems for their height and width and can thereby be sized by changing the font-size of the SVG element.

It is recommended that the font-size utilities be used.

SizeExample
Small
Default
Large
Extra Large
2x Large
3x Large
4x Large
5x Large

Creating custom icons

The <SvgIcon> component can be used for other custom icons. It allows you to pass in the SVG child elements. This component is recommended if you want built-in accessibility features and standard icon styles.

In the example below, the <SvgIcon> component is used with a custom path.

Code

React

See Storybook for React guidance of this component.

Style customization

The following CSS variables can be overridden to customize Icon components:

CSS variables for icon
VariableDefault Core Theme Value
--icon__color--errorhex value: #e31c3d--color-error
--icon__color--inversehex value: #ffffff--color-white
--icon__color--primaryhex value: #0071bc--color-primary
--icon__color--successhex value: #12890e--color-secondary
--icon__color--warnhex value: #f8c41f--color-warn

Guidance

Accessibility

The <SvgIcon> component has built-in accessibility features including:

  • a built-in title attribute. For any specific exported icon, the title attribute is defaulted, but can be overwritten.
  • focusable="false" which prevents the icon from being focusable
  • role="img" which tells assistive technologies that the icon's purpose is as an image
  • optional description attribute which can be used for a more detailed explanation of the icon's contents. Meant to be used to provide more detail than just the title
  • an availableariaHidden attribute which can be used if the icon's context is described elsewhere. For example, if the icon is part of a button with text, the text may provide the text description instead of the icon component.

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Complete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Not applicable

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Complete

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete