button

50 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Button purpose and definition

Buttons are clickable elements used to trigger actions. They communicate calls to action to the user and allow users to interact with pages in a variety of ways. Button labels express what action will occur when the user interacts with it.

When to use buttons

Use buttons to communicate actions users can take and to allow users to interact with the page. Each page should have only one primary button. Any remaining calls to action should be represented as lower emphasis buttons.

When not to use buttons

Do not use buttons as navigational elements. Instead, use links when the desired action is to take the user to a new page.

Button variants and their purposes

Primary: For the principal call to action on the page. Primary buttons should only appear once per screen (not including the application header, modal dialog, or side panel). Secondary: For secondary actions on each page. Secondary buttons can only be used in conjunction with a primary button and perform the negative action of the set, such as 'Cancel' or 'Back'. Do not use a secondary button in isolation or for a positive action. Tertiary: For less prominent, and sometimes independent, actions. Tertiary buttons can be used in isolation or paired with a primary button when there are multiple calls to action. Tertiary buttons can also be used for sub-tasks on a page where a primary button for the main and final action is present. Ghost: For the least pronounced actions; often used in conjunction with a primary button. In a progress flow, a ghost button may be paired with a primary and secondary button set, where the primary button is for forward action, the secondary button is for 'Back', and the ghost button is for 'Cancel'. Danger: For actions that could have destructive effects on the user's data (for example, delete or remove). Danger button has three styles: primary, tertiary, and ghost.

Button label content formula

Button labels should clearly indicate the action of the button. Use the {verb} + {noun} content formula on buttons except in the case of common actions like 'Done', 'Close', 'Cancel', 'Add', or 'Delete'. There are exceptions to this rule for situations in which button length could cause problems in compact UIs or negatively impact translation, but the {verb} + {noun} formula is still best practice. By default Carbon uses sentence case for all button labels.

Button label alignment

In a Carbon button, the label is always left-aligned, not center-aligned. The icons in a button with a label are right-aligned but in an icon only button, the icon is centered.

Button overflow content handling

When the button's label is too long to fit within the available space of the button, the label should overflow and wrap to the second line. Truncating a button label is not recommended. It is best practice to keep button labels succinct and follow the {verb} + {noun} content formula.

Button sizes and use cases

The button is available in seven different sizes: extra small, small, medium, large (productive), large (expressive), extra large, and 2XL. Extra small: Use when vertical space is limited or in areas with a confined layout. Small: Use when buttons are paired with 32px small sized input fields. Medium: Use when buttons are paired with 40px medium sized input fields. Large (productive): The most common button size in software products. Pairs with 14px body copy. Large (expressive): The larger expressive type size within this button provides balance when paired with 16px body copy. Used by the IBM.com team in website banners. Extra large: Use when buttons bleed to the edge of a larger component, like in the context of modals, side panel and narrow tearsheets. 2XL: Use when buttons bleed to the edge of a full-screen component, like in the context of large tearsheets. We do not recommend mixing different button sizes in button groups.

Button visual hierarchy and emphasis

The most important thing is to establish a visual hierarchy between the buttons in your UI. A layout should contain a single high-emphasis button that makes it clear that other buttons have less importance in the hierarchy. This high-emphasis button commands the most attention. A high-emphasis button can be accompanied by medium- and low-emphasis buttons that perform less important actions. Keep in mind that you should only group together calls to action that have a relationship to one another. You don't necessarily need to use the buttons in the order that their labels imply. Although secondary buttons have less visual prominence because they are less saturated than their primary counterparts, they are still tonally heavy. If your layout requires multiple actions, low emphasis buttons (tertiary or ghost) may be a better choice.

Secondary button usage and restrictions

Secondary buttons are tonally heavy but have less visual prominence than their primary counterparts due to their lower saturation. Secondary buttons are intended to be used in conjunction with a primary button. When used in a pair, the secondary button executes the set's negative action, like 'Cancel' or 'Back.' Secondary buttons should not be used in isolation or for a positive/primary action.

