Button

Overview#

Buttons allow users to take actions, and make choices, with a single click, tap or keypress. They are typically placed in:

  • Modals
  • Cards
  • Page headers

Design Guidelines#

Visual Style#

  • The standard button size is Size: default.

  • The standard link button size is Size: small.

  • Always use the disabled button state when buttons are pressed and are performing their actions.

  • Never wrap button text.

  • Never use icons in buttons. Except:

    • The icon type="down" in dropdowns.

    • The icon type="loading" in button loading states.

      button-usage-pattern-3

Icon only buttons#

Icon-only buttons are not advised, though may be used in cases where space is limited, such as on mobile. For usability and accessibility purposes in cases where you must use icon-only buttons:

  • Icons must be minimum 48px by 48px.
  • Icon buttons must be accompanied with title or aria text describing the intended action.
  • Icons should be filled, not outlined.

Dropdown buttons#

For dropdown buttons, see the dropdown documentation.

Hierarchy#

  • Pair primary buttons (high-emphasis) with default buttons (medium emphasis) and link buttons (low emphasis) to create a visual hierarchy.
  • When placing buttons next to each other, place high emphasis button to the right followed by the button with medium emphasis and so on.
  • Never use more than one primary button in a card header or page header.
  • For Save / Cancel scenarios, use the primary button for "save" and the default button for "cancel" - As per the design decision.

Placement#

  • Always place actions that impact the entire page in the page header.

  • Use buttons in page headers when the action:

    • Impacts the entire page (example: when the button launches a user into a new task flow).
    • Impacts all the information on a page (example: saving, deleting, exporting data represented by the entire page).
    • Is the most important action of a task or user flow.
    • Default, primary, danger and link buttons can be used in page headers.
  • Always place actions that impact a card in the card header or footer.

  • Avoid placing two primary buttons next to one another.

Behaviour#

  • Always launch a modal confirm action when a user clicks a danger button.
  • Always show a loading icon (icon type="loading") to the left of the button text when it takes more than 1 second to complete an action.

Editorial#

  • Button text should be clear and predictable. Users should be able to anticipate what happens when they click a button.
  • Always write button text in sentence case.
  • Always use the {verb} +{noun} format unless the action is clear with a single verb.
  • Avoid commas, punctuation and articles (the, an, a).
  • Avoid long button text.
  • Never change button text in the loading state.
  • General guidelines for when to use which type of button:
    • Primary or secondary buttons: If the data is being changed or altered in any way (Add, remove, update, etc.).
    • Link/Tertiary buttons: If the data is being interacted with but not changed (Download, export, refresh, etc.).

Examples#

Primary#

Use to emphasize the most important actions in a user flow. Avoid using more than one primary button in a card or page header.

Danger#

Use when an action will delete user data that would be difficult to recover from. Danger buttons should open confirmations in a modal or dialog before the action is executed unless used in the modal itself. See Delete vs Remove on destructive action usage patterns.

Default#

Most common button type. Use other button types if a button is placed higher or lower in visual hierarchy or importance.

Ghost#

Ghost buttons only have outlines and are used in the place of the default button against non-white backgrounds because they don't clash with the background color. Avoid using ghost buttons for primary or destructive actions.

Link#

Used for less important or less common actions. For example, link buttons are used in page headers and card headers for actions such as print, import and export. Use link buttons to provide non-navigational actions within or right after a sentence.

Danger Link#

Used when an action is destructive such as removing or deleting data. See Delete vs Remove on destructive action usage patterns.

Text (White Link)#

Used in place of the link button against dark or non-white backgrounds; where enough contrast is required to provide accessibility. For example, text buttons are used in page headers and modal headers for actions such as save, cancel, and sign in/out.

Last updated on by Larissa Hsia