Button #
A control that can be pressed to trigger an action.
Demos #
Configurable #
<cdx-button>Click me</cdx-button>
Name | Value |
---|---|
Props | |
action | |
weight | |
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>
<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';
export default defineComponent( {
name: 'ButtonWithIcon',
components: {
CdxButton,
CdxIcon
},
setup() {
return {
cdxIconArrowPrevious
};
}
} );
</script>
<template>
<cdx-button weight="quiet">
<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';
export default defineComponent( {
name: 'QuietButtonWithIcon',
components: {
CdxButton,
CdxIcon
},
setup() {
return {
cdxIconDownload
};
}
} );
</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">
<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';
export default defineComponent( {
name: 'IconOnlyButton',
components: {
CdxButton,
CdxIcon
},
setup() {
return {
cdxIconPrevious
};
}
} );
</script>
<template>
<cdx-button weight="quiet" aria-label="Help">
<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';
export default defineComponent( {
name: 'QuietIconOnlyButton',
components: {
CdxButton,
CdxIcon
},
setup() {
return {
cdxIconHelp
};
}
} );
</script>
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' |
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-icon
parameter 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);
}