Icon β
An Icon is a graphical representation of an idea.
Label
Name | Value |
---|---|
View | |
Reading direction |
Overview β
When to use Icon β
Icons are used to give the user additional context for understanding the interface. This component can be used inside other components, like a Button.
Codex contains a list of icons. Read more about how to use and create Codex icons.
About Icon β
Size β
Icons can be one of three sizes.
- By default, Icons use
@size-125
(equivalent to20px
in the default Codex theme) known as medium. - In elements with a smaller height, Icons should use
@size-100
(equivalent to16px
in the default Codex theme) known as small. - In specific cases, Icons should use
@size-75
(equivalent to12px
in the default Codex theme) known as x-small.
Color β
- By default, icons use
@color-base
. - Decorative icons should use
@color-subtle
. - Icons in a placeholder state should use
@color-placeholder
. - Status-conveying icons should use their associated status color, either
@color-notice
,@color-error
,@color-warning
, or@color-success
. - Icons as a part of an action or link inherit the color of the accompanying label.
Examples β
Basic usage β
Icon can be used inside other components, like Button. Note that the icon will inherit the text color of that componentβfor instance, in a destructive primary button, the icon is white, like the button label.
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.
Medium Icon | 20px | |
Small Icon | 16px | |
Extra-small Icon | 12px |
WARNING
x-small
Icon size is only intended for use in certain special cases. Most components should use Icons in small
or medium
size.
Technical implementation β
Vue usage β
β
Props β
Prop name | Description | Type | Default |
---|---|---|---|
icon (required) | The SVG path or an object containing that path plus other data. | Icon | |
iconLabel | Accessible 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 | '' |
lang | Explicitly 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|null | null |
dir | Explicitly 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|null | null |
size | Specify 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' |
CSS-only version β
You can use icons in a no-JavaScript context via 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 name | Description | Default |
---|---|---|
@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 . Visit the list of all icons for icon names. To use a custom icon, set this to 'none' , check how to use a custom icon below. | |
@param-fill-color | The hex code of the fill color of the icon | @color-base |
@param-size-icon | The icon size | @size-icon-medium |
@param-is-button-icon | Whether the icon is inside of a <button> element | false |
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)
Custom icon β
To use a custom icon:
- Set the first parameter of the
.cdx-mixin-css-icon()
mixin to'none'
- Set
mask-image
and-webkit-mask-image
to a URL that points to the icon image (this can be a data URL)
WARNING
You must set both mask-image
and -webkit-mask-image
, because many browsers only respect the latter. This may happen automatically if you use a tool like Autoprefixer.
Custom icon