Icon

An Icon is a graphical representation of an idea.

Label

NPM

<template>
	<p>
		<cdx-icon :icon="cdxIconTag" />
		Label
	</p>
</template>

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

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

MediaWiki

<template>
	<p>
		<cdx-icon :icon="cdxIconTag"></cdx-icon>
		Label
	</p>
</template>

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

module.exports = defineComponent( {
	name: 'SimpleIcon',
	components: { CdxIcon },
	setup() {
		return {
			cdxIconTag
		};
	}
} );
</script>

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

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 to 20px in the default Codex theme) known as medium.
• In elements with a smaller height, Icons should use @size-100 (equivalent to 16px in the default Codex theme) known as small.
• In specific cases, Icons should use @size-75 (equivalent to 12px 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.

NPM

<template>
	<cdx-button>
		<cdx-icon :icon="cdxIconNext" />
		Next
	</cdx-button>
	<br><br>
	<cdx-button weight="primary" action="destructive">
		<cdx-icon :icon="cdxIconTrash" />
		Remove
	</cdx-button>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxIcon, CdxButton } from '@wikimedia/codex';
import { cdxIconNext, cdxIconTrash } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'IconInButton',
	components: { CdxIcon, CdxButton },
	setup() {
		return {
			cdxIconNext,
			cdxIconTrash
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-button>
		<cdx-icon :icon="cdxIconNext"></cdx-icon>
		Next
	</cdx-button>
	<br><br>
	<cdx-button weight="primary" action="destructive">
		<cdx-icon :icon="cdxIconTrash"></cdx-icon>
		Remove
	</cdx-button>
</template>

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

module.exports = defineComponent( {
	name: 'IconInButton',
	components: { CdxIcon, CdxButton },
	setup() {
		return {
			cdxIconNext,
			cdxIconTrash
		};
	}
} );
</script>

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

NPM

<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>

MediaWiki

<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' );

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.

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. See the list of all icons for icon names. To use a custom icon, set this to 'none', see 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

<p>
  <span class="cdx-demo-css-icon--code"></span>
  Code
</p>
<p>
  <span class="cdx-demo-css-icon--map-pin"></span>
  Map pin
</p>

NPM

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon {
  &--code {
    .cdx-mixin-css-icon( @cdx-icon-code );
  }

  &--map-pin {
    .cdx-mixin-css-icon( @cdx-icon-map-pin );
  }
}

MediaWiki

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon {
  &--code {
    .cdx-mixin-css-icon( @cdx-icon-code );
  }

  &--map-pin {
    .cdx-mixin-css-icon( @cdx-icon-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

<p>
  <span class="cdx-demo-css-icon--trash"></span>
  Delete
</p>

NPM

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon--trash {
  .cdx-mixin-css-icon( @cdx-icon-trash, @color-destructive );
}

MediaWiki

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon--trash {
  .cdx-mixin-css-icon( @cdx-icon-trash, @color-destructive );
}

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)

<p>
  <span class="cdx-demo-css-icon--bookmark"></span>
  Bookmark (medium)
</p>
<p>
  <span class="cdx-demo-css-icon--bell"></span>
  Bell (small)
</p>
<p>
  <span class="cdx-demo-css-icon--arrow-next"></span>
  Arrow next (extra-small)
</p>

NPM

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon {
  &--bookmark {
    // No size parameter added, so default size of medium will be used.
    .cdx-mixin-css-icon( @cdx-icon-bookmark );
  }

  &--bell {
    // Size parameter included via a named parameter.
    .cdx-mixin-css-icon( @cdx-icon-bell, @param-size-icon: @size-icon-small );
  }

  &--arrow-next {
    .cdx-mixin-css-icon( @cdx-icon-arrow-next, @param-size-icon: @size-icon-x-small );
  }
}

MediaWiki

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon {
  &--bookmark {
    // No size parameter added, so default size of medium will be used.
    .cdx-mixin-css-icon( @cdx-icon-bookmark );
  }

  &--bell {
    // Size parameter included via a named parameter.
    .cdx-mixin-css-icon( @cdx-icon-bell, @param-size-icon: @size-icon-small );
  }

  &--arrow-next {
    .cdx-mixin-css-icon( @cdx-icon-arrow-next, @param-size-icon: @size-icon-x-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)

<p>
  <span dir="ltr" class="cdx-demo-css-icon cdx-demo-css-icon--article"></span>
  Article (LTR)
</p>
<p>
  <span dir="rtl" class="cdx-demo-css-icon cdx-demo-css-icon--article"></span>
  Article (RTL)
</p>

NPM

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon {
  &--article {
    .cdx-mixin-css-icon( @cdx-icon-article );
  }
}

MediaWiki

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon {
  &--article {
    .cdx-mixin-css-icon( @cdx-icon-article );
  }
}

Language support

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

Strikethrough (German)

Strikethrough (English)

Strikethrough (Finnish)

<p lang="de">
  <span class="cdx-demo-css-icon cdx-demo-css-icon--strikethrough"></span>
  Strikethrough (German)
</p>
<p lang="en">
  <span class="cdx-demo-css-icon cdx-demo-css-icon--strikethrough"></span>
  Strikethrough (English)
</p>
<p lang="fi">
  <span class="cdx-demo-css-icon cdx-demo-css-icon--strikethrough"></span>
  Strikethrough (Finnish)
</p>

NPM

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon {
  &--strikethrough {
    .cdx-mixin-css-icon( @cdx-icon-strikethrough );
  }
}

MediaWiki

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon {
  &--strikethrough {
    .cdx-mixin-css-icon( @cdx-icon-strikethrough );
  }
}

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

<p>
  <span class="cdx-demo-css-icon--custom"></span>
  Custom icon
</p>

NPM

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon--custom {
  .cdx-mixin-css-icon( "none", @color-progressive );
  /* stylelint-disable-next-line plugin/no-unsupported-browser-features,function-url-quotes */
  -webkit-mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20"><mask id="inner"><circle cx="10" cy="10" r="10" fill="white"/><circle cx="10" cy="10" r="6" fill="black"/></mask><circle cx="10" cy="10" r="10" fill="black" mask="url(%23inner)"/></svg>');
  /* stylelint-disable-next-line plugin/no-unsupported-browser-features,function-url-quotes */
  mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20"><mask id="inner"><circle cx="10" cy="10" r="10" fill="white"/><circle cx="10" cy="10" r="6" fill="black"/></mask><circle cx="10" cy="10" r="10" fill="black" mask="url(%23inner)"/></svg>');
}

MediaWiki

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon--custom {
  .cdx-mixin-css-icon( "none", @color-progressive );
  /* stylelint-disable-next-line plugin/no-unsupported-browser-features,function-url-quotes */
  -webkit-mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20"><mask id="inner"><circle cx="10" cy="10" r="10" fill="white"/><circle cx="10" cy="10" r="6" fill="black"/></mask><circle cx="10" cy="10" r="10" fill="black" mask="url(%23inner)"/></svg>');
  /* stylelint-disable-next-line plugin/no-unsupported-browser-features,function-url-quotes */
  mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20"><mask id="inner"><circle cx="10" cy="10" r="10" fill="white"/><circle cx="10" cy="10" r="6" fill="black"/></mask><circle cx="10" cy="10" r="10" fill="black" mask="url(%23inner)"/></svg>');
}