Button

A Button triggers an action when the user clicks or taps on it.

<cdx-button>Click me</cdx-button>

Name	Value
Props
action	default progressive destructive
weight	normal primary quiet
size	medium large
disabled
Slots
default
View
Reading direction	Left to right (LTR) Right to left (RTL)

Overview

When to use Button

Use the Button component when you want to trigger an action or toggle something in the user's current context.

Avoid using Button when:

• The action is to navigate the user to a new resource, which would take them away from the current context. In such cases, consider Link instead. Learn more about using links and buttons.
• You need to represent state-persistent user actions. In this case, use ToggleButton instead.

About Button

Button includes the following elements.

Label

Button labels should be as short as possible, with text that clearly states what action follows clicking the button (e.g. download, submit form, search).

Buttons labels should ideally be fewer than 38 characters in English, as translations average 42 characters. Logographic and Arabic-script languages are generally shorter, while Romance, some Germanic, Slavic, Austronesian, and others like Greek and Finnish tend to be longer, averaging 45–53 characters.

• Use descriptive, accessible verbs to encourage action. Concise & Accessible

• Write in sentence case, capitalising only the first word. Consistent

• Answer direct questions in titles or body copy using the same terminology. Clear

• Avoid using similar words for different actions. Clear

• Avoid verbs that imply visual or sensory abilities such as "see", or are idiomatic or vague. Accessible & Translatable

Icon (optional)

Icons simplify user recognition and provide the ability to shorten button labels to a minimum. When the Button includes a label, the icon is optional and should be used to add a clear visual reinforcement to the label. If the Button is icon-only, it should use a universally recognizable icon, such as the “edit” action.

• Ensure that icons used in buttons are relevant to the action they represent.
• Use icons only when they are clear and easily recognizable.

Examples

Button types

Button action

A Button can convey one of three action types.

1. Neutral
   Use neutral buttons for actions that are neutral or secondary in importance.
2. Progressive
   Use progressive buttons for actions that lead to the next step in the process.
3. Destructive
   Reserve destructive buttons for actions that involve removal or limitation, such as deleting a page or blocking a user. Avoid using them for actions like cancel buttons.

Button weight

A Button can convey one of three weight types.

1. Normal
   When designing a project, normal buttons are the default choice.
2. Primary
   Primary buttons signal the main action in a given view – a page or a dialog. As they should guide the user to the most important action (“call to action”), there should only be one primary button per view.
3. Quiet
   Use quiet buttons for an easily recognizable action that does not detract focus from the content. For example, the icon-only edit buttons alongside sections in article view on mobile Wikipedia.

NPM

<template>
	<div class="cdx-demo-button-types">
		<div class="cdx-demo-button-types__neutral">
			<cdx-button>
				Normal neutral
			</cdx-button>
			<cdx-button weight="quiet">
				Quiet neutral
			</cdx-button>
		</div>
		<div class="cdx-demo-button-types__progressive">
			<cdx-button action="progressive">
				Normal progressive
			</cdx-button>
			<cdx-button action="progressive" weight="primary">
				Primary progressive
			</cdx-button>
			<cdx-button action="progressive" weight="quiet">
				Quiet progressive
			</cdx-button>
		</div>
		<div class="cdx-demo-button-types__destructive">
			<cdx-button action="destructive">
				Normal destructive
			</cdx-button>
			<cdx-button action="destructive" weight="primary">
				Primary destructive
			</cdx-button>
			<cdx-button action="destructive" weight="quiet">
				Quiet destructive
			</cdx-button>
		</div>
	</div>
</template>

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

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

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

.cdx-demo-button-types {
	display: flex;
	flex-direction: column;
	gap: @spacing-100;

	> div {
		display: flex;
		gap: @spacing-50;
	}
}
</style>

MediaWiki

<template>
	<div class="cdx-demo-button-types">
		<div class="cdx-demo-button-types__neutral">
			<cdx-button>
				Normal neutral
			</cdx-button>
			<cdx-button weight="quiet">
				Quiet neutral
			</cdx-button>
		</div>
		<div class="cdx-demo-button-types__progressive">
			<cdx-button action="progressive">
				Normal progressive
			</cdx-button>
			<cdx-button action="progressive" weight="primary">
				Primary progressive
			</cdx-button>
			<cdx-button action="progressive" weight="quiet">
				Quiet progressive
			</cdx-button>
		</div>
		<div class="cdx-demo-button-types__destructive">
			<cdx-button action="destructive">
				Normal destructive
			</cdx-button>
			<cdx-button action="destructive" weight="primary">
				Primary destructive
			</cdx-button>
			<cdx-button action="destructive" weight="quiet">
				Quiet destructive
			</cdx-button>
		</div>
	</div>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxButton } = require( '@wikimedia/codex' );

module.exports = defineComponent( {
	name: 'ButtonTypes',
	components: { CdxButton }
} );
</script>

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

.cdx-demo-button-types {
	display: flex;
	flex-direction: column;
	gap: @spacing-100;

	> div {
		display: flex;
		gap: @spacing-50;
	}
}
</style>

With icon

Use an icon with the button label when you need to convey meaning through both textual and visual elements.

NPM

<template>
	<cdx-button @click="onClick">
		<cdx-icon :icon="cdxIconDownload" /> Download
	</cdx-button>
</template>

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

export default defineComponent( {
	name: 'ButtonWithIcon',
	components: {
		CdxButton,
		CdxIcon
	},
	setup() {
		function onClick() {
			// eslint-disable-next-line no-console
			console.log( 'click event emitted' );
		}

		return {
			cdxIconDownload,
			onClick
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-button @click="onClick">
		<cdx-icon :icon="cdxIconDownload"></cdx-icon> Download
	</cdx-button>
</template>

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

module.exports = defineComponent( {
	name: 'ButtonWithIcon',
	components: {
		CdxButton,
		CdxIcon
	},
	setup() {
		function onClick() {
			// eslint-disable-next-line no-console
			console.log( 'click event emitted' );
		}

		return {
			cdxIconDownload,
			onClick
		};
	}
} );
</script>

Icon-only button

Use an icon-only button for actions that can be universally recognized through the icon alone. For an icon-only Button, the label is visually hidden but available to assistive technology users.

WARNING

Due to the lack of descriptive text, icon-only buttons require one of the following attributes: aria-label or aria-hidden.

The attribute aria-label has to be used on icon-only buttons to be understandable by assistive technology users. Exceptions are buttons in component combinations, e.g. the button in the Combobox component, that are skipped by adding aria-hidden without negatively impacting the component's functionality.

NPM

<template>
	<cdx-button aria-label="Back" @click="onClick">
		<cdx-icon :icon="cdxIconEdit" />
	</cdx-button>
</template>

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

export default defineComponent( {
	name: 'IconOnlyButton',
	components: {
		CdxButton,
		CdxIcon
	},
	setup() {
		function onClick() {
			// eslint-disable-next-line no-console
			console.log( 'click event emitted' );
		}

		return {
			cdxIconEdit,
			onClick
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-button aria-label="Back" @click="onClick">
		<cdx-icon :icon="cdxIconEdit"></cdx-icon>
	</cdx-button>
</template>

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

module.exports = defineComponent( {
	name: 'IconOnlyButton',
	components: {
		CdxButton,
		CdxIcon
	},
	setup() {
		function onClick() {
			// eslint-disable-next-line no-console
			console.log( 'click event emitted' );
		}

		return {
			cdxIconEdit,
			onClick
		};
	}
} );
</script>

Disabled button

Buttons may be disabled, but disabled buttons should be used sparingly.

• Use disabled Buttons when they are related to a single input, therefore implying what must be completed to enable the Button.
• Avoid using disabled Buttons to prevent a user from attmepting to continue forward. Instead, rely on providing validation as a response to what might be incomplete or incorrect.

<button class="cdx-button" disabled>Disabled button</button>

Button sizes

Buttons can be medium or large size.

Most Buttons should use the medium size. The large size is intended only for accessibility purposes, such as making icon-only Buttons larger on touchscreens to increase the touch area.

By default, the width of a Button with text is determined by the width of the text until reaching a max-width. However, on mobile, Buttons should span the full-width of the container, except for icon-only Buttons, which will maintain their fixed square proportions.

Button size examples for all supported size values.

Size	Min-size	Text button	Icon-only button
Medium	32px
Large	44px

NPM

<template>
	<table class="cdx-demo-button-sizes">
		<caption>
			Button size examples for all supported <code>size</code> values.
		</caption>
		<thead>
			<th>Size</th>
			<th>Min-size</th>
			<th>Text button</th>
			<th>Icon-only button</th>
		</thead>
		<tr>
			<td>
				<span>Medium</span>
			</td>
			<td>
				<span>32px</span>
			</td>
			<td>
				<cdx-button @click="onClick">
					Medium button
				</cdx-button>
			</td>
			<td>
				<cdx-button aria-label="Medium button example" @click="onClick">
					<cdx-icon :icon="cdxIconBell" />
				</cdx-button>
			</td>
		</tr>
		<tr>
			<td>
				<span>Large</span>
			</td>
			<td>
				<span>44px</span>
			</td>
			<td>
				<cdx-button size="large" @click="onClick">
					Large button
				</cdx-button>
			</td>
			<td>
				<cdx-button
					aria-label="Large button example"
					size="large"
					@click="onClick"
				>
					<cdx-icon :icon="cdxIconBell" />
				</cdx-button>
			</td>
		</tr>
	</table>
</template>

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

export default defineComponent( {
	name: 'ButtonSizes',
	components: { CdxButton, CdxIcon },
	setup() {
		function onClick() {
			// eslint-disable-next-line no-console
			console.log( 'click event emitted' );
		}

		return {
			cdxIconBell,
			onClick
		};
	}
} );
</script>

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

.cdx-demo-button-sizes {
	table {
		width: @size-full;
	}

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

MediaWiki

<template>
	<table class="cdx-demo-button-sizes">
		<caption>
			Button size examples for all supported <code>size</code> values.
		</caption>
		<thead>
			<th>Size</th>
			<th>Min-size</th>
			<th>Text button</th>
			<th>Icon-only button</th>
		</thead>
		<tr>
			<td>
				<span>Medium</span>
			</td>
			<td>
				<span>32px</span>
			</td>
			<td>
				<cdx-button @click="onClick">
					Medium button
				</cdx-button>
			</td>
			<td>
				<cdx-button aria-label="Medium button example" @click="onClick">
					<cdx-icon :icon="cdxIconBell"></cdx-icon>
				</cdx-button>
			</td>
		</tr>
		<tr>
			<td>
				<span>Large</span>
			</td>
			<td>
				<span>44px</span>
			</td>
			<td>
				<cdx-button size="large" @click="onClick">
					Large button
				</cdx-button>
			</td>
			<td>
				<cdx-button
					aria-label="Large button example"
					size="large"
					@click="onClick"
				>
					<cdx-icon :icon="cdxIconBell"></cdx-icon>
				</cdx-button>
			</td>
		</tr>
	</table>
</template>

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

module.exports = defineComponent( {
	name: 'ButtonSizes',
	components: { CdxButton, CdxIcon },
	setup() {
		function onClick() {
			// eslint-disable-next-line no-console
			console.log( 'click event emitted' );
		}

		return {
			cdxIconBell,
			onClick
		};
	}
} );
</script>

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

.cdx-demo-button-sizes {
	table {
		width: @size-full;
	}

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

Developer notes

Set min-width manually on Buttons with extremely short labels Non-icon-only Buttons with text labels of only 1-2 characters in length may fall below size of the target area described above. If you are dealing with non-icon-only Buttons with extremely short labels, it is recommended to set a minimum width of: @min-size-interactive-pointer in your own CSS.

Technical implementation

Vue usage

Props

Prop name	Description	Type	Values	Default
action	The kind of action that will be taken on click.	ButtonAction	'default', 'progressive', 'destructive'	'default'
weight	Visual prominence of the button.	ButtonWeight	'normal', 'primary', 'quiet'	'normal'
size	Button size. Most buttons should use the default medium size. In rare cases the large size should be used, for example to make icon-only buttons larger on touchscreens.	ButtonSize	'medium', 'large'	'medium'

Events

Event name	Properties	Description
click

Slots

Name	Description	Bindings
default	Button content

CSS-only version

Markup structure

The CSS Button component uses the <button> element and the .cdx-button class.

<!-- Button element with CSS class(es). -->
<button class="cdx-button">Click me</button>

Button actions

There are three Button actions: default, progressive, and destructive. Use the following classes to apply these actions:

• Default: cdx-button--action-default (class can be omitted since this is the default)
• Progressive: cdx-button--action-progressive
• Destructive: cdx-button--action-destructive

<div>
  <button class="cdx-button cdx-button--action-default">Default button</button>
</div>
<div>
  <button class="cdx-button cdx-button--action-progressive">
    Progressive button
  </button>
</div>
<div>
  <button class="cdx-button cdx-button--action-destructive">
    Destructive button
  </button>
</div>

Button weights

There are three Button weights: normal, primary, and quiet. Use the following classes to apply these actions:

• Normal: cdx-button--weight-normal (class can be omitted since this is the default)
• Primary: cdx-button--weight-primary
• Quiet: cdx-button--weight-quiet

<div>
  <button class="cdx-button cdx-button--action-progressive">
    Progressive normal button
  </button>
</div>
<div>
  <button
    class="cdx-button cdx-button--action-progressive cdx-button--weight-primary"
  >
    Progressive primary button
  </button>
</div>
<div>
  <button
    class="cdx-button cdx-button--action-progressive cdx-button--weight-quiet"
  >
    Progressive quiet button
  </button>
</div>

Disabled

Add the disabled attribute to the <button> element to get a disabled element with appropriate styles.

<button class="cdx-button" disabled>Disabled button</button>

With CSS icon

You can use CSS icons within button content. To set up an icon within a CSS-only button, do the following.

1. Add an empty span inside the button before the label with the class cdx-button__icon.
2. Use the .cdx-mixin-css-icon() mixin with the @param-is-button-icon parameter set to true.

Note that in Firefox version 52 and below, full color support for icons inside CSS-only buttons is not available, and the icon will fall back to a single color.

WARNING

Be sure to add aria-hidden="true" to the icon element to hide it from assistive technology.

<button class="cdx-button">
  <span
    class="cdx-button__icon cdx-demo-css-icon--arrow-previous"
    aria-hidden="true"
  ></span>
  Go back
</button>

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--arrow-previous {
  .cdx-mixin-css-icon( @cdx-icon-arrow-previous, @param-is-button-icon: true );
}

MediaWiki

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

.cdx-demo-css-icon--arrow-previous {
  .cdx-mixin-css-icon( @cdx-icon-arrow-previous, @param-is-button-icon: true );
}

Icon-only Button

Add the cdx-button--icon-only class for an icon-only Button.

WARNING

Be sure to add an aria-label attribute to the button element so it can be understandable to screen reader users.

<button class="cdx-button cdx-button--icon-only" aria-label="Back">
  <span class="cdx-button__icon cdx-demo-css-icon--arrow-previous"></span>
</button>

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--arrow-previous {
  .cdx-mixin-css-icon( @cdx-icon-arrow-previous, @param-is-button-icon: true );
}

MediaWiki

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

.cdx-demo-css-icon--arrow-previous {
  .cdx-mixin-css-icon( @cdx-icon-arrow-previous, @param-is-button-icon: true );
}

Button sizes

There are two Button sizes: medium and large. Most Buttons should use the medium size. The large size is intended only for accessibility purposes, such as making icon-only Buttons larger on small screens to increase the touch area.

Use the following classes to apply these actions:

• Medium: cdx-button--size-medium (class can be omitted since this is the default)
• Large: cdx-button--size-large

<div>
  <button class="cdx-button cdx-button--icon-only" aria-label="Back">
    <span class="cdx-button__icon cdx-demo-css-icon--bell"></span>
  </button>
</div>
<div>
  <button
    class="cdx-button cdx-button--icon-only cdx-button--size-large"
    aria-label="Back"
  >
    <span class="cdx-button__icon cdx-demo-css-icon--bell"></span>
  </button>
</div>

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--bell {
  .cdx-mixin-css-icon( @cdx-icon-bell, @param-is-button-icon: true );
}

MediaWiki

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

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

Link buttons and other elements

DANGER

Do not do this unless you absolutely have to. Use a <button> element styled like a button for an action, and use an <a> element styled like a link for navigation.

There are rare occasions where an inline element other than <button> needs to be styled to look like a button. To achieve this, add the following classes to your inline element:

• The classes detailed above: cdx-button, plus any other classes needed for action, weight, or size
• cdx-button--fake-button
• Either cdx-button--fake-button--enabled for an enabled button or cdx-button--fake-button--disabled for a disabled button. You must include one of these classes to get the proper button styles.

If your element behaves like a button (triggering an action or event), you should also add role="button" to the element if that role is allowed. See the ARIA Authoring Practices Guide on buttons for more information.

Progressive link button

<a
  class="cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--action-progressive"
  href="#"
>
  Progressive link button
</a>

Keyboard navigation

Key	Function
Enter / Space	If the focus is placed on the Button, it activates the Button.