Icon ​

An Icon is a graphical representation of an idea.

Guidelines ​

Using icons ​

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.

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 ​

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 ​

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

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

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

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.

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

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

Vue usage ​

Props ​

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:

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

// 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 );
  }
}

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

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

// 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 );
}

@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).

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

// 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 );
  }
}

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

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

// 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 );
  }
}

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

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

// 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 );
  }
}

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

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