Button

Button lets users trigger an action.

Overview

A button communicates a specific call to action that users can perform, including submitting a form, confirming a choice in a dialog, or canceling an action.

Anatomy

Anatomy: Button

1. Label:  Describes the action the button performs.
2. Icon (optional): Used to support the text and add emphasis or replace the text.
3. Container: The element that holds the text, color, and icon.

Demo

Open the component in Figma.

When to use

Use a button for these scenarios:

• When users need to take an action, such as Add, Save, or Cancel.

When not to use

Use another type of action for scenarios where users need to navigate to another page or have multiple actions and space constraints.

Use a link instead:

• When users can navigate to other pages.

Use a menu button instead:

• When you need to display multiple actions but there is a space constraint.

Variants

Button has four variants, each with a different visual hierarchy to guide users to perform actions.

Primary and secondary buttons should be used for important actions tied to the objective of an interaction, while floating buttons should be used for local-level actions, such as filtering a table.

Primary

A primary button is used for the most important call to action. It has the highest visual prominence and only one primary button should be used per context. These constraints help the user identify the primary action of a page and accomplish it.

A primary button can be used alone.

Secondary

Secondary buttons are used for supplemental actions. Secondary buttons establish hierarchy by calling users’ attention to actions that, while not the most important on the page, are still tied to the primary objective of an interaction.

A secondary button can be used in conjunction with a primary button to perform the negative action, usually Cancel or Back. Or, multiple secondary buttons can be used together to present equal, secondary actions.

A secondary button can’t be used alone.

Floating

Floating buttons are used when having a visible boundary is not ideal, including inline actions in tables, and the close button in a dialog. Floating buttons should be used sparingly because they can be difficult for users to identify.

When using floating buttons, check alignment carefully: their left and right padding can cause them to appear indented from surrounding text.

The visual boundary of this button allows vertical alignment.

The hidden boundaries of this floating buttons cause visual alignment issues.

Properties

Size

Small

Use a small button when there isn’t enough room for a medium button, such as inline actions in a table.

Medium (default)

Use a medium button as the default; it matches the size of input fields.

Large

Use a large button to provide the largest possible click target size.

Width

Contained

The text and the padding control the width of the button.

Wide

The button stretches to the width of its container.

Buttons with icons

Icon-only button

Each of the button variants (primary, secondary, and floating) can be an icon-only button. The icon-only button is for one-click actions. The icon used must clearly explain the button action. For example, a delete button could use only the delete icon.

The icon-only button includes a tooltip that labels the action on hover. See the content guidelines.

Leading and trailing icons

Icons can be placed before or after the text of a button to clarify or call attention to it. Only one icon, either leading or trailing, should be used per button.

Use an icon only when necessary and when it has a strong association with the text. The icon should never be used for decoration.

Danger button

Primary, secondary, and floating button variants can be a danger button. Danger buttons are used only for actions that are destructive and permanent, such as deleting.

Behaviors

States

As an interactive element the button component has the following states:

Default

The default state lets users know a button is enabled.

Hover

The hover state is initiated when a user pauses over an interactive element with a cursor.

Focus

The focus state displays the hover state with an additional highlight ring to visualize the interaction more easily when navigating with a keyboard.

Disabled

The disabled state prevents a user from initiating an action. The context of the page or component should make it clear why the element is disabled and what needs to change in order to be able to use it.

Active

The active state indicates an option is selected.

Accessibility

Odyssey components are designed and built to meet accessibility requirements out of the box. So, designers and engineers can focus on any accessibility concerns unique to their problem areas.

Our components meet WCAG 2.2 AA criteria and WAI-ARIA guidelines to provide a usable and accessible experience to everyone. See the ARIA guidelines for button.

Content guidelines

Label

• The label is the most important element of a button.
• Clearly and accurately describe the action that will occur.
• Lead with a strong verb that encourages action.
• Use the verb + noun content formula on buttons except in the case of common actions like Done, Close, Cancel, Add, or Delete.
• Be predictable. Use the same word or phrase as found elsewhere in the experience. For example, if you have a verb in the title, use the same verb in the button.
• One or two words, no more than four words, with fewer than 30 characters including spaces.
  Examples of long Okta button labels include:
  Save and add another
  Create Okta user type
  Enable application reporting
• If a button must explain two actions, you can use only the verbs if the context clearly describes the full actions. For example, Clear and revoke instead of Clear sessions & revoke tokens.
• Avoid unnecessary articles and prepositions, such as the, an, a, or with.
• Don’t use punctuation marks such as periods or exclamation points.
• Write in sentence case (capitalize the first word and proper nouns only).

Icon-only button tool tip

• Buttons should always have labels, unless they are only using an icon that is universally understood and accessible.
• The icon represents the button’s action and the meaning is unambiguous.
• The tooltip text describes the button’s action, rather than the name of the icon itself.
• Use the same verb + noun guidance as the label to write the tooltip.
• See tooltip.

Content accessibility

For all buttons, the aria-label text should include any visible button label text. Differences between visible and programmatic labeling can cause confusion, and could prevent voice recognition commands from working.

Icon-only buttons also require a label. It will appear automatically on hover and focus. Repeat the same text as the icon-only button tooltip.

Figma: Button