Button alignment contexts

Buttons are unique in that their alignment depends on where they appear and whether or not they're contained within another component. As a general rule, on full-page designs, the primary button is on the left side of the page. Whereas in wizards, where a user is progressing through a series of steps or dialog windows, the primary action traditionally sits at the bottom right. Buttons within components such as notifications, search fields, and data tables are also right-aligned. Left-justified: Banner call to actions, in-page forms, and nested buttons in components like tiles. Right-justified: Inline notifications, inline field buttons and data tables, progressive forms, wizards, and single-button dialogs. Full-span: Dialogs, side panel, and small tiles; currently Carbon does not offer a way to implement full-span buttons in code without an override, they max out at 320px.

Fixed width button structure

When a button is treated as a fixed element within a layout, there is fixed padding of 16px to the left and 64px padding to the right of the button label. The button label determines the button's width.

Hanging versus non-hanging button alignment

Hanging button alignment is when the button label is aligned to the grid rather than the container. This alignment should be used to group sections between components and buttons that directly affect each other. Non-hanging button alignment is when the button container is aligned to the grid. These rules apply to buttons with a visible container. For buttons that don't have a visible container in the default state, such as ghost button and danger ghost button, refer to ghost button alignment guidance.

Fluid width buttons

There is a hybrid scenario where a floating primary, secondary, or tertiary button can span a designated number of columns on the responsive column grid, giving it a fluid width. These are called 'fluid width buttons.' Fluid width buttons are always preferable to fixed width default buttons in a layout. When possible, set the button container's relative position to the responsive layout grid and match the button width to the width of other elements on the page. Ideally, when using groups of related buttons (not including ghost buttons unless in a tearsheet or modal), they should all be the same width.

Fluid button border and separator token

There is a 1px border between all fluid buttons that use the $button-separator token for borders. This feature adds a 3:1 distinction between the two interactive UI elements. The border is a recommended feature to improve accessibility.

Button groups definition and usage

Button groups are a useful way of aligning buttons that have a relationship. Group the buttons logically into sets based on usage and importance. Too many calls to action will overwhelm and confuse users so they should be avoided. Button groups should be used when there are either two or three actions that a user needs to consider. Any more than three actions should be grouped meaningfully using menu buttons to reduce the amount of space these actions take up on a page.

Button width in button groups

When using groups of related buttons (not including ghost buttons), they should all be the same width. The width of all the buttons is usually determined by the longest button label. This guidance should be followed for both the toolbar and the batch actions toolbar as well.

Horizontally arranged button groups positioning

When using multiple buttons, the position of the primary button adheres to alignment guidance. A primary button will be left-aligned and positioned to the left of the secondary/tertiary button on full-page designs. The primary button will be right-aligned and appear to the right of the secondary/tertiary button within wizards and dialog windows.

Vertically stacked button groups

Vertical button groups are common in products to save real estate in narrow columns and occasionally side panels. These stacked buttons can act as fluid buttons bleeding into the side panel, or they can have a 16px spacing surrounding the side panel. The 16px spacing allows the use of a tertiary button in the vertically stacked button group. In these instances, the primary button is always on top and the secondary or tertiary button is below.

Recommended button group combinations with primary button

For 2 buttons: Primary and secondary button; Primary and tertiary button; Primary and ghost button; Primary and danger tertiary button; Danger primary and secondary button; Danger primary and ghost button. For 3 buttons: Primary, secondary, and tertiary button; Primary, secondary, and ghost button; Primary and 2 secondary buttons; Primary and 2 tertiary buttons; Primary, tertiary, and danger tertiary.

Recommended button group combinations without primary button

For 2 buttons: 2 Tertiary buttons; Tertiary and ghost button; 2 Ghost buttons. For 3 buttons: 3 Tertiary buttons; 2 Tertiary and 1 danger tertiary button.

Button group combinations to avoid

Do not use two high-emphasis buttons in a button group. Do not use the secondary button in conjunction with non-primary buttons. Do not use tertiary and danger tertiary buttons together. Do not use primary and danger ghost buttons together. Do not use tertiary and danger ghost buttons together.

Primary button usage and exceptions

Primary button is used for the principal call to action on the page. Primary button should only appear once per screen (the only exceptions are temporary flows with primary actions). Temporary flows are when a primary button on a page, but through interaction with the page content, another flow may be launched that has its own primary button. Temporarily, there may be two primary buttons on a page. In this case, a user has triggered something with an intention to focus on another flow, therefore temporarily having two primary buttons on a page is acceptable.

Primary button best practice: Not every page needs one

Sometimes the primary purpose of the page is to interact with other components or read over content, rather than to trigger an action. In this case, use tertiary and ghost buttons for these supporting actions or experiences.

Tertiary button usage and alignment

Tertiary buttons have less prominence than a primary button and slightly more prominence than a ghost button. Tertiary buttons work well on their own or as part of a button group. Tertiary buttons should stay aligned with the content of the page. Always make sure the tertiary button has adequate padding on all sides. Tertiary buttons should not be used in fluid arrangements.

Tertiary button best practice: Page headers

It is challenging to use a primary button in the header of a page because the content beneath the header is probably going to have a primary action, or will in a future release. Even if the button in the page header is not styled as a primary button, it has significant prominence due to its hierarchical placement at the top. Therefore, it is advised to use a tertiary button for page headers. If it is determined that the button in the page header, across all tabs, should be primary, ensure none of the content below the header contain another primary action.

Tertiary button best practice: Button groups

In button groups, where there is one primary and two other actions with shared importance, consider using tertiary buttons.

Tertiary button best practice: Empty states

For empty states that appear on pages that already have the primary action defined, a tertiary button is the ideal solution to launch a new task flow.

Ghost button characteristics and usage

Ghost buttons have the least prominence among the button variants. Ghost buttons are more subtle, making them ideal for supplementary actions. They work best when they are flush against a container or horizontally grouped with other elements.

Ghost button alignment with content

Ghost buttons work well when aligned to a corner of a container. The general rule for vertically aligning a ghost button with other content is to ensure its label aligns with the text elsewhere on the page. Ghost buttons can be useful for small supplementary actions in side panels. In this context, extending the width of the ghost button to the full width of the container makes this treatment seem intentional. Aligning to the full width of a container is only recommended when the containers are smaller in size such as a side panel of 480px (medium) and below. Ghost buttons can also be aligned horizontally and inline with other components on the page.

Ghost button best practice: Data table actions

Buttons in the table toolbar are often depicted as a primary button, but this might not always be the case. Use a ghost button instead if there is another button on the page that requires primary styling.

Ghost button best practice: Productive cards

In dashboards with multiple productive cards, ghost buttons work well as they draw less attention than a tertiary button. For a ghost button to appear aligned in vertical arrangements within a container, it is recommended that it touches at least two edges of the container.

Ghost button best practice: Cancel action

Ghost buttons work well as a cancel button in progressive flows, as they draw less attention; users have to purposefully find and click the button to cancel. In tearsheets, the buttons are fluid, which wouldn't be a suitable application for a tertiary button.

Danger button purpose and styles

Danger button is used for actions that could have destructive effects, such as 'Delete', 'Remove', or 'Stop'. The danger button has three different styles: primary, tertiary, and ghost. Determining which danger button style to use will depend on the level of emphasis you want to give to the destructive action. Destructive actions that are a required or primary step in a workflow should use the primary danger button style. However, if a destructive action is just one of several actions a user could choose from, then a lower emphasis style like the tertiary danger button or the ghost danger button may be more appropriate.

Button with icon usage guidelines

Icons can be placed next to labels to clarify an action and call attention to a button. However, icons should be used sparingly, as overuse can create visual noise and make an experience less usable. If you use a button with an icon in one part of your UI it does not mean that you need to add icons to all other buttons. Use a 16px icon within buttons; use a 20px icon within the large expressive buttons. Icons are distinguished by their solid shape and knocked-out details. Icons should always appear to the right of the label. Icons used in buttons must be directly related to the action that the user is taking. Icons must match the color value of the label within a button.

Icon spacing in ghost buttons

Use 8px spacing between the label and the icon in a ghost button.

Universal actions with well-established icons

When deciding whether to add an icon to a button, consider how recognizable the icon is and whether, in other contexts, a similar icon may be used for a different meaning. We want to avoid the same icon being used for completely different actions. Universal actions suitable for adding an icon alongside the button label with clearly defined and widely recognized icons are: Create/Add (Add), Edit (Edit), Copy (Copy), Delete (Trash can), Remove (Subtract alt), Export (Export), Upload (Upload), Download (Download), Play/Start (Play), Pause (Pause), Stop (Stop outline), Refresh (Restart). Icons that are not in this list can be used in buttons, as long as the icon clearly conveys the intended action.

Icon representation pitfall

Do not use a defined icon to represent a different universal action. Using icons in the universal actions list for other actions can confuse the expected outcome and experience.

Launch icon usage

The launch icon should be used on any call to action that launches the user into another tab (whether the content of the new tab is part of the same product or an entirely separate web resource). Buttons and links requiring the launch icon are often found in the UI left navigation area, side panel, cards, and modals. The target destination of the launch action should be made clear to the user through the button or link label and the surrounding context.

Icon usage consistency in button groups

Using icons in button groups is optional. We recommend showing an icon for each button in a button group or showing no icons for consistency. A benefit of pairing an icon with a button label is that it visually describes its action and directs more attention to it. However, in some cases, using too many buttons with icons in a group can create unwanted noise in the UI and tend to overcomplicate a simple experience. Only use icons in button groups for the universal actions or for other actions where a particular icon is commonly paired and associated.

Default icon variation preference

Use the default option for all icons (the only exception is status icons, which have their own defined icon to use). The Carbon library contains filled variants of a few icons. Since not every icon has this variation, we advise using the default option for all icons. Default icons are named after their action.

Icon only button usage

Icon only buttons allow users to take actions, and make choices, with a single tap. Icon buttons can take the form of a primary, secondary, tertiary, or ghost variant but most commonly will be styled as primary or ghost buttons. Icon only buttons should be used sparingly. Using icon only buttons is recommended for the following use cases: The icon must be standardized and recognizable without label or must represent an action with a strong visual attribute, such as a pin icon for a pinning action. There is insufficient space and multiple actions, therefore a toolbar using icon buttons is required.

Tooltip requirement for icon only buttons

Regardless of how recognizable an icon may or may not be, or whether that action lies within the universal actions list, a tooltip is always required with text explaining what the icon button would do if clicked.

Icon only ghost button color tokens

Carbon builds type, color, and spacing tokens into its components, improving the ease of component usage. Do not change the color token for icon only ghost buttons. The same applies for specifications across components.

Danger button icon only form restriction

Danger buttons cannot be used in an icon only form. Danger can be a critical action and should be applied to a button that holds higher emphasis along with a visual label. It is best to use a danger button in a primary, tertiary, or ghost button form.

Primary button focus behavior

The primary button is the default action. When dialogs appear, the primary button typically takes focus. On a form, if focus is on a component that is not actionable with the Enter key, pressing Enter will activate the primary button.

Button mouse interaction

Users can trigger a button by clicking anywhere within the button container.

Button keyboard interaction

Users can trigger a button by pressing Enter or Space while the button has focus. For additional keyboard interactions, see the Accessibility tab.

Button loading state

Buttons can have inline loading that provides visual feedback that the action is in process. The button would be disabled when inline loading is in progress.

Right-to-left (RTL) button behavior

For right-to-left (RTL) languages, the entire button is mirrored horizontally. The label is right-aligned and the icon is left-aligned.

Give your agent this brain