Button

An interactive element that represents an action or choice. Well written button text clearly communicates what action will occur when the user interacts with it.

Developer Documentation

See the code and developer guidelines for this component.

Usage

Use Buttons to represent what type of actions the users can take on a page and to create a visual hierarchy between different calls to action.

As a general rule, use no more than two primary call-to-action buttons (Primary Button) per page.

Examples of Button usage:

  • To trigger action.
  • To submit a form.
  • To begin a new task.
  • To navigate to the next step in a process.
  • To confirm completion or to exit out of a flow.

If the action will take the user to a new page or to an external site, consider using a Link instead.

Guidelines

How to Write Effective Button Text

  • Button text should set clear expectations as to what will happen when activated.
  • Use title case (capitalize the first letter each word).
  • Use task-specific action verbs like: “Add”, “Remove”, “Read Details”, and “Submit”.
  • Use less than 20 characters.
  • Use compact words. For example, instead of “Submit Your Information Now” use “Submit”.
  • Use first-person pronouns. Use “Customize My Loan,” instead of “Customize Your Loan.”
  • Do not use ampersands (&).
  • Do not wrap button text into a second line; it reduces legibility, and starts looking less like an interactable element.

Button Styling

  • Text should be center aligned.
  • Buttons should have 16px of padding on the top and bottom, and 24px on the left and right sides.
  • Width should be between 48px and 280px.
  • Grouped buttons should be 16px away from each other.
  • Do not use buttons in paragraphs or within lines of text. Use Link instead.

Full Width at Smaller Viewports

At small viewport sizes, a Button may be full width.

  • Stacked Buttons should have the primary action above secondary actions.
  • Use full width Buttons in containers that take up 1/3 of the grid or smaller.

Variants

Use Button variants to emphasize different actions within a page.

Variant names imply the order within action hierarchy, but they do not imply the visual placement on the page.

Primary Button

Represents the main call to action on the page. Use no more than two Primary Buttons per page.

When there are multiple buttons, use the Primary Button to indicate the main action.

Examples

  • Submit Application
  • Apply to Buy a Home
  • Apply for Refinance
  • In a multi-step form, a Primary Button works with Secondary and Tertiary Button as a set of related actions.
    • Primary Button is "Submit"
    • Secondary Button is "Back"
    • Tertiary Button is "Cancel"

Developer Documentation

See the code and developer guidelines for this component.

Secondary Button

Represents the second-highest priority action, following the Primary Button. There can be more than one on a page.

Examples

  • Preview
  • Save For Later
  • Back
  • In a multi-step form, a Secondary Button works with Primary and Tertiary Button as a set of related actions.
    • Primary Button is "Submit"
    • Secondary Button is "Back"
    • Tertiary Button is "Cancel"

Developer Documentation

See the code and developer guidelines for this component.

Tertiary Button

Represents less prominent actions. Sometimes in an action set with Primary and Secondary Buttons, but they can also be independent actions.

Example

  • In a multi-step form, a Tertiary Button works with Primary and Secondary Button as a set of related actions.
    • Primary Button is "Submit"
    • Secondary Button is "Back"
    • Tertiary Button is "Cancel"

Developer Documentation

See the code and developer guidelines for this component.

States

Disabled

Represents an action that’s not currently available to the user. It implies that the Button would be available given a certain set of circumstances.

Since a user can’t interact with this Button, consider if it’s necessary to show it at all.

Disabled - Primary

Developer Documentation

See the code and developer guidelines for this component.

Disabled - Secondary

Developer Documentation

See the code and developer guidelines for this component.

Disabled - Tertiary

Developer Documentation

See the code and developer guidelines for this component.

Spinning

Use when data is being saved or submitted. The spinning indicator will replace the Button text.

Spinning - Primary

Developer Documentation

See the code and developer guidelines for this component.

Spinning - Secondary

Developer Documentation

See the code and developer guidelines for this component.

Spinning - Tertiary

Developer Documentation

See the code and developer guidelines for this component.

Full Width at Smaller Viewports

At small viewport sizes, a Button may be used at full width.

  • Stacked Buttons should have the primary action above secondary actions.
  • Use full width Buttons in containers that take up 1/3 of the grid or smaller.

Developer Documentation

See the code and developer guidelines for this component.

Anatomy

  • A Button must contain text and/or an Icon

Accessibility

  • If a Button only includes an Icon with no text, alternative text must be provided.

We follow, WCAG 2.1 Level AA - Button Aria Practices (Web Content Accessibility Guidelines).