Button

View source on GitHub

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
`text` 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.
`accessibilityControls`	`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.
`accessibilityExpanded`	`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.
`accessibilityHaspopup`	`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.
`accessibilityLabel`	`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`.
`color`	`"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.
`disabled`	`boolean`	-
	Set disabled state so buttons look inactive, cannot be interacted with, and actions are not available.
`fullWidth`	`boolean`	`false`
	Default buttons are sized by the text within the button whereas full-width buttons expand to the full width of their container.
`href`	`string`	-
	Specify a link URL. Required with link-role buttons.
`iconEnd`	`$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.
`onClick`	`({ 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 custom navigation variant for examples.
`ref`	`React.Ref<"button"> \| React.Ref<"a">`	-
	Forward the ref to the underlying button or anchor element.
`rel`	`"none" \| "nofollow"`	`"none"`
	Optional with link-role buttons.
`role`	`"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.
`selected`	`boolean`	`false`
	Control the "selected" state of a button component to toggle binary states. Optional with button-role + button-type buttons.
`size`	`"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).
`tabIndex`	`-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.
`target`	`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.
`type`	`"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

<Button text="Medium-sized button" />

<Button text="Medium-sized button" />

Types & Roles

Visit pinterest.com

Disable buttons

Remove from keyboard navigation with tabIndex

function Example() {
  const [disabled, setDisabled] = React.useState(false);
  const [tabIndex, setTabIndex] = React.useState(false);

  return (
    <Flex alignItems="start" direction="column" gap={6}>
      <Flex gap={2}>
        <Tooltip text="Default button">
          <Button
            onClick={() => {}}
            text="Clear search history"
            disabled={disabled}
            tabIndex={tabIndex ? -1 : 0}
          />
        </Tooltip>
        <Tooltip text="Submit button">
          <Button
            type="submit"
            name="satisfaction-questionnaire"
            text="Submit your response"
            disabled={disabled}
            tabIndex={tabIndex ? -1 : 0}
          />
        </Tooltip>
        <Tooltip text="Link button">
          <Button
            role="link"
            target="blank"
            href="https://www.pinterest.com"
            text="Visit pinterest.com"
            disabled={disabled}
            tabIndex={tabIndex ? -1 : 0}
          />
        </Tooltip>
      </Flex>
      <Flex gap={2}>
        <Switch
          onChange={() => setDisabled(!disabled)}
          id="disable-buttons"
          switched={disabled}
        />
        <Box paddingX={2} flex="grow">
          <Label htmlFor="disable-buttons">
            <Text>Disable buttons</Text>
          </Label>
        </Box>
      </Flex>
      <Flex gap={2}>
        <Switch
          onChange={() => setTabIndex(!tabIndex)}
          id="unreachable-buttons"
          switched={tabIndex}
        />
        <Box paddingX={2} flex="grow">
          <Label htmlFor="unreachable-buttons">
            <Text>Remove from keyboard navigation with tabIndex</Text>
          </Label>
        </Box>
      </Flex>
    </Flex>
  );
}

function Example() {
  const [disabled, setDisabled] = React.useState(false);
  const [tabIndex, setTabIndex] = React.useState(false);
  return (
    <Flex alignItems="start" direction="column" gap={6}>
      <Flex gap={2}>
        <Tooltip text="Default button">
          <Button
            onClick={() => {}}
            text="Clear search history"
            disabled={disabled}
            tabIndex={tabIndex ? -1 : 0}
          />
        </Tooltip>
        <Tooltip text="Submit button">
          <Button
            type="submit"
            name="satisfaction-questionnaire"
            text="Submit your response"
            disabled={disabled}
            tabIndex={tabIndex ? -1 : 0}
          />
        </Tooltip>
        <Tooltip text="Link button">
          <Button
            role="link"
            target="blank"
            href="https://www.pinterest.com"
            text="Visit pinterest.com"
            disabled={disabled}
            tabIndex={tabIndex ? -1 : 0}
          />
        </Tooltip>
      </Flex>
      <Flex gap={2}>
        <Switch
          onChange={() => setDisabled(!disabled)}
          id="disable-buttons"
          switched={disabled}
        />
        <Box paddingX={2} flex="grow">
          <Label htmlFor="disable-buttons">
            <Text>Disable buttons</Text>
          </Label>
        </Box>
      </Flex>
      <Flex gap={2}>
        <Switch
          onChange={() => setTabIndex(!tabIndex)}
          id="unreachable-buttons"
          switched={tabIndex}
        />
        <Box paddingX={2} flex="grow">
          <Label htmlFor="unreachable-buttons">
            <Text>Remove from keyboard navigation with tabIndex</Text>
          </Label>
        </Box>
      </Flex>
    </Flex>
  );
}

Size

<Flex gap={2}>
  <Button size="sm" text="Small-sized button" />
  <Button text="Medium-sized button" />
  <Button size="lg" text="Large-sized button" />
</Flex>

<Flex gap={2}>
  <Button size="sm" text="Small-sized button" />
  <Button text="Medium-sized button" />
  <Button size="lg" text="Large-sized button" />
</Flex>

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.

function Example() {
  const [selectedTransparent, setSelectedTransparent] = React.useState(false);
  const [selectedSemiTransparentWhite, setSelectedSemiTransparentWhite] = React.useState(false);

  return (
    <Flex>
      <Box column={4} padding={2}>
        <Box margin={3}>
          <Button
            text="Toggle text color & compare contrast"
            onClick={() => setSelectedTransparent((currentValue) => !currentValue)}
            selected={selectedTransparent}/>
        </Box>
        <Image
          alt="Image to compare contrast between text color and background."
          color="rgb(231, 186, 176)"
          naturalHeight={751}
          naturalWidth={564}
          src="https://i.ibb.co/7bQQYkX/stock2.jpg"
        >
          <Box padding={2}>
          <Button
            color={selectedTransparent ? 'transparentWhiteText' : 'transparent'}
            iconEnd="add-pin"
            text="Save this image"
          />
          </Box>
          <Box padding={2} position="absolute" bottom right>
            <Button
            color={selectedTransparent ? 'transparent' : 'transparentWhiteText'}
            iconEnd="pin-hide"
            text="Hide this image"
          />
          </Box>
        </Image>
      </Box>
      <Box column={4} padding={2}>
        <Box margin={3}>
          <Button
            text="Toggle button color & compare transparency"
            onClick={() => setSelectedSemiTransparentWhite((currentValue) => !currentValue)}
            selected={selectedSemiTransparentWhite}/>
        </Box>
        <Image
        alt="Image to compare contrast between button color and background."
          color="rgb(231, 186, 176)"
          naturalHeight={751}
          naturalWidth={564}
          src="https://i.ibb.co/7bQQYkX/stock2.jpg"
        >
          <Box padding={2}>
          <Button
            color={selectedSemiTransparentWhite ? 'semiTransparentWhite' : 'white'}
            iconEnd="add-pin"
            text="Save this image"
          />
          </Box>
          <Box padding={2} position="absolute" bottom right>
            <Button
            color={selectedSemiTransparentWhite ? 'white' : 'semiTransparentWhite'}
            iconEnd="pin-hide"
            text="Hide this image"
            inline />
          </Box>
        </Image>
      </Box>
    </Flex>
  )
};

function Example() {
  const [selectedTransparent, setSelectedTransparent] = React.useState(false);
  const [selectedSemiTransparentWhite, setSelectedSemiTransparentWhite] = React.useState(false);
  return (
    <Flex>
      <Box column={4} padding={2}>
        <Box margin={3}>
          <Button
            text="Toggle text color & compare contrast"
            onClick={() => setSelectedTransparent((currentValue) => !currentValue)}
            selected={selectedTransparent}/>
        </Box>
        <Image
          alt="Image to compare contrast between text color and background."
          color="rgb(231, 186, 176)"
          naturalHeight={751}
          naturalWidth={564}
          src="https://i.ibb.co/7bQQYkX/stock2.jpg"
        >
          <Box padding={2}>
          <Button
            color={selectedTransparent ? 'transparentWhiteText' : 'transparent'}
            iconEnd="add-pin"
            text="Save this image"
          />
          </Box>
          <Box padding={2} position="absolute" bottom right>
            <Button
            color={selectedTransparent ? 'transparent' : 'transparentWhiteText'}
            iconEnd="pin-hide"
            text="Hide this image"
          />
          </Box>
        </Image>
      </Box>
      <Box column={4} padding={2}>
        <Box margin={3}>
          <Button
            text="Toggle button color & compare transparency"
            onClick={() => setSelectedSemiTransparentWhite((currentValue) => !currentValue)}
            selected={selectedSemiTransparentWhite}/>
        </Box>
        <Image
        alt="Image to compare contrast between button color and background."
          color="rgb(231, 186, 176)"
          naturalHeight={751}
          naturalWidth={564}
          src="https://i.ibb.co/7bQQYkX/stock2.jpg"
        >
          <Box padding={2}>
          <Button
            color={selectedSemiTransparentWhite ? 'semiTransparentWhite' : 'white'}
            iconEnd="add-pin"
            text="Save this image"
          />
          </Box>
          <Box padding={2} position="absolute" bottom right>
            <Button
            color={selectedSemiTransparentWhite ? 'white' : 'semiTransparentWhite'}
            iconEnd="pin-hide"
            text="Hide this image"
            inline />
          </Box>
        </Image>
      </Box>
    </Flex>
  )
};

Width

<React.Fragment>
  <Box padding={2}>
    <Button text="Default inline button" />
  </Box>
  <Box padding={2}>
    <Button fullWidth text="Full-width button" />
  </Box>
</React.Fragment>

<React.Fragment>
  <Box padding={2}>
    <Button text="Default inline button" />
  </Box>
  <Box padding={2}>
    <Button fullWidth text="Full-width button" />
  </Box>
</React.Fragment>

Icons

<Button iconEnd="download" text="Download CVS file" />

<Button iconEnd="download" text="Download CVS file" />

Selected state

function Example() {
  const [selected, setSelected] = React.useState(false);
  return (
    <Button
      selected={selected}
      onClick={() => {setSelected(!selected)}}
      text={selected ? "Selected" : "Deselected"}
    />
  );
}

function Example() {
  const [selected, setSelected] = React.useState(false);
  return (
    <Button
      selected={selected}
      onClick={() => {setSelected(!selected)}}
      text={selected ? "Selected" : "Deselected"}
    />
  );
}

ref

function ButtonPopoverExample() {
  const [selected, setSelected] = React.useState(false);

  const anchorRef = React.useRef(null);

  return (
    <React.Fragment>
      <Button
        onClick={() => setSelected(!selected)}
        ref={anchorRef}
        selected={selected}
        text={selected ? "Hide Popover" : "Show Popover"}
      />
      {selected && (
        <Popover
          anchor={anchorRef.current}
          idealDirection="right"
          onDismiss={() => setSelected(false)}
          shouldFocus={false}
        >
          <Box padding={3}>
            <Text weight="bold">This is a Button with an anchor ref to a Popover component</Text>
          </Box>
        </Popover>
      )}
    </React.Fragment>
  );
}

function ButtonPopoverExample() {
  const [selected, setSelected] = React.useState(false);
  const anchorRef = React.useRef(null);
  return (
    <React.Fragment>
      <Button
        onClick={() => setSelected(!selected)}
        ref={anchorRef}
        selected={selected}
        text={selected ? "Hide Popover" : "Show Popover"}
      />
      {selected && (
        <Popover
          anchor={anchorRef.current}
          idealDirection="right"
          onDismiss={() => setSelected(false)}
          shouldFocus={false}
        >
          <Box padding={3}>
            <Text weight="bold">This is a Button with an anchor ref to a Popover component</Text>
          </Box>
        </Popover>
      )}
    </React.Fragment>
  );
}

Accessibility: label

function AccessibilityExample() {
  const [selected, setSelected] = React.useState(false);

  return (
    <Button
      accessibilityLabel={selected ? "Unfollow Alberto on Pinterest" : "Follow Alberto on Pinterest"}
      onClick={() => setSelected(!selected)}
      selected={selected}
      text={selected ? "Unfollow" : "Follow"}        />
  );
}

function AccessibilityExample() {
  const [selected, setSelected] = React.useState(false);
  return (
    <Button
      accessibilityLabel={selected ? "Unfollow Alberto on Pinterest" : "Follow Alberto on Pinterest"}
      onClick={() => setSelected(!selected)}
      selected={selected}
      text={selected ? "Unfollow" : "Follow"}        />
  );
}

Accessibility: controls, expanded, & popup

function MenuButtonExample() {
  const [selected, setSelected] = React.useState(false);
  const anchorRef = React.useRef();

  return (
    <React.Fragment>
      <Box display="inlineBlock" ref={anchorRef}>
        <Button
          accessibilityControls="menu"
          accessibilityExpanded={selected}
          accessibilityHaspopup
          selected={selected}
          onClick={() => setSelected(!selected)}
          text="Menu"
        />
      </Box>

      {selected && (
        <Layer>
          <Popover
            anchor={anchorRef.current}
            idealDirection="down"
            onDismiss={() => setSelected(false)}
            positionRelativeToAnchor={false}
            size="md"
          >
            <Box id="menu" direction="column" display="flex" padding={2}>
              <Box padding={2}>
                <Text weight="bold">
                  Option 1
                </Text>
              </Box>
              <Box padding={2}>
                <Text weight="bold">
                  Option 2
                </Text>
              </Box>
            </Box>
          </Popover>
        </Layer>
      )}
    </React.Fragment>
  );
}

function MenuButtonExample() {
  const [selected, setSelected] = React.useState(false);
  const anchorRef = React.useRef();
  return (
    <React.Fragment>
      <Box display="inlineBlock" ref={anchorRef}>
        <Button
          accessibilityControls="menu"
          accessibilityExpanded={selected}
          accessibilityHaspopup
          selected={selected}
          onClick={() => setSelected(!selected)}
          text="Menu"
        />
      </Box>
      {selected && (
        <Layer>
          <Popover
            anchor={anchorRef.current}
            idealDirection="down"
            onDismiss={() => setSelected(false)}
            positionRelativeToAnchor={false}
            size="md"
          >
            <Box id="menu" direction="column" display="flex" padding={2}>
              <Box padding={2}>
                <Text weight="bold">
                  Option 1
                </Text>
              </Box>
              <Box padding={2}>
                <Text weight="bold">
                  Option 2
                </Text>
              </Box>
            </Box>
          </Popover>
        </Layer>
      )}
    </React.Fragment>
  );
}

Variants

This example illustrates two custom navigation implementations to externally control the link navigation behavior of Button: setting a default logic with OnLinkNavigationProvider and a custom component logic with the onClick prop.

If onNavigation prop is passed to OnLinkNavigationProvider, it's passed down to all children links and sets a custom default link navigation behavior. onLinkNavigation is a higher-order function: it takes named arguments (href and target) and returns an event handler function. In the component's onClick event handler, the onClick prop gets called first, followed by the function passed down by the OnLinkNavigationProvider.

Button's onClick prop is an event handler function. This callback takes 2 named parameters: 'event', the 'onClick' event, and disableOnNavigation, a callback function that disables any default custom navigation logic set by OnLinkNavigationProvider. disableOnNavigation is only accessible in OnLinkNavigationProvider's children components with link behavior.

In this example, Button has a parent OnLinkNavigationProvider setting a default custom navigation logic. We can compare three navigation behaviors: (a) the default Button behavior (by disabling the OnLinkNavigationProvider's inherited logic), (b) the default custom behavior set by OnLinkNavigationProvider and (c) a custom behavior set on Button.

onClick is used to disable the default custom logic set in OnLinkNavigationProvider and implement custom behavior at the component level. disableOnNavigation and customOnNavigation are both called first during the 'onClick' event.

If onNavigation is a custom hook function, it can contain complex logic, including React hooks, to perform side effects.

In this example, both onNavigation and customOnNavigation functions execute the following actions:

Disable the default link behavior
Show an alert message
Open a different URL in a new window

Both onNavigationClick, inside onNavigation, and onClick have event access to preventDefault(). It could also be used to stopPropagation().

Navigation controller:

Default navigation (disabled custom navigation set on OnLinkNavigationProvider)

Custom navigation set on OnLinkNavigationProvider

Custom navigation set on Button