Icon

An Icon is a graphical representation of an idea. Icons are used to give the user additional context to aid in understanding the interface. This component can be used inside other components, like a Button.

Guidelines

Using icons

Codex contains a list of icons. Read more about how to use and create Codex icons.

Specifications

Size

Icon size can be 20px, 16px or 12px. Icon base size will be 20px, while 16px will be used for small icons. We will use 12px just for a limited set of specific use cases.

20px icons should be used by default size, including in elements with a min-height of 32px (like the start icon within the TextInput).
16px icons should be in elements with a height less than 32px (like the start icon within the InfoChip) or for controls in elements with a min-height of 32px (like the dropdown arrow’s icon in the Select).
12px icons will only be used for a small set of specific cases, like the external-link icon, or for controls in elements with a height less than 32px (like the remove buttons for chips in the ChipInput).

Color

Icons will always use Gray700 if used individually, and not as part of another component.

Icons used within other components inherit the color of the accompanying label.

Refer to the Icon component in Codex Figma.

Interaction states

Icons serve as both informative and decorative elements, so they do not inherently exhibit states on their own. Instead, an icon will adopt the state of the text or component it is placed within.

Demos

Simple icon

Label

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

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.
	Medium Icon	20px
	Small Icon	16px
	Extra-small Icon	12px

NPMMediaWiki

vue

<template>
	<table class="cdx-demo-icon-sizes">
		<caption>
			Icon size examples for all supported <code>size</code> values.
		</caption>
		<tr>
			<th>
				<cdx-icon
					:icon="cdxIconLogoWikimedia"
					size="medium"
					icon-label="Example icon at medium size"
				/>
			</th>
			<td>
				<span>Medium Icon</span>
			</td>
			<td>
				<span>20px</span>
			</td>
		</tr>
		<tr>
			<th>
				<cdx-icon
					:icon="cdxIconLogoWikimedia"
					size="small"
					icon-label="Example icon at small size"
				/>
			</th>
			<td>
				<span>Small Icon</span>
			</td>
			<td>
				<span>16px</span>
			</td>
		</tr>
		<tr>
			<th>
				<cdx-icon
					:icon="cdxIconLogoWikimedia"
					size="x-small"
					icon-label="Example icon at extra-small size"
				/>
			</th>
			<td>
				<span>Extra-small Icon</span>
			</td>
			<td>
				<span>12px</span>
			</td>
		</tr>
	</table>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxIcon } from '@wikimedia/codex';
import { cdxIconLogoWikimedia } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'IconSizes',
	components: { CdxIcon },
	setup() {
		return {
			cdxIconLogoWikimedia
		};
	}
} );
</script>

<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';

.cdx-demo-icon-sizes {
	width: @size-full;

	caption {
		margin-top: @spacing-25;
		text-align: left;
		caption-side: bottom;
	}
}
</style>

vue

<template>
	<table class="cdx-demo-icon-sizes">
		<caption>
			Icon size examples for all supported <code>size</code> values.
		</caption>
		<tr>
			<th>
				<cdx-icon
					:icon="cdxIconLogoWikimedia"
					size="medium"
					icon-label="Example icon at medium size"
				></cdx-icon>
			</th>
			<td>
				<span>Medium Icon</span>
			</td>
			<td>
				<span>20px</span>
			</td>
		</tr>
		<tr>
			<th>
				<cdx-icon
					:icon="cdxIconLogoWikimedia"
					size="small"
					icon-label="Example icon at small size"
				></cdx-icon>
			</th>
			<td>
				<span>Small Icon</span>
			</td>
			<td>
				<span>16px</span>
			</td>
		</tr>
		<tr>
			<th>
				<cdx-icon
					:icon="cdxIconLogoWikimedia"
					size="x-small"
					icon-label="Example icon at extra-small size"
				></cdx-icon>
			</th>
			<td>
				<span>Extra-small Icon</span>
			</td>
			<td>
				<span>12px</span>
			</td>
		</tr>
	</table>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxIcon } = require( '@wikimedia/codex' );
const { cdxIconLogoWikimedia } = require( './icons.json' );

// @vue/component
module.exports = defineComponent( {
	name: 'IconSizes',
	components: { CdxIcon },
	setup() {
		return {
			cdxIconLogoWikimedia
		};
	}
} );
</script>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-demo-icon-sizes {
	width: @size-full;

	caption {
		margin-top: @spacing-25;
		text-align: left;
		caption-side: bottom;
	}
}
</style>

WARNING

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

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 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 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`. See the list of all icons for icon names.
`@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)

Icon ​

Guidelines ​

Using icons ​

Specifications ​

Size ​

Color ​

Interaction states ​

Demos ​

Simple icon ​

Using icons in buttons ​

Icon sizes ​

Vue usage ​

Props ​

CSS-only version ​

Icon color ​

Icon sizes ​

Bidirectionality ​

Language support ​

Icon

Guidelines

Using icons

Specifications

Size

Color

Interaction states

Demos

Simple icon

Using icons in buttons

Icon sizes

Vue usage

Props

CSS-only version

Icon color

Icon sizes

Bidirectionality

Language support