Skip to content
On this page
You're viewing the docs for the main branch of Codex, which may contain features that have not been released yet. Codex users should visit the official docs.

Button

A control that can be pressed to trigger an action.

Demos

Configurable

NameValue
Props
action
weight
size
disabled
Slots
default
View
Reading direction

Default

Button actions

There are three button actions: default, progressive, and destructive.

Button weights

There are three button weights: normal, primary, and quiet.

Disabled

Add the disabled attribute for a disabled button.

With icon

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.

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.

Button size examples for all supported size values.
SizeMin-sizeText buttonIcon-only button
Medium32px
Large44px

Usage

Props

Prop nameDescriptionTypeValuesDefault
actionThe kind of action that will be taken on click.ButtonAction'default', 'progressive', 'destructive''default'
weightVisual prominence of the button.ButtonWeight'normal', 'primary', 'quiet''normal'
sizeButton 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 namePropertiesDescription
click

Slots

NameDescriptionBindings
defaultButton content

CSS-only version

Markup structure

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

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

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

Disabled

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

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 screen readers.

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

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.