Usage ​

This page describes how to use the different NPM packages available as part of Codex. Read more about the different packages and their contents.

Installation ​

Install the following packages from NPM:

• @wikimedia/codex
• @wikimedia/codex-design-tokens
• @wikimedia/codex-icons

npm install --save-dev @wikimedia/codex @wikimedia/codex-design-tokens @wikimedia/codex-icons

Some projects may not need the icons package, but most do.

You will also need to install Vue.js in order to use Codex Vue components.

Using components ​

Vue 3 components ​

Import the components you need from the @wikimedia/codex package, and pass them into the components setting of your component:

<template>
	<div>
		<cdx-button action="progressive" weight="primary">
			Click me!
		</cdx-button>
	</div>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxButton } from '@wikimedia/codex';

export default defineComponent( {
	components: {
		CdxButton
	},
	// ...
} );
</script>

Find documentation for individual components in the “Components” section. For example, the documentation for CdxButton is at “Button” page.

CSS-only components ​

Output the HTML of the component with the appropriate CSS classes (see the component page's "CSS-only version" section for details, e.g. for the CSS-only Button). Load codex.style.css or codex.style-rtl.css depending on the reading direction of the page (read more about Codex CSS files and bidirectionality support).

<button class="cdx-button cdx-button--action-progressive cdx-button--weight-primary">
  Save
</button>

Using icons ​

For more information about icons, see the icon documentation, and the list of all icons.

Vue 3 icons ​

Import the icons you need from the @wikimedia/codex-icons package, put them in your component's data, then pass them to a Codex component as a prop:

<template>
	<div>
		<cdx-button action="destructive">
			<cdx-icon :icon="cdxIconTrash" /> Delete this item
		</cdx-button>
	</div>
</template>

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

export default defineComponent( {
	components: {
		CdxButton,
		CdxIcon
	},
	data: () => ( {
		cdxIconTrash
	} ),
	// ...
} );
</script>

For more information about the Icon component, see the Icon demo page.

CSS-only icons ​

Import Codex design tokens and the CSS icon mixin. Then, apply the mixin to an empty <span> element.

<!-- Standalone icon. -->
<span class="my-icon-class--map-pin"></span>
<button class="cdx-button cdx-button--action-destructive">
	<!-- Icon inside a button. -->
	<span class="my-icon-class--trash"></span>
	Delete
</button>

@import (reference) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';
@import (reference) '@wikimedia/codex/mixins/css-icon.less';

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

	&--trash {
		.cdx-mixin-css-icon( @cdx-icon-trash, @param-is-button-icon: true );
	}
}

For more information about the CSS-only icon, see the Icon demo page.

Using design tokens ​

Import the appropriate design tokens theme file in your CSS, Less, or SCSS code to access Codex design tokens.

Sample CSS usage ​

@import '@wikimedia/codex-design-tokens/theme-wikimedia-ui.css';

.my-custom-element {
	background-color: var( --background-color-interactive );
	padding: var( --spacing-25 ) var( --spacing-50 );
}

Sample Less usage ​

@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';

.my-custom-element {
	background-color: @background-color-interactive;
	padding: @spacing-25 @spacing-50;
}

For more information about design tokens, see the design tokens overview and design tokens demo pages (e.g. Color).

Using Less mixins ​

Import the following in your Less code:

1. The appropriate design tokens theme file (this must be imported first for all Less mixins)
2. The Less mixin you want to use

@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';
@import ( reference ) '@wikimedia/codex/mixins/link.less';

.my-custom-link {
	.cdx-mixin-link();
}

Versioning ​

Codex follows the semantic versioning standard. The current version is 1.0.0. Subsequent versions will continue to be numbered 0.x.y, until Codex is stable and mature enough to warrant a 1.0.0 release. If a release contains breaking changes, the minor version number (the x in 0.x.y) will be incremented, and the breaking changes will be clearly documented in CHANGELOG.md.

Bidirectionality support ​

Codex has limited support for bidirectional text. It supports pages that are entirely in a left-to-right (LTR) script, or pages that are entirely in a right-to-left (RTL) script. It does not support pages with a mix of LTR and RTL content, or pages whose directionality changes at runtime, except in some special cases.

Codex provides two direction-specific stylesheets. On LTR pages, use codex.style.css; on RTL pages, use codex.style-rtl.css. Codex does not provide a single stylesheet using attribute selectors like [dir='rtl'] to set the right style for each direction, because of the significant limitations of this approach.

Some Codex components detect the direction of the surrounding content, and adjust their behavior accordingly, for example in how they respond to the left and right arrow keys. Icons also adjust to the surrounding direction. For more information on how bidirectionality is handled for icons, see the icon documentation.

For more information on this topic, see the developer documentation on bidirectionality.