Skip to content
On this page

Button

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

Guidelines

Using buttons

Buttons must contain a label and can also include an icon. For icon-only buttons, the label is visually hidden but available to assistive technology users.

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

Avoid using buttons 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.[1]
  • You need to represent state-persistent user actions. In this case, use ToggleButton instead.

Example of Codex Buttons in three different variants:
progressive, destructive, and neutral.

Specifications

The button styles distinguish types of buttons and each button’s state (e.g. hover, active, focussed) in accessible color variations.

Specification of Button.

  1. Icon (optional)
    Icons simplify user recognition and provide the ability to shorten button labels to a minimum.
  2. 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).

When using buttons, consider the size of their target area. Make sure that the associated active touch area is at least 44 x 44 dp. Otherwise users may fail to hit the active area, for example due to motor disabilities.

Refer to the Button component in Codex Figma.

Types

Button content

Depending on the content of the button, there are the following types:

  1. Text with icon
    It combines descriptive text with a reinforcing icon. It's suitable when you need to convey meaning through both textual and visual elements.
  2. Text-only
    It contains only text for simplicity. It is suitable for actions that do not require or benefit from an accompanying icon, or when the icon would not effectively reinforce the meaning of the text.
  3. Icon-only
    It uses an icon alone to create visual impact. It is suitable for actions that can be universally recognized through the icon alone, such as the “edit” action.

Example of button content: text with icon, text-only and icon-only.

Button action or variant (“flavor”)

There three type of buttons based on the type of action they convey:

  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.

Example of button action: progressive, destructive, and neutral.

Button weight

Buttons can be categorized into three types based on their weight and their significance in their respective contexts:

Primary buttons

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.

Variants of primary buttons: progressive and destructive.

They come in two variants (“flavors”):

  1. Progressive: Use progressive buttons for actions that lead to the next step in the process.
  2. Destructive: Use destructive buttons for actions that remove or limit, such as deleting a page or blocking a user. Don't use it for actions such as cancel buttons.
Normal buttons

When designing a project, normal framed buttons are the default choice. Quiet, frameless buttons (read next section) should only be used in views, where normal buttons need to be further visually de-emphasized, see below.

Variants of normal buttons: neutral, progressive and destructive.

Normal buttons have three variants (“flavors”):

  1. Neutral
  2. Progressive
  3. Destructive
Quiet buttons (“frameless”)

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.[2]They still feature minimal target sizes and states to provide the user clear interaction feedback. Normal (framed) buttons are the default choice for simplified recognition.

Variants of quiet buttons: neutral, progressive and destructive.

Quiet buttons have three variants (“flavors”):

  1. Neutral
  2. Progressive
  3. Destructive

Interaction states

Buttons have the following visually separate states:

Neutral buttons

Interaction states of the Neutral Button (both normal and quiet buttons): default,
hover, active, focus, and disabled.

Progressive buttons

Interaction states of the Progressive Button (primary, normal,
and quiet buttons): default, hover, active, focus, and disabled.

Destructive buttons

Interaction states of the Destructive Button (primary, normal,
and quiet buttons): default, hover, active, focus, and disabled.

  1. Default
  2. Hover
  3. Active
  4. Focus
  5. Disabled

Accessibility note: The disabled state does not meet our minimum color contrast rules. WCAG 2.1 states that “…part[s] of an inactive user interface component […] have no contrast requirement”.[3]
Provide sufficient information in a disabled element’s context, so the user can understand what is disabled and how to enable it (if applicable).

References

  1. “Links vs. Buttons in Modern Web Applications” by Marcy Sutton
  2. Mobile English Wikipedia: Button (computing) article with exemplified quiet edit buttons
  3. Web Content Accessibility Guidelines (WCAG) 2.1 – Success Criterion 1.4.3 Contrast (Minimum)

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

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

Vue 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 assistive technology.

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.

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.