Button

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

Each page should have one primary button, and a Return or Enter keyboard event should trigger it. Any remaining calls-to-action should be represented as secondary buttons.

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

A button’s text label is the most important element on a button, as it communicates the action that will be performed when the user touches it. In a contained button the text is always left aligned, not centered. By default Carbon uses sentence case for all button labels.

If a text label is not used, an icon should be present to signify what the button does.

There are four common button sizes: default, inline, and small. Each button type can use any of these three sizes based on need. The fourth button size, full bleed, has a more reserved application and should rarely be used.

A layout should contain a single prominent button that makes it clear that other buttons have less importance in the hierarchy. This high-emphasis button commands the most attention.

A UI can have more than one button in a layout at a time, so a high-emphasis button can be accompanied by medium- and low-emphasis buttons that perform less important actions. Only group together calls to action that have a relationship to one another.

Although buttons are usually left aligned (never centered) in our system, they are unique in that, more so than any other component, their alignment depends on where they appear and whether or not they’re contained within another component. Typical nested button locations include.

When possible set the button container’s relative position to the responsive layout grid and match buttton width to the other elements on the page. Say something here also about button groups and matching both buttons widths to the width of the longest button.

By default the container’s width is set to the size of the text label with 64px fixed padding on the right side and 16px fixed padding on the left.

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.

When using multiple buttons, the primary button appears to the right and any secondary buttons appear to the left. Research has shown that performance differences between secondary and primary button placement are negligible, however maintaining consistency throughout a product, offering, or platform is crucial. The Secondary / Primary button order (secondary to the left and primary to the right) is therefore our required guidance and should be followed at all times.

Typical landing pages for product has buttons side by side. However vertical button groups are also common in product in order to save real estate in narrow columns and occassionally side panels. In this instance the primary button is always on top and the secondary or tertiary button is below.

A button’s text label is the most important element on a button, as it communicates the action that will be performed when the user touches it. Buttons need to be clear and predictable.

Button labels should clearly indicate the action of the button. To provide enough context, use the {verb} + {noun} content formula on buttons except in the case of common actions like “Done”, “Close”, “Cancel”, “Add” or “Delete.”

For consistency, see Carbon’s content guidelines for a list of recommended action labels.

Mouse

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

Keyboard

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

Screen readers

VoiceOver: Users can trigger a button by pressing Enter or Space while the button has focus.

JAWS: Users can trigger a button by pressing Enter or Space while the button has focus.

NVDA: Users can trigger a button by pressing Enter or Space while the button has focus.

Primary buttons are high emphasis elements that are used to indicate the principal call to action on the page. They should be limited to one primary button per page. Keep in mind that not every screen needs a primary button.

Secondary buttons are medium emphasis elements that are used for secondary actions on each page. They can only be used in conjunction with a primary button.

Tertiary buttons are low emphases elements that are used for less prominent actions. They can be used in insolation or in a pair with a primary button when there are multiple calls to action.

Danger buttons are high emphasis elements that have a different visual style to inform users of potentially destructive actions they are about to take. Within a set, the danger button should be styled as a primary button.

For more guidance on destructive actions, refer to the common actions pattern.

Ghost buttons are low emphasis elements that are used for least pronounced actions. They are often used in conjunction with primary and secondary buttons. Since the enabled state does not have a visual container, ghost buttons do not distract from nearby content.

Icons can be placed next to labels to both clarify an action and call attention to a button. There are certain instances where and icon will suffice in place of a text label, but use icon buttons cautiously.

Icon buttons allow users to take actions, and make choices, with a single tap. Icon buttons can take the form of any of the 5 types above but most commonly will be styled as primary or ghost buttons.

Help us improve this pattern by providing feedback, asking questions, and leaving any other comments on GitHub.