Button

v1.0.0 | View in Storybook

​

Placement

• Buttons should be placed contextually near the objects they affect for easy discoverability.

​

Right side

Buttons should always be placed furthest right in the following contexts:

• Full page: If the action affects the entire content on the page, Buttons should be placed either in the page header area on the right or within the Page toolbar with the Primary Button being furthest right.
• In side panels: Buttons can be placed in the header or footer area, with the Primary Button being furthest right.
• In Dialogs, steppers or wizards: Buttons always appear in the footer, with the Primary Button being furthest right.

​

Left side

Buttons may make more sense to place on the left side in the following contexts:

• Cards: Card content is always left aligned and Buttons placed on the left to align with content makes for better readability.
• Lists: In dense lists when content is left aligned, it may make more sense to place relevant Buttons on the left to align with content.

​

When to use a full width Button

Buttons by default have fixed paddings. The width of the Button adjusts to accommodate the label keeping the correct padding on all sides. However, Buttons can span the full width of their parent container. Full width buttons help visually distinguish actions from other screen elements so they are easier to detect. The content of the Button always stays centered. Examples of when you might want to use a full width Button are in narrow side panels or small containers such as Popovers and Menus.

​

Grouping

• Small groups (2-3): Use secondary and/or ghost buttons (plus one primary if needed) with 8px spacing between buttons.
• Large groups (3+, e.g., toolbars): Use mainly ghost buttons to reduce visual clutter with 8px spacing between buttons.

​

Variants and when to use them

• Consider Button hierarchy: We use different Button types to establish a visual hierarchy. You don’t always need to use the secondary Button as the second Button in your layout. The most important thing is to establish a visual hierarchy between the buttons in your UI, which is why only one primary Button should be used on a page.
• Type indicates importance: The Button type should be chosen based on the importance of the action. More important, more emphasis.
• Verb + noun format: Reference action label guidelines in the design.md file to use the appropriate verb. It’s always best to use a label with your Button unless the icon is highly recognizable, such as the save (floppy disk) or delete (trash bin) icons, or space is limited. Alternatively, use an icon button with a Tooltip.
• Avoid disabled Buttons: Disabled Buttons can be confusing and frustrating for many users and can be difficult to spot for those with low vision or users relying on keyboard interactions, since disabled Buttons won’t take keyboard focus. To make things easier, enable the Button so users can click it, and provide an error message or inline validation if information is incorrect or missing. Or try using alternative methods to activate a Button control such as selections that trigger an Action toolbar. If you must use a disabled Button, include clarifying text or a tooltip to explain why.

​

Dos and don’ts

• Do use only one default (primary) button per view, if needed.
• Do use size=“sm” for buttons in the Topbar action slot. Match this in your designs.
• Don’t use a button where a link should be. Buttons change state or trigger actions. Links navigate.
• Don’t use destructive buttons inline as the first interaction. Use a ghost or other Button type then use the destructive Button when the user confirms the action.

​

Behavior

• Primary action submits or commits the labeled operation; support keyboard activation (Enter / Space) when the control is focusable.
• Loading state should prevent duplicate submissions where the action is not idempotent.
• Icon-only buttons must have an accessible name (visible label, aria-label, or Tooltip that is exposed to assistive tech per implementation).

​

Toggle vs Button

A standard Button triggers a one time action and returns to its resting state immediately after, whereas a Toggle maintains an on/off state until clicked again. Toggled Buttons have different visual identities than Buttons and should be used to indicate the following interactions:

• A selected element such as in a Toolbar.
• An applied filter such as in Page toolbar.

​

Often used with

Tooltip on icon-only triggers; Menu (dropdown / split); KBD hints in labels; pairs with Dialog, Popover, or Action toolbar as trigger.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Default sizes

Use default (primary) Button sizes for the main call to action on a page or in a form footer; match size to surrounding UI density while keeping the primary action visually prominent.

​

Secondary sizes

Use secondary Button sizes for supporting actions that are important but not the primary CTA—for example, “Cancel” beside “Save” in a dialog.

​

Outline sizes

Use outline Button sizes for low-emphasis actions in dense interfaces or on varied backgrounds where a filled button would compete with the primary action.

​

Ghost sizes

Use ghost Button sizes for tertiary actions and icon buttons in toolbars where minimal visual weight is needed to reduce clutter.

​

On dark variants

Use on-dark Button variants when placing buttons on dark or tinted backgrounds such as banners, media overlays, or inverted header regions.

​

Destructive sizes

Use destructive Button sizes for irreversible actions such as delete or remove, typically in dialogs or confirmation flows where the consequence is explicit.

​

Button states

Reference Button states—default, hover, focus, active, and disabled—to ensure interactive feedback is clear and consistent across variants.

​

All sizes

Compare all Button sizes to choose the scale appropriate for the context, from compact toolbars (sm) to prominent page-level actions (default or lg).

​

With left icon

Place an icon to the left of the Button label when it reinforces the action meaning—for example, a plus icon before “Add item.”

​

With right icon

Place an icon to the right of the Button label when it indicates direction or outcome—for example, a chevron before “Next” or an external-link icon for opening in a new context.

​

Icon buttons

Use icon-only Buttons when space is limited and the icon is widely recognized; always pair with a Tooltip or accessible name so the action is not ambiguous.

​

Disabled

Avoid disabled Buttons when possible; if used, provide adjacent text or a Tooltip explaining why the action is unavailable so users are not left guessing.

​

Loading

Use the loading Button state during in-progress operations to prevent duplicate submissions and signal that the action is being processed.

​

In context

Review Buttons in context—alongside forms, cards, or toolbars—to validate hierarchy, spacing, and alignment with surrounding content.

​

Click interaction

Verify Button click interaction fires the expected action once per activation and does not conflict with parent clickable regions.

​

Keyboard navigation

Ensure Buttons are focusable and activatable with Enter and Space, and that focus order follows a logical path through grouped actions.

​

Accessibility

• Icon-only buttons: Always provide an explicit aria-label or an internal screen-reader-only text element (<span className="sr-only">) when no visual text label exists.
• Disabled states: Use aria-disabled="true" rather than native HTML disabled attributes if you need the button to retain keyboard focusability (e.g., to trigger an explanatory disabled-state tooltip).

​

Form button types

Use correct HTML button types in forms—submit, reset, or button—so Enter key behavior and form submission work as users expect.

​

Edge case empty

Avoid rendering Buttons with empty labels; empty buttons fail accessibility checks and give users no indication of the action.

​

Edge case long text

Test Buttons with long labels to ensure text wraps or truncates gracefully within width constraints without breaking layout.

​

Edge case special characters

Verify Buttons render special characters and localized strings correctly in labels without clipping or encoding issues.

​

Edge case multiple icons

Avoid multiple icons in a single Button unless the pattern is explicitly supported; extra icons often confuse the action meaning.

​

Edge case whitespace

Trim whitespace in Button labels; leading or trailing spaces can cause misalignment and inconsistent sizing.

​

Edge case nested elements

Keep Button content flat; nested interactive elements inside a Button break accessibility and click targeting.

​

Edge case width constraints

Test Buttons in narrow containers to confirm labels truncate or wrap appropriately, or switch to icon-only with a Tooltip when space is critical.

​

Edge case icon only

Icon-only Buttons must always include an accessible name via aria-label or Tooltip so screen reader users understand the action.

​

Edge case rapid state changes

Handle rapid state changes—such as quick toggling between default and loading—so the Button does not flicker or allow duplicate submissions.

​

Edge case invisible content

Ensure Button labels and icons are visible and meet contrast requirements; invisible or near-invisible content makes actions unusable for many users.