Button

<Button variant="primary">
  ✊ Action
</Button>

A Button communicates that users can trigger an action. Places you’d use a Button include:

• Submitting a form
• Closing a modal
• Moving to the next step in a flow

A Button can contain an icon and/or text. See Icon Buttons for detailed guidelines.

TL;DR If pressing the trigger results in a URL change, or that resultant page makes sense as a whole new browser tab use an Anchor element. Everything else is a Button.

It may not be immediately obvious but the semantic distinction between an anchor and Button HTML element is extremely important to learn. Without realising it the decision can cause significant usability problems due to the in-built behaviours, interactions and expectations that come with each.

For example, an anchor element will perform its action when clicked and when the enter key is pressed. A Button element will perform its action when clicked and when the enter and spacebar keys are pressed. When holding the control or command key an anchor will open a new browser tab, a Button will not.

You should:

• Use an Anchor when you are navigating the user to a new page or place on the page
• Use a Button when the user is performing an action. An action always happens on the same page as the trigger

If you need to link to content, you can use our Anchor component.

For accessibility, the distinction becomes even more important, especially for those who are using Assistive Technology (A.T.) such as screen readers and dictation software. Here are some quick tips:

• Correctly choosing between an anchor or Button element will help inform A.T. users what will happen next. Will I be taken to an entirely new page or will something happen on the current page?
• Choose Button text that clearly describes the action that is about to happen
• Don’t repeat the same Button text on the same page. Try not to have 20 “edit” Buttons, add clarifying text, even if it’s visually hidden, to fully describe the action. E.g. “edit home address”, “add new phone number”
• Don’t communicate with color alone. When choosing a destructive Button, make sure the Button text also indicates the action is destructive
• Use anchors that look like Buttons sparingly. Voice dictation users may encounter issues when trying to activate them. A user may say, “Click the read more Button”, but the dictation software won’t respond since it can’t tell what the anchor looks like visually. Use an alternative where possible, such as an anchor with an icon or with a larger font size.

<Stack orientation="horizontal" spacing="space30">
  <Button variant="primary">
    ✊ Action
  </Button>
  <Button variant="secondary">Action</Button>
  <Button variant="destructive">Action</Button>
  <Button variant="destructive_secondary">Action</Button>
  <Button variant="primary" size="small">
    Action
  </Button>
  <Button variant="secondary" size="small">
    Action
  </Button>
  <Button variant="destructive" size="small">
    Action
  </Button>
  <Button variant="destructive_secondary" size="small">
    Action
  </Button>
  <Button variant="link">Action</Button>
  <Button variant="destructive_link">Action</Button>
  <Button variant="reset" size="reset">
    Action
  </Button>
  <Button variant="primary_icon" size="reset">
    <PlusIcon decorative={false}  title="Add to cart" />
  </Button>
  <Button variant="secondary_icon" size="reset">
    <PlusIcon decorative={false} title="close" />
  </Button>
  <Button variant="destructive_icon" size="reset">
    <PlusIcon decorative={false} title="remove" />
  </Button>
</Stack>

Use a primary Button to indicate the most prominent action a customer would make on a screen. It should be a safe and if possible, reversible action without much cost.

Try to use only one primary Button on a screen. Using multiple might be distracting.

<Button variant="primary">
  Save
</Button>

The secondary Button is the most frequently used Button.

Use a secondary Button to indicate an action that should be easy for a customer to make but isn’t the most prominent on a screen. It should be a safe and if possible, reversible action without much cost.

<Button variant="secondary">
  Cancel
</Button>

A destructive secondary Button indicates a destructive action, such as “Delete” or “Remove”, that might be difficult to reverse. If possible, give users the ability to undo the action, or at least, confirm the action.

<Button variant="destructive_secondary">
  Delete
</Button>

Use a destructive primary Button for the most prominent action a customer would make on a screen if that action is destructive and could be difficult to reverse.

<Button variant="destructive">
  Delete
</Button>

Use Link-style Buttons when other types of Buttons may be too distracting.

<Stack orientation="horizontal" spacing="space30">
  <Button variant="link">Edit</Button>
  <Button variant="destructive_link">
    Delete
  </Button>
</Stack>

To make a Toggle Button, set the pressed attribute to either true or false. The variant must be either secondary, secondary_icon, or destructive_secondary.

Use a Toggle Button when the button controls a binary state. It can contain text or an icon.

Toggle Buttons use the aria-pressed attribute and color to communicate the state of the button. The icon can change based on the state, but the text should not. For example, if it is a follow button, the text should not change from "follow" to "unfollow" when the user clicks it.

const ToggleButtons = () => {
  const [followPressed, setFollowPressed] = React.useState(false);
  const [boldPressed, setBoldPressed] = React.useState(false);
  const [pausePressed, setPausePressed] = React.useState(true);
  const [destructivePressed, setDestructivePressed] = React.useState(true)

return (
  <Box display="flex" flexDirection="row" columnGap="space60">
    <Button variant="secondary" pressed={followPressed} onClick={() => setFollowPressed(!followPressed)}>
      {followPressed ? <CheckboxCheckIcon decorative /> : <PlusIcon decorative />}
      Follow
    </Button>
    <Button variant="secondary_icon" size="icon" pressed={boldPressed} onClick={() => setBoldPressed(!boldPressed)}>
      <BoldIcon decorative={false} title="Bold" />
    </Button>
    <Button variant="secondary" size="circle" pressed={pausePressed} onClick={() => setPausePressed(!pausePressed)}>
      <ScreenReaderOnly>Pause</ScreenReaderOnly>
      {pausePressed ? <PlayIcon decorative /> : <PauseIcon decorative />}
    </Button>
    <Button variant="destructive_secondary" size="icon" pressed={destructivePressed} onClick={() => setDestructivePressed(!destructivePressed)}>
      <BoldIcon decorative={false} title="Destructive" />
    </Button>
  </Box>
); };

render(<ToggleButtons />);

Buttons that navigate the user can only be represented by the primary and secondary variants. When this is used, it must be accompanied by an arrow pointing to the right or an external link icon after the text. The icons help to indicate that the action performed on click is a navigation. These Button types do not have disabled or loading states, as anchors cannot be in those states.

To create a Button-styled anchor, use the Button component and add the as="a" prop so that it is rendered as an anchor semantically, while maintaining Button styling.

Note: The same guidance applies for any action deemed "primary"; use only one per page.

<Stack orientation="horizontal" spacing="space30">
  <Button as="a" href="#" variant="primary">
    Button as anchor (internal link)
  </Button>
  <Button as="a" href="https://twilio.com" variant="secondary">
    Button as anchor (external link)
  </Button>
</Stack>

Use small Buttons sparingly, only when needed for vertical density. Guidelines for using variants in small Buttons are the same as in their default size.

<Stack orientation="horizontal" spacing="space30">
  <Button variant="primary" size="small">
    Save
  </Button>
  <Button variant="secondary" size="small">
    Cancel
  </Button>
  <Button variant="destructive" size="small">
    Delete
  </Button>
  <Button variant="destructive_secondary" size="small">
    Delete
  </Button>
</Stack>

Use rounded small Buttons sparingly, only when needed for vertical density and visual differentiation. Guidelines for using variants in rounded small Buttons are the same as in their default size.

<Stack orientation="horizontal" spacing="space30">
  <Button variant="primary" size="rounded_small">
    New messages
    <ArrowDownIcon decorative />
  </Button>
  <Button variant="secondary" size="rounded_small">
    5 Unread messages
  </Button>
  <Button variant="destructive" size="rounded_small">
    End chat
  </Button>
  <Button variant="destructive_secondary" size="rounded_small">
    Kick chat participant
  </Button>
</Stack>

The reset Button is basically a primitive Button. The Button styles are reset, so styles won't interfere with any child elements. This allows you to create your own Buttons using the Paste. This reset variant only resets styles. No other Button functionality is reset.

<Button variant="reset" size="reset">
  Edit
</Button>

Use primary icon, secondary icon, and destructive icon Button variants for buttons that, for a specific reason and purpose, can only have an icon in them, such as in compact UI situations. These variants do not have any border nor background color. When using these variants, use size="reset" in the Button component to remove any unnecessary padding. To change the size of an icon button, change the size of the Icon component itself.

Use an icon that can only convey a single action.

You can also create icon Buttons from other variants that have background colors and borders, like primary and secondary, by using that variant and changing the size of the Button component to size="icon" or size="icon_small".

Use icon-only Buttons sparingly. If there is any text in a button, do not use these icon-specific variants or sizes.

<Stack orientation="vertical" spacing="space60">
  <Stack orientation="horizontal" spacing="space60">
    <Button variant="primary_icon" size="reset">
      <PlusIcon decorative={false} size="sizeIcon10" title="Add to cart" />
    </Button>
    <Button variant="secondary_icon" size="reset">
      <CloseIcon decorative={false} size="sizeIcon40" title="close" />
    </Button>
    <Button variant="destructive_icon" size="reset">
      <MinusIcon decorative={false} size="sizeIcon80" title="remove" />
    </Button>
  </Stack>
  <Stack orientation="horizontal" spacing="space60">
    <Button variant="primary" size="icon">
      <PlusIcon decorative={false} title="Add to cart" />
    </Button>
    <Button variant="secondary" size="icon">
      <PlusIcon decorative={false} title="Add to cart" />
    </Button>
    <Button variant="destructive" size="icon">
      <PlusIcon decorative={false} title="Add to cart" />
    </Button>
    <Button variant="destructive_secondary" size="icon">
      <PlusIcon decorative={false} title="Add to cart" />
    </Button>
    <Button variant="primary" size="icon_small">
      <PlusIcon decorative={false} title="Add to cart" />
    </Button>
    <Button variant="secondary" size="icon_small">
      <PlusIcon decorative={false} title="Add to cart" />
    </Button>
    <Button variant="destructive" size="icon_small">
      <PlusIcon decorative={false} title="Add to cart" />
    </Button>
    <Button variant="destructive_secondary" size="icon_small">
      <PlusIcon decorative={false} title="Add to cart" />
    </Button>
  </Stack>
</Stack>

You can create circle Buttons from variants that have background colors and borders, like primary and secondary, by using that variant and changing the size of the Button component to size="circle" or size="circle_small".

Like icon buttons, circle buttons can only have an icon in them. To change the size of the Button, change the size of the Icon component itself.

Use an icon that can only convey a single action.

Use circular icon-only Buttons sparingly. If there is any text in a button, do not use a circle button.

<Stack orientation="horizontal" spacing="space60">
  <Button variant="primary" size="circle">
    <PlusIcon decorative={false} title="Add to cart" />
  </Button>
  <Button variant="secondary" size="circle">
    <PlusIcon decorative={false} title="Add to cart" />
  </Button>
  <Button variant="destructive" size="circle">
    <PlusIcon decorative={false} title="Add to cart" />
  </Button>
  <Button variant="destructive_secondary" size="circle">
    <PlusIcon decorative={false} title="Add to cart" />
  </Button>
  <Button variant="primary" size="circle_small">
    <PlusIcon decorative={false} title="Add to cart" />
  </Button>
  <Button variant="secondary" size="circle_small">
    <PlusIcon decorative={false} title="Add to cart" />
  </Button>
  <Button variant="destructive" size="circle_small">
    <PlusIcon decorative={false} title="Add to cart" />
  </Button>
  <Button variant="destructive_secondary" size="circle_small">
    <PlusIcon decorative={false} title="Add to cart" />
  </Button>
</Stack>

To internationalize a Button, simply pass different text as the children. If the Button is an anchor with an external link, you need to also pass the i18nExternalLinkLabel prop, with the value wrapped in parentheses. The value should be a translation of the phrase "link takes you to an external page", to indicate that the showExternal link will open the link in a new URL.

<Button
    variant='primary'
    as='a'
    href="https://www.nlg-npap.org/donate/"
    i18nExternalLinkLabel="(este enlace redirige a una página externa)"
>
  Soy enlace externo
</Button>

Use the loading state if the action doesn’t happen instantly. The Button is also disabled in this state.

However, the loading state may make an action appear to take longer than it does and doesn’t communicate what’s preventing the action from completing. Use it when you can’t move the user to the next state.

<Stack orientation="horizontal" spacing="space30">
  <Button variant="primary" loading>
    Submit
  </Button>
  <Button variant="secondary" loading>
    Submit
  </Button>
  <Button variant="destructive" loading>
    Submit
  </Button>
  <Button variant="destructive_secondary" loading>
    Submit
  </Button>
  <Button variant="primary" size="small" loading>
    Submit
  </Button>
  <Button variant="secondary" size="small" loading>
    Submit
  </Button>
  <Button variant="destructive" size="small" loading>
    Submit
  </Button>
  <Button variant="destructive_secondary" size="small" loading>
    Submit
  </Button>
  <Button variant="link" loading>
    Submit
  </Button>
  <Button variant="destructive_link" loading>
    Submit
  </Button>
  <Button variant="reset" size="reset" loading>
    Submit
  </Button>
</Stack>

Use the disabled state sparingly.

The customer shouldn't have to guess why a Button is disabled. It should be immediately obvious to the customer why a Button might be disabled (e.g., if it follows a single empty text field). Otherwise, show the Button in its default state, then provide helpful error text after it's pressed.

<Stack orientation="horizontal" spacing="space30">
  <Button variant="primary" disabled>
    Action
  </Button>
  <Button variant="secondary" disabled>
    Action
  </Button>
  <Button variant="destructive" disabled>
    Action
  </Button>
  <Button variant="destructive_secondary" disabled>
    Action
  </Button>
  <Button variant="primary" size="small" disabled>
    Action
  </Button>
  <Button variant="secondary" size="small" disabled>
    Action
  </Button>
  <Button variant="destructive" size="small" disabled>
    Action
  </Button>
  <Button variant="destructive_secondary" size="small" disabled>
    Action
  </Button>
  <Button variant="link" disabled>
    Action
  </Button>
  <Button variant="destructive_link" disabled>
    Action
  </Button>
  <Button variant="reset" size="reset" disabled>
    Action
  </Button>
</Stack>

In most cases, you’ll use a text-only Button.

Button text should:

• Use sentence case ("Sign up now", not "Sign Up Now").
• Avoid articles ("a", "the").
• Clearly indicate what will happen when a user selects it.
• Start with a verb, except for a common action like “Done.”
• Be concise without sacrificing clarity and user confidence.

In general, align Buttons to the direction of the text (for example, left-aligned in English) for easy scannability. When moving customers through a sequence, place the primary Button in the direction of the movement (e.g., a “Next” Button goes on the right in an English-language flow).

Pair text with an icon only if the icon clarifies the meaning of the Button. Use no more than one icon before text and one icon after text.