Icons

Variations Design Guidelines Code Reference Accessibility

Icons
updated

HTML/CSS Available
Web Component Beta
Last Updated
2.11.0

Icons enhance experiences by visually communicating meaning, actions, status, and feedback. Browse available icons on the Iconography page.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

Use to create a static, non-interactive icon.

HTML

Web Component

<svg class="mds-icon">
    <use xlink:href="/icons/mds.svg#heart">
        <title>favorite</title>
    </use>
</svg>

<mds-icon name="heart" title="favorite"></mds-icon>

Many components—like Buttons, List Groups and Headers—account for the use of icons to enhance their display. See component documentation pages for details on using and sizing icons.

Sizing

Icons are available in small and medium sizes. The default size is medium, and you can use modifier classes or props to make them smaller or larger.

Small

Medium (Default)

Small

Medium (Default)

HTML

Web Component

<svg class="mds-icon mds-icon--s">
    <use xlink:href="/icons/mds.svg#heart--s">
        <title>favorite</title>
    </use>
</svg>

<mds-icon name="heart--s" title="favorite"></mds-icon>

Components, like Buttons, have specific rules for which size icons to use. Always follow component guidelines on icon use.
Always use small icon artwork for small icons and default icon artwork for medium icons. Using the wrong size icon results in undesirable scaling of the artwork.

Use When

Creating static, non-interactive icons to supplement content.

Don’t Use When

Creating an interactive icon. Instead, use the Icon-Only Button.
Creating a toolbar of interactive icons. Instead, use the Icon-Only Button Group.

Visual Language

Available icons are listed on the Iconography page.
Never use IP icons to represent anything other than their established meanings.
Medium icons are 23px by 23px.
Small icons are 15px by 15px.
Icons are black #000000 by default, style icons by adding a fill property in your product’s CSS.

CSS

Class References

Class	Applies to	Outcome
`.mds-icon--s`	`.mds-icon`	Scales icon down to `15px` by `15px`.

Mixin Reference

@include icon-height-removal()

Use to vertically center an icon without influencing overall vertical spacing, particularly when cropping text to cap height and baseline using the mds-text-crop mixin.

Web Component

Props

Prop	Type	Validation	Default	Description
`ariaHidden`	Boolean	––	`true`, switches to false if `title` is provided.	Sets the `aria-hidden` attribute on the `<svg>`.
`class`	String	––	––	A space-separated list of class names that will be appended to the default `mds-icon` class.
`id`	String	––	––	The `id` attribute for the `<svg>`.
`name`	String	Enum: `[ MDS Icon Name]` See the iconography page for icon names.	––	A string containing a valid MDS icon name.
`title`	String	––	––	Describes the icon for assistive technologies. Used only when there is no accompanying text with the icon, e.g., a Button with icon.

Use kebab-case when setting props in HTML. For example, hiddenLabel would be written as hidden-label.

Using the Icon Sprite

The MDS icon sprite, mds.svg must be injected into any page where the <mds-icon> web component is used. Previous implementations of icons in MDS allowed loading of the icon sprite via an external reference, but that method has proved unreliable when used alongside custom elements.

Usage Examples

Selecting an icon:

<mds-icon name="heart"></mds-icon>

Using the title attribute:

<mds-icon name="question-circle--s" title="FAQ"></mds-icon>

Browser Support

The MDS icons depend on the svg4everybody polyfill for IE11 compatibility.

Implementation

Update the <title> tag within the SVG with a text describing the icons.