Button

Buttons allow users to perform actions within a surface. They can be used alone for immediate action, or as a trigger for another component, like Dropdown or Popover.

also known as Action, CTA

Figma:

Ready

Responsive:

Ready

Adaptive:

N/A

Props

Component props
Name	Type	Default
`text` Required	`string`	-
	Text to render inside the Button to convey the function and purpose of the Button.
`accessibilityControls`	`string`	-
	Specifies the `id` of an associated element (or elements) whose contents or visibility are controlled by Button so that screen reader users can identify the relationship between elements. See the Accessibility guidelines for details on proper usage.
`accessibilityExpanded`	`boolean`	-
	Indicates that Button hides or exposes collapsible components and expose whether they are currently expanded or collapsed. See the Accessibility guidelines for details on proper usage.
`accessibilityHaspopup`	`boolean`	-
	Indicates that a component controls the appearance of interactive popup elements, such as menu or dialog. See the Accessibility guidelines for details on proper usage.
`accessibilityLabel`	`string`	-
	Label for screen readers to announce Button. See the Accessibility guidelines for details on proper usage.
`backgroundContext`	`"light" \| "dark"`	`"light"`
	Indicates whether this component is hosted in a light or dark container. Used for improving focus ring color contrast.
`color`	`"gray" \| "red" \| "blue" \| "transparent" \| "semiTransparentWhite" \| "transparentWhiteText" \| "white"`	`"gray"`
	The background color of Button. See the color on white backgrounds variant and the color on color/image backgrounds variant
`dataTestId`	`string`	-
	Available for testing purposes, if needed. Consider better queries before using this prop.
`disabled`	`boolean`	`false`
	Indicates if Button is disabled. Disabled Buttons are inactive and cannot be interacted with. See the state variant for details on proper usage.
`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. See the width variant variant to learn more.
`iconEnd`	`unknown`	-
	An icon displayed after the text to help clarify the usage of Button. See the icon variant to learn more.
`iconStart`	`unknown`	-
	An icon displayed before the text to help clarify the Button usage.
`name`	`string`	-
	The name attribute specifies the name of the button element. The name attribute is used to reference form-data after the form has been submitted and for testing.
`onClick`	`(arg1: { event: React.MouseEvent<HTMLButtonElement> \| React.KeyboardEvent<HTMLButtonElement>; }) => void`	-
	Callback invoked when the user clicks (press and release) on Button with the mouse or keyboard.
`selected`	`boolean`	`false`
	Toggles between binary states: on/off, selected/unselected, open/closed. See the selected variant to learn more. See the state variant for details on proper usage.
`size`	`"sm" \| "md" \| "lg"`	`"md"`
	sm: 32px, md: 40px, lg: 48px See the size variant variant to learn more.
`tabIndex`	`-1 \| 0`	`0`
	Use "-1" to remove Button from keyboard navigation. See the Accessibility guidelines to learn more.
`type`	`"button" \| "submit"`	-
	Use "submit" if Button is used within or 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.

Best practices

Place primary Buttons to the right or top of other Button styles.

Don't

Place more than one primary Button per container/area.

Show the full text on Buttons. Buttons should be stacked when they cannot be displayed side by side.

Don't

Truncate the Button text. In rare instances where Buttons must remain on one line, truncate the text on the secondary Button before truncating on the primary Button.

Keep the Button text as simple and actionable as possible. Refer to the Button writing guidelines for more detail. If text is not sufficient for accessibility, refer to Accessibility guidelines for more detail.

Don't

Do not add icons to a Button to reinforce the text.

Use an IconButton + Tooltip next to the disabled Button if you need to explain why it is disabled.

Don't

Use a Tooltip on disabled Button, as it is not accessible for keyboard and screen reader users.

Accessibility

ARIA attributes

When Button text does not provide sufficient context about the Button’s behavior, supply a short, descriptive label for screen-readers using accessibilityLabel.
Texts like “Click here“, “Follow“, or “Shop“ can be confusing when a screen reader reads them out of context. In those cases, we must pass an alternative text with deeper context to replace the Button text, like “Follow Ryan” or “Shop Wedding Invitations”.

If Button is used as a control Button to show/hide a Popover-based component, we recommend passing the following ARIA attributes to assist screen readers:

accessibilityLabel: if present, read by screen readers read instead of the text prop.
accessibilityControls: informs the screen reader that Button controls the display of an anchored Popover-based component. It populates aria-controls.
accessibilityHaspopup: informs the screen reader that there’s a Popover-based component attached to Button. It populates aria-haspopup.
accessibilityExpanded: informs the screen reader whether the button-anchored Popover-based component is currently open or closed. It populates aria-expanded.

import { useRef, useState } from 'react';
import { Box, Button, Dropdown } from 'gestalt';

export default function ActionDropdownExample() {
  const [open, setOpen] = useState(false);
  const [selected, setSelected] = useState(null);
  const anchorRef = useRef(null);

  const onSelect = ({ item }) => setSelected(item);

  return (
    <Box display="flex" justifyContent="center" padding={8} width="100%">
      <Button
        ref={anchorRef}
        accessibilityControls="action-variant-dropdown-example"
        accessibilityExpanded={open}
        accessibilityHaspopup
        iconEnd="arrow-down"
        onClick={() => setOpen((prevVal) => !prevVal)}
        selected={open}
        size="lg"
        text={selected ? selected.label : 'Display'}
      />
      {open && (
        <Dropdown
          anchor={anchorRef.current}
          id="action-variant-dropdown-example"
          onDismiss={() => setOpen(false)}
        >
          <Dropdown.Item
            onSelect={onSelect}
            option={{ value: 'Cozy', label: 'Cozy' }}
            selected={selected}
          />
          <Dropdown.Item
            onSelect={onSelect}
            option={{ value: 'Comfy', label: 'Comfy' }}
            selected={selected}
          />
        </Dropdown>
      )}
    </Box>
  );
}

Color contrast in disabled state

Disabled Buttons do not need to pass color contrast guidelines.

From w3.org, 1.4.3 Contrast (Minimum): Text or images of text that are part of an inactive user interface component, that are pure decoration, that are not visible to anyone, or that are part of a picture that contains significant other visual content, have no contrast requirement.

Our current disabled Button implementation does fail to pass color contrast on accessibility integration tests. To exclude disabled buttons from the integration tests we recomment conditionally setting a data-test-id={ isDisabled ? "disabled-button-<name>" : undefined } and excluding them from the integration test.

On cypress-axe that can be achieved with cy.a11yCheck({ exclude: [['[data-test-id="disabled-button-submit"]']] })

`Localization`

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.


Avoid truncating Button text whenever possible. Refer to the 
              Button usage guidelines for more information

`Variants`

`State`


Default
 The typical state of a Button that represents it can be interacted with and is not in a selected state.
Disabled
Used to block user interaction such as hover, focus and click. Disabled Buttons are completely unreachable by a keyboard and screenreader, so do not attach Tooltips to disabled Buttons.
Selected
  When Button is used to toggle a boolean state or control the visibility of other elements (e.g. Dropdown), use the selected prop to indicate the current state.

import { Button, ButtonGroup, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <ButtonGroup>
        <Button
          accessibilityLabel="Save"
          color="red"
          selected={false}
          size="lg"
          text="Save"
        />
        <Button
          accessibilityLabel="Follow"
          selected={false}
          size="lg"
          text="Follow"
        />
      </ButtonGroup>
    </Flex>
  );
}

import { Button, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Button accessibilityLabel="Submit" disabled size="lg" text="Submit" />{' '}
    </Flex>
  );
}

import { Button, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Button
        accessibilityLabel="Following"
        selected
        size="lg"
        text="Following"
      />
    </Flex>
  );
}

`Size`

Button is available in 3 fixed sizes. The Button text has always a fixed size of 16px:



lg (48px)
 Large is the only size that should be used on Pinner surfaces. 
md (40px)
 Medium is used on more dense UI such as business surfaces or internal tools. 
sm (32px)
 Small should be used sparingly and only in places where the UI is very dense.

size="sm"

size="md"

size="lg"

`Color`


      
        On white backgrounds
        
      

Red (Primary)
 High emphasis, used for primary actions.
Gray (Secondary)
 Medium emphasis, used for secondary actions.
Transparent (Tertiary)
 Low emphasis when placed on dark/image backgrounds, used for tertiary actions in that context. Note, this treatment should be used with caution as it has potential color contrast issues.


      
        On color/image backgrounds
        
      

White (Primary)
   High emphasis when placed on color/image backgrounds, used for primary actions in that context.
Semi-transparent white (Secondary)
   Medium emphasis when placed on color/image backgrounds, used for secondary actions in that context.

On white backgrounds

import { Box, Button, Flex, Text } from 'gestalt';

export default function Example() {
  const bgColors = {
    gray: 'default',
    red: 'default',
    blue: 'default',
    transparent: 'default',
    transparentWhiteText: 'tertiary',
  };

  return (
    <Box padding={4}>
      <Flex gap={6} height="100%" width="100%" wrap>
        {['gray', 'red', 'blue', 'transparent', 'transparentWhiteText'].map(
          (color) => (
            <Flex key={color} direction="column" gap={2}>
              <Box
                alignItems="center"
                borderStyle="sm"
                color={bgColors[color]}
                display="flex"
                height={200}
                justifyContent="center"
                rounding={4}
                width={200}
              >
                <Button
                  backgroundContext={
                    color === 'transparentWhiteText' ? 'dark' : 'light'
                  }
                  color={color}
                  size="lg"
                  text="Save"
                />
              </Box>
              <Text size="200" weight="bold">
                color=&quot;{color}&quot;
              </Text>
            </Flex>
          )
        )}
      </Flex>
    </Box>
  );
}

On color/image backgrounds

import { Box, Button, Flex, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      gap={6}
      height="100%"
      justifyContent="center"
      width="100%"
      wrap
    >
      {['semiTransparentWhite', 'transparentWhiteText', 'white'].map(
        (color) => (
          <Flex key={color} direction="column" gap={2}>
            <Box
              alignItems="center"
              borderStyle="sm"
              dangerouslySetInlineStyle={{
                __style: {
                  backgroundImage: 'url("https://i.ibb.co/d0pQsJz/stock3.jpg")',
                },
              }}
              display="flex"
              height={200}
              justifyContent="center"
              rounding={4}
              width={200}
            >
              <Button color={color} size="lg" text="Save" />
            </Box>
            <Text size="200" weight="bold">
              color=&quot;{color}&quot;
            </Text>
          </Flex>
        )
      )}
    </Flex>
  );
}

`Width`


Inline (default)
 Inline is our default Button width.  The width of an inline Button is based on the length of its text. Use in most cases where you need a Button.
Full-width (fullWidth)
 Full-width Buttons can be used in narrower content areas when the text in the Button is close to full width in the content area. This is especially common to see in components such as BannerCallout and BannerUpsell at their smaller breakpoints.

import { Box, Button } from 'gestalt';

export default function Example() {
  return (
    <Box
      direction="column"
      display="flex"
      justifyContent="center"
      margin={4}
      width="100%"
    >
      <Box margin={2} width="100%">
        <Button
          color="red"
          fullWidth={false}
          iconEnd="arrow-down"
          onClick={({ event }) => event.preventDefault()}
          size="lg"
          text="Inline Button"
        />
      </Box>
      <Box margin={2} width="100%">
        <Button
          color="red"
          fullWidth
          iconEnd="arrow-down"
          onClick={({ event }) => event.preventDefault()}
          size="lg"
          text="Full-width Button"
        />
      </Box>
    </Box>
  );
}

`Icons`

iconEnd adds an icon after the Button text, and iconStart adds an icon before. Icons should only be used to visually reinforce a specific function or interaction of the Button. Menus and external links are a common use case. Use visit when linking to an external URL or arrow-down when displaying a Popover on click. Note that icons on Button are not accessible to screen readers.

Use Gestalt's ESLint rule to enforce the correct icons usage in Button. Learn more about the "button-icon-restrictions" rule

import { Button, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Button
        accessibilityLabel="Notifications"
        iconEnd="arrow-down"
        iconStart="bell"
        size="lg"
        text="Notifications"
      />
    </Flex>
  );
}

`Focus style`

import { Box, Button, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box height={150} width={150}>
        {' '}
        <Flex
          alignItems="center"
          height="100%"
          justifyContent="center"
          width="100%"
        >
          <Button
            accessibilityLabel="Save"
            backgroundContext="light"
            color="red"
            selected={false}
            size="lg"
            text="Save"
          />
        </Flex>
      </Box>
      <Box color="inverse" height={150} width={150}>
        <Flex
          alignItems="center"
          height="100%"
          justifyContent="center"
          width="100%"
        >
          <Button
            accessibilityLabel="Follow"
            backgroundContext="dark"
            selected={false}
            size="lg"
            text="Follow"
          />
        </Flex>
      </Box>
    </Flex>
  );
}

`Writing`

Do


If your object is already described on the screen, Buttons only need a verb (Example: Save).
If your object isn’t described on the screen, Buttons need a verb + the object (Example: Create Pin).
Use fewer than 3 words.
Use sentence case.

Don't


Do not use punctuation.

`Component quality checklist`

Component quality checklist
Quality item	Status	Status description
Figma Library	Ready	Component is available in Figma for web and mobile web.
Responsive Web	Ready	Component responds to changing viewport sizes in web and mobile web.

`Internal documentation`

PDocs available

ButtonLink Use ButtonLink when a link is needed instead of an action.



              ButtonGroup
When displaying multiple Buttons in a layout, use ButtonGroup to ensure consistent spacing and wrapping behavior.

              IconButton
Use IconButton when only an icon is needed instead of text.

              TapArea
Use TapArea to make non-button elements interactive, like an Image. This ensures the element interaction is accessible and uses Gestalt styles.

              Tabs
Tabs are intended for page-level navigation between multiple URLs.

Edit page on GitHub

Button

also known as Action, CTA

Props

Usage guidelines

Best practices

Accessibility

ARIA attributes

Color contrast in disabled state

Localization

Variants

State

Size

Color

On white backgrounds

On color/image backgrounds

Width

Icons

Focus style

Writing

Component quality checklist

Internal documentation

Related

`Localization`

`Variants`

`State`

`Size`

`Color`

`Width`

`Icons`

`Focus style`

`Writing`

`Component quality checklist`

`Internal documentation`

`Related`