CodexButton
A control that can be pressed to trigger an action.
Demos
Configurable
<cdx-button>Click me</cdx-button>| Name | Value |
|---|---|
| Props | |
action | |
weight | |
size | |
disabled | |
| Slots | |
default | |
| View | |
Reading direction | |
Default
<cdx-button>Click me</cdx-button>Button actions
There are three button actions: default, progressive, and destructive.
<div>
<cdx-button>Default button</cdx-button>
</div>
<div>
<cdx-button action="progressive">Progressive button</cdx-button>
</div>
<div>
<cdx-button action="destructive">Destructive button</cdx-button>
</div>Button weights
There are three button weights: normal, primary, and quiet.
<div>
<cdx-button action="progressive">
Normal progressive button
</cdx-button>
</div>
<div>
<cdx-button action="progressive" weight="primary">
Primary progressive button
</cdx-button>
</div>
<div>
<cdx-button action="progressive" weight="quiet">
Quiet progressive button
</cdx-button>
</div>Disabled
Add the disabled attribute for a disabled button.
<cdx-button disabled>Disabled button</cdx-button>With icon
<template>
<cdx-button @click="onClick">
<cdx-icon :icon="cdxIconArrowPrevious" /> Go back
</cdx-button>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxButton, CdxIcon } from '@wikimedia/codex';
import { cdxIconArrowPrevious } from '@wikimedia/codex-icons';
import getEventLogger from '../../../src/utils/getEventLogger';
export default defineComponent( {
name: 'ButtonWithIcon',
components: {
CdxButton,
CdxIcon
},
setup() {
const onClick = getEventLogger<Event>( 'click' );
return {
cdxIconArrowPrevious,
onClick
};
}
} );
</script><template>
<cdx-button weight="quiet" @click="onClick">
<cdx-icon :icon="cdxIconDownload" /> Download
</cdx-button>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxButton, CdxIcon } from '@wikimedia/codex';
import { cdxIconDownload } from '@wikimedia/codex-icons';
import getEventLogger from '../../../src/utils/getEventLogger';
export default defineComponent( {
name: 'QuietButtonWithIcon',
components: {
CdxButton,
CdxIcon
},
setup() {
const onClick = getEventLogger<Event>( 'click' );
return {
cdxIconDownload,
onClick
};
}
} );
</script>Icon-only button
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 screen reader 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.
<template>
<cdx-button aria-label="Back" @click="onClick">
<cdx-icon :icon="cdxIconPrevious" />
</cdx-button>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxButton, CdxIcon } from '@wikimedia/codex';
import { cdxIconPrevious } from '@wikimedia/codex-icons';
import getEventLogger from '../../../src/utils/getEventLogger';
export default defineComponent( {
name: 'IconOnlyButton',
components: {
CdxButton,
CdxIcon
},
setup() {
const onClick = getEventLogger<Event>( 'click' );
return {
cdxIconPrevious,
onClick
};
}
} );
</script><template>
<cdx-button
weight="quiet"
aria-label="Help"
@click="onClick"
>
<cdx-icon :icon="cdxIconHelp" />
</cdx-button>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxButton, CdxIcon } from '@wikimedia/codex';
import { cdxIconHelp } from '@wikimedia/codex-icons';
import getEventLogger from '../../../src/utils/getEventLogger';
export default defineComponent( {
name: 'QuietIconOnlyButton',
components: {
CdxButton,
CdxIcon
},
setup() {
const onClick = getEventLogger<Event>( 'click' );
return {
cdxIconHelp,
onClick
};
}
} );
</script>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 touchscreens to increase the touch area.
| Medium button | 32px | |
| Large button | 44px |
<template>
<table>
<caption>
Button size examples for all supported <code>size</code> values.
</caption>
<tr>
<th>
<cdx-button aria-label="Medium button example" @click="onClick">
<cdx-icon :icon="cdxIconBell" />
</cdx-button>
</th>
<td>
<span>Medium button</span>
</td>
<td>
<span>32px</span>
</td>
</tr>
<tr>
<th>
<cdx-button
aria-label="Large button example"
size="large"
@click="onClick"
>
<cdx-icon :icon="cdxIconBell" />
</cdx-button>
</th>
<td>
<span>Large button</span>
</td>
<td>
<span>44px</span>
</td>
</tr>
</table>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxButton, CdxIcon } from '@wikimedia/codex';
import { cdxIconBell } from '@wikimedia/codex-icons';
import getEventLogger from '../../../src/utils/getEventLogger';
export default defineComponent( {
name: 'ButtonSizes',
components: { CdxButton, CdxIcon },
setup() {
const onClick = getEventLogger<Event>( 'click' );
return {
cdxIconBell,
onClick
};
}
} );
</script>
<style lang="less" scoped>
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';
table {
width: @size-full;
}
caption {
margin-top: @spacing-25;
/* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
text-align: left;
/* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
caption-side: bottom;
}
</style>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:
- Add an empty span inside the button before the label with the class
cdx-button__icon. - Use the
.cdx-mixin-css-icon()mixin with the@param-is-button-iconparameter set totrue.
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 screen readers.
<button class="cdx-button">
<span
class="cdx-button__icon cdx-demo-css-icon--arrow-previous"
aria-hidden="true"
></span>
Go back
</button>// 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);
}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>// 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);
}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>// 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);
}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--enabledfor an enabled button orcdx-button--fake-button--disabledfor a disabled button. You must include one of these classes to get the proper button styles.
<a
class="cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--action-destructive cdx-button--weight-primary"
href="#"
>
Primary destructive link button
</a><label
class="cdx-button cdx-button--fake-button cdx-button--fake-button--enabled"
>
<span class="cdx-button__icon cdx-demo-css-icon--user-avatar"></span>
Label button
</label>// 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--user-avatar {
.cdx-mixin-css-icon(@cdx-icon-user-avatar, @param-is-button-icon: true);
}