Icon β
An Icon is a graphical representation of an idea.
Name | Value |
---|---|
Props | |
icon | |
size | |
language | |
View | |
Reading direction | |
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information. |
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.
Icon colors β
All icons are monochrome, meaning the entire icon is the same color. By default, Icon uses the base color (#202122
), but this can be overridden by changing the color
property of the .cdx-icon
element in CSS.
Success!
Developer notes
Note that the SVG inherits the Icon color
by applying fill: currentColor
. Some components style their icons to match the surrounding text color. For example, Button features red icons matching the red (#bf3c2c
) text in its destructive variant.
Internationalization β
Many icons, like cdxIconJournal
, have different versions for left-to-right (LTR) and right-to-left (RTL) contexts. The Icon component automatically detects the direction of its environment, and chooses the correct icon accordingly. For example, if the journal icon appears on a page that is RTL, or inside of a <div dir="rtl">
tag, the RTL version of the icon will be displayed.
Name | Value |
---|---|
View | |
Reading direction |
Similarly, some icons, like cdxIconBold
have different versions for different languages. The icon component also automatically detects the language of its environment, so if for example the bold icon appears on a page that has <html lang="fr">
at the root, or inside of a <p lang="fr">
, the French version of the icon will be displayed.
Default
English
French
Arabic
Name | Value |
---|---|
View | |
Reading direction |
Developer notes
The automatic direction and language detection feature has limitations. It only detects the direction and language of the surrounding context when the icon component is initially mounted. If the surrounding context changes later, for example because the lang
or dir
attribute on the parent/ancestor is changed, the icon will not notice these changes and will not update to reflect them.
If you run into this limitation, or if the automatic direction/language detection isn't working for other reasons, you can set the direction and/or language explicitly through the dir
and lang
props:
Bold icon in German: <cdx-icon :icon="cdxIconBold" lang="de" />
Journal icon in RTL: <cdx-icon :icon="cdxIconJournal" dir="rtl" />
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