Button

To add the Button, LinkButton, or LoadingButton component to your app:

1
2
import { Button } from "@forge/react";

1
2
import { LinkButton } from "@forge/react";

1
2
import { LoadingButton } from "@forge/react";

Description

A button triggers an event or action. They let users know what will happen next.

Props

Button props

The Button accepts all shared props as well as an optional appearance prop.

LinkButton props

The LinkButton accepts all shared props (except for type) as well as the additional props below.

LoadingButton props

The LoadingButton accepts all shared props as well as an optional isLoading and appearance prop.

Examples

Default

Use default buttons for most actions that aren't the main call to action for a page or area. Default buttons are less prominent than primary buttons.

1
2
const ButtonDefaultExample = () => {
  return <Button>Default button</Button>;
};

Appearance

Primary

Use a primary button to call attention to a form submission or to highlight the most important call to action on a page. Primary buttons should only appear once per area, though not every screen needs a primary button.

1
2
const ButtonPrimaryExample = () => {
  return <Button appearance="primary">Primary button</Button>;
};

Subtle

Use a subtle button with a primary button for secondary actions, such as “Cancel.”

1
2
const ButtonSubtleExample = () => {
  return <Button appearance="subtle">Subtle button</Button>;
};

Warning

Warning buttons confirm actions that may cause a significant change or a loss of data.

Typically, warnings alert people of a problem that might happen if they proceed. These appearances are often found in confirmation modals.

1
2
const ButtonWarningExample = () => {
  return <Button appearance="warning">Warning button</Button>;
};

Danger

A danger button appears as a final confirmation for a destructive and irreversible action, such as deleting.

1
2
const ButtonDangerExample = () => {
  return <Button appearance="danger">Danger button</Button>;
};

Link Button

The default form of a link button.

1
2
const LinkButtonExample = () => {
  return <LinkButton href="https://atlassian.com/">Link button</LinkButton>;
};

Link Appearance

Use a link appearance for buttons that look and behave like inline text links.

1
2
const LinkButtonLinkExample = () => {
  return (
    <LinkButton appearance="link" href="/">
      Link appearance button
    </LinkButton>
  );
};

Subtle Link Appearance

Similar to a subtle button, but looks like a link. Use a subtle link button to avoid overwhelming a page with blue links.

Make sure designs have clear affordances for interactable areas and elements. Because there is no color affordance, this style of button relies on the context around it to show that it can be interacted with.

1
2
const ButtonSubtleLinkExample = () => {
  return (
    <LinkButton appearance="subtle-link" href="/">
      Subtle link appearance button
    </LinkButton>
  );
};

Disabled Link Button

Standard buttons use the disabled HTML attribute, however this doesn't exist for anchor <a> tags, so link buttons are disabled by adding aria-disabled="true", adding role="link" and removing the href attribute.

1
2
const LinkButtonDisabledExample = () => {
  return (
    <LinkButton href="https://atlassian.com/" appearance="primary" isDisabled>
      Disabled link button
    </LinkButton>
  );
};

States

Disabled

Set isDisabled to disable a button that shouldn't be actionable. The button will appear faded and won't respond to user interaction.

Disabled buttons can cause accessibility issues (disabled elements are not in the tab order) so wherever possible, avoid using isDisabled. Instead, use validation or other techniques to show users how to proceed.

1
2
const ButtonDisabledExample = () => {
  return (
    <Button appearance="primary" isDisabled>
      Disabled button
    </Button>
  );
};

Selected

Set isSelected to indicate the button is selected.

1
2
const ButtonSelectedExample = () => {
  return <Button isSelected>Selected button</Button>;
};

Loading

Use the loading button and set isLoading to indicate the button is loading. The button text is hidden and a spinner is shown in its place, while maintaining the width that it would have if the text were visible.

1
2
const ButtonLoadingExample = () => {
  return (
    <LoadingButton appearance="primary" isLoading>
      Loading button
    </LoadingButton>
  );
};

Spacing

Button spacing depends on the surrounding UI. Default spacing is used for most use cases, compact for tables, and none for breadcrumbs.

1
2
import { ButtonGroup, Button, LinkButton } from "@forge/react";

const ButtonPaddingExample = () => {
  return (
    <ButtonGroup>
      <Button appearance="primary">Default</Button>
      <Button appearance="primary" spacing="compact">
        Compact
      </Button>
      <LinkButton href="/" spacing="none" appearance="subtle-link">
        None
      </LinkButton>
    </ButtonGroup>
  );
};

Full Width

Buttons can expand to full width to fill the parent container. This is sometimes done in login forms.

1
2
const ButtonFullWidthExample = () => {
  return (
    <Button shouldFitContainer appearance="primary">
      Full width button
    </Button>
  );
};

Button with icon

Buttons may include an icon before or after the text label. Valid icons can be found in the Atlassian Design System Icon Library.

Extract the glyph segment of the icon's import to get the valid icon name to pass into iconBefore or iconAfter (eg. @atlaskit/icon/glyph/star-filled -> star-filled is a valid icon name).

Icon before

1
2
const ButtonIconBefore = () => {
  return (
    <Button
      appearance="primary"
      iconBefore="star-filled"
    >
      Icon before
    </Button>
  );
};

Icon after

1
2
const ButtonIconAfter = () => {
  return (
    <Button
      appearance="primary"
      iconAfter="star-filled"
    >
      Icon after
    </Button>
  );
};

Accessibility considerations

When using the Button, LinkButton, and LoadingButton components, we recommend keeping the following accessibility considerations in mind:

Avoid disabling buttons

Avoid disabling buttons, especially in forms. Instead, keep the button pressable, and use validation and errors to explain what needs to be done to proceed.

Disabled buttons don’t explain why the button isn’t usable. They also aren’t reachable in the tab order and don’t receive hover, focus, or click events, making them entirely inaccessible to some people.

Never put tooltips on disabled buttons

Tooltips can't be reached on all devices or by some assitive technologies, and they should never appear on elements that aren't interactable.

Things to consider before using a tooltip:

• Is this information essential to the user experience? If so, never hide it behind a tooltip. Tooltips aren’t easy to discover and aren’t accessible at all on mobile devices. If it isn’t essential information, consider if you need to show it at all.
• Is this information actionable? Being shown things that you can’t use without any next steps can be frustrating or confusing. Consider only showing UI that a user can interact with.
• If the information is still necessary or helpful, consider using helper text or other more accessible text that has the same content instead of a tooltip. This gives you more options to provide a link to a next step or another action.