Skip to main content

Button

Buttons enable a user to initiate a specific action.

Code documentation

Web

Anatomy

The button component is made up of four elements.

  1. Container
  2. Icon
  3. Label
  4. Progress
Anatomy diagram numbering four elements of a button.

Variants

Label

The label conveys the button's action. Keep button labels concise and action-driven.

A button expands to fit the label text.

Icon

An icon can be included alongside a label to provide additional visual context or by itself in compact layouts. Always ensure the icon's meaning is clear and compliments the text label.

One button includes an icon to the left of label and expands to fit both. A second button includes only an icon and is perfectly square.

Icon-based buttons should be selectively used to avoid unnecessary visual clutter. Additionally, they should include a tooltip to help clarify the meaning as well as provide relevant text to a screen reader or other assistive device.

Icon position

Icons can be placed on either side of the label with the left position being the default. Use left icons to emphasis a button’s meaning and right icons to imply a progression or directionality.

Two buttons include icons and labels. The left button positions the icon to the left of the label. The right button positions the icon to the right of the label.

Appearance

Primary

Primary buttons call attentions to the strongest call to action within a particular context or view. These should generally appear only once per container.

A button with a blue background and white label text

Secondary

Secondary buttons are the default button appearance and often used alongside a primary button to indicate a secondary action such as “Cancel.” They can also be used for most non-critical actions.

A button with a transparent background, blue border, and blue label text

Tertiary

Use tertiary buttons for less prominent or independent actions. Tertiary buttons can also be paired with a primary button when there are multiple calls to action.

A button with a transparent background and border and blue label text

Danger

Danger buttons convey destructive actions such as “Delete” or “Remove.” To avoid confusion, do not use danger buttons for any type of action other than a destructive one.

A button with a red background and white label text

Size

Buttons are available in small, medium, and large sizes.

Three button sizes are compared left-to-right: small, medium, and large.

Small

Use small buttons where vertical space is limited or when paired with other content that is similar in height.

Medium

The medium size is the default and used for most button instances.

Large

Use large buttons in limited cases where a button needs to pair with a larger element or have particular prominence. Typically, a large button should be limited to one per view.

Block

By default, a button’s width is dependent on the label and/or icon contained within it. However, a block button expands to fit the width of its surrounding container. Buttons can be set as a block variant at any size. Use when vertically stacking multiple calls to action in a container such as a card or dialog.

An expanded button with a left-positioned icon and label text fills an implied container

Behavior

States

Each button appearance has six available states: enabled, focus, hover, active, disabled, and pending. The pending state replaces the label and icon with a progress indicator to show that a process such as saving is taking place.

The primary button appearance includes enabled, focus, hover, active, disabled, and pending states.
Primary
The secondary button appearance includes enabled, focus, hover, active, disabled, and pending states.
Secondary
The tertiary button appearance includes enabled, focus, hover, active, disabled, and pending states.
Tertiary
The danger button appearance includes enabled, focus, hover, active, disabled, and pending states.
Danger