Buttons allow users to take actions, and make choices, with a single click. They are typically found in forms, dialog, and toolbars. Some buttons are specialized for particular tasks, such as navigation or presenting menus.

Props

Name
Type
Default
Required
string
-

Text to render inside the button to convey the function and purpose of the button. The button text has a fixed size.

Accessibility: Screen readers read the accessibilityLabel prop, if present, instead of the text prop. See accessibilityLabel for more info.

string
-

Specify the id of an associated element (or elements) whose contents or visibility are controlled by a button component so that screen reader users can identify the relationship between elements.

Optional with button-role + button-type buttons.

Accessibility: It populates aria-controls.

boolean
-

Indicate that a button component hides or exposes collapsible components and expose whether they are currently expanded or collapsed.

Optional with button-role + button-type buttons.

Accessibility: It populates aria-expanded.

boolean
-

Indicate that a button component controls the appearance of interactive popup elements, such as menu or dialog.

Optional with button-role + button-type buttons.

Accessibility: It populates aria-haspopup.

string
-

Supply a short, descriptive label for screen-readers to replace button texts that do not provide sufficient context about the button component behavior. Texts like Click Here, Follow, or Read More can be confusing when a screen reader reads them out of context. In those cases, we must pass an alternative text to replace the button text.

Use IconButton if you only need a button with an icon and no text.

Accessibility: It populates aria-label. Screen readers read the accessibilityLabel prop, if present, instead of text.

"gray" | "red" | "blue" | "transparent" | "semiTransparentWhite" | "transparentWhiteText" | "white"
"gray"

Primary colors to apply to the button background.

Accessibility: Use transparentWhiteText to increase the contrast between a dark background and a transparent-Button text.

boolean
-

Set disabled state so buttons look inactive, cannot be interacted with, and actions are not available.

boolean
false

Default buttons are sized by the text within the button whereas full-width buttons expand to the full width of their container.

string
-

Specify a link URL.

Required with link-role buttons.

$Keys<typeof icons>
false

Add a Gestalt icon to be displayed after the button text. Sometimes an icon can help clarify the usage of a button. Menus are a common use case.

Accessibility: Icons on buttons are not accessible for screen readers.

Use IconButton if you only need buttons with icons and no text.

({ event: SyntheticMouseEvent<HTMLButtonElement> | SyntheticKeyboardEvent<HTMLButtonElement> | SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement>, {| disableOnNavigation: () => void |}> }) => void
-

Callback fired when a button component is clicked (pressed and released) with a mouse or keyboard.

See OnLinkNavigationProvider to learn more about link navigation.

React.Ref<"button"> | React.Ref<"a">
-

Forward the ref to the underlying button or anchor element.

"none" | "nofollow"
"none"

Optional with link-role buttons.

"button" | "link"
"button"

Select a button variant:

  • 'button': Use to render 'submit' or 'button'-type buttons. The button is rendered as a <button>.
  • 'link': Use for buttons to act like links. The button is rendered as an <a>.

Required with link-role buttons.

boolean
false

Control the "selected" state of a button component to toggle binary states.

Optional with button-role + button-type buttons.

"sm" | "md" | "lg"
"md"

Display a button in different sizes. Size changes the component padding modifying its fixed height: sm (32px), md (40px), lg (48px).

-1 | 0
0

Remove the component from sequential keyboard navigation to improve accessibility. The component is not focusable with keyboard navigation but it can be focused with Javascript or visually by clicking with the mouse.

The default behaviour for the component is to be focusable in sequential keyboard navigation in the order defined by the document's source order.

If component is disabled, the component is also unreachable from keyboard navigation.

null | "self" | "blank"
"null"

Define the frame or window to open the anchor defined on href:

  • null opens the anchor in the same window.
  • blank opens the anchor in a new window.
  • self opens an anchor in the same frame.

Optional with link-role buttons.

"submit" | "button"
"button"

Select a type of button-role button:

-button: Use to render simple push buttons with no default behavior and control custom functionality inside the onClick callback.

-submit: Use to submit forms. The button is inside/associated with a form.

Usage guidelines

When to Use
  • Communicating an action that will occur.
  • Triggering or enabling an action, such as submitting requested information.
  • Progressing or regressing a user through a step in a flow.
When Not to Use
  • Directing users to a new page or different part within the same page. Instead, use Link.
  • Limited space available. Consider using an IconButton instead.

Basic Button

Types & Roles

Size

Color

color="gray"
color="red"
color="blue"
color="white"
color="transparent"
color="semiTransparentWhite"

Color: transparent and semiTransparentWhite

Image to compare contrast between text color and background.
Image to compare contrast between button color and background.

Width

Icons

Selected state

ref

Accessibility: label

Accessibility: controls, expanded, & popup

OnLinkNavigationProvider
OnLinkNavigationProvider allows external link navigation control across all children components with link behavior.