Skip to content
On this page

Icon

A graphical representation of an idea.

See the Icons section for more information, including a list of all available icons.

Demos

Simple icon

Label

NameValue
View
Reading direction

Using icons in buttons

Icons can be used inside other components, like buttons. For demos of how to use icons inside buttons, see the Button documentation.

Icon sizes

Icons support a few different pre-defined size options. Right now the supported sizes are: medium, small, and x-small.

If no size property is provided, the medium size will be used by default.

Icon size examples for all supported size values.
Example icon at medium sizeMedium Icon20px
Example icon at small sizeSmall Icon16px
Example icon at extra-small sizeExtra-small Icon12px

WARNING

x-small icon size is only intended for use in certain special cases. Most components should use Icons in small or medium size.

Usage

Props

Prop nameDescriptionTypeDefault
icon(required)The SVG path or an object containing that path plus other data.Icon
iconLabelAccessible label for the icon. If not included, the icon will be hidden from screen readers via aria-hidden="true". Browsers also display this label as a tooltip when the user hovers over the icon. Note that this label is not rendered as visible text next to the icon.string''
langExplicitly set the language code to use for the icon. See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/lang. Defaults to the lang attribute of the nearest ancestor at mount time.string|nullnull
dirExplicitly set the direction to use for the icon. See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dir. Defaults to the computed direction at mount time.HTMLDirection|nullnull
sizeSpecify icon size by choosing one of several pre-defined size options. See the type documentation for supported size options. The medium size is used by default if no size prop is provided.IconSize'medium'

Events

Event namePropertiesDescription
click

CSS-only version

You can use icons in a no-JavaScript context via a the CSS icon Less mixin provided by the Codex library. To use this mixin, import the mixin file and apply .cdx-mixin-css-icon() to an empty <span> element. The parameters of the mixin are as follows:

Param nameDescriptionDefault
@param-icon (required)The icon to use, in the form of a Less variable. These variables are also provided by the mixin file. The syntax for the Less variable version of an icon name is @cdx-icon-icon-name, e.g. @cdx-icon-info-filled. See the list of all icons for icon names.
@param-fill-colorThe hex code of the fill color of the icon@color-base
@param-size-iconThe icon size@size-icon-medium
@param-is-button-iconWhether the icon is inside of a <button> elementfalse

WARNING

Before importing the css-icon mixin, you must first import the design tokens. If you don't, you will get errors that look like variable @color-base is undefined.

TIP

Visit the Button docs for details on using CSS icons within buttons.

Code

Map pin

Icon color

Use the second parameter of the .cdx-mixin-css-icon() mixin, @param-fill-color, to apply a hex code as the SVG fill color.

Delete

Icon sizes

Use the third parameter of the .cdx-mixin-css-icon() mixin, @param-size-icon, to use one of the pre-defined size options (@size-icon-medium, @size-icon-small, or @size-icon-x-small).

Bookmark (medium)

Bell (small)

Arrow next (extra-small)

Bidirectionality

The CSS icon mixin supports icons that differ between the left-to-right (LTR) and right-to-left (RTL) reading directions. To take advantage of this behavior, in RTL contexts, one of the following is required:

  • A dir="rtl" attribute set on the <html> element.
  • A dir="rtl" attribute set directly on the icon span.

WARNING

In RTL contexts, ensure that a dir="rtl" attribute is set either on the <html> element or on the icon element itself.

Article (LTR)

Article (RTL)

Language support

The CSS-only icons mixin supports icons with language-specific variants.

Strikethrough (German)

Strikethrough (English)

Strikethrough (Finnish)