Button (legacy)

Caution

Legacy buttons will soon be deprecated. Please use the new button, icon button, link button, or link icon button. Migrate from legacy buttons using our codemod.

View the migration guide

Examples Code Usage Migration guide Changelog

Migrate to use the new button components

New button components with improved APIs are here. This migration guide will help you migrate from the old @atlaskit/button to the new button components which are more accessible, have better performance, and provide more safe customization/composition options.

Button: Typical button with text and optional icon
Link button: Link that appears like a button
Icon button: Button with only an icon

Link Icon button: Link that appears like an icon button
Link: For text-based links

Pressable: Low-level button component for custom buttons
Anchor: Low-level anchor component for custom links

Use the codemod for automated migration assistance

To streamline the experience, we provide a codemod to automate a majority of the work. It can be run with the following command in your terminal, replacing the path with a path to the file you'd like to migrate.

npx @atlaskit/codemod-cli -n migrate-to-new-buttons --extensions tsx --parser tsx <path-to-your-file-or-package>

This finds all eligible buttons and migrates them to use the new components, adding commented tasks for things you may want to review. (If this doesn't work, make sure your environment is set up properly.)

What do migrations look like using the codemod?

Here is what the codemod will do for all migratable buttons.

Code changes when migrating default buttons

+import Button from '@atlaskit/button/default/button';
-import Button from '@atlaskit/button';

const App = () => (
  <Button
    appearance="primary"
    onClick={onClick}
  >
    Default button
  </Button >
);

Code changes when migrating loading buttons

+import Button from '@atlaskit/button/default/button';
-import { LoadingButton } from '@atlaskit/button';
import AddIcon from '@atlaskit/icon/glyph/add';

const App = () => (
-  <LoadingButton
+  <Button
    isLoading
    onClick={onClick}
  >
    Default button
+ </Button>
- </LoadingButton>
);

Code changes when migrating icon buttons

-import Button from '@atlaskit/button';
+import IconButton from '@atlaskit/button/icon/button';
import AddIcon from '@atlaskit/icon/glyph/add';

const App = () => (
-  <Button
+  <IconButton
-    iconBefore={<AddIcon label="more" />}
+    icon={AddIcon}
+    label="more"
    onClick={onClick}
  />
);

Code changes when migrating link buttons

-import Button from '@atlaskit/button';
+import LinkButton from '@atlaskit/button/link';

const App = () => (
-  <Button
+  <LinkButton
    href="/home"
  >
    Link button
-  </Button>
+  </LinkButton>
);

Tasks

Some buttons may require additional changes. The codemod will mark these for you with instructions on how to manually configure the new button. For example:

// TODO: (from codemod) Buttons with "component", "css" or "style" prop can't be automatically migrated with codemods. Please migrate it manually.

For details on each type of button and what the codemod will do for each one, view the Atlassian migration details (Atlassians only), (opens new window).

Visual changes

Some of the new buttons have minor visual changes that can impact VR tests. In particular, some buttons with icons have slight visual changes that impact tests. These icon spacing changes were intentional to improve the look and feel of the icon buttons.

Legacy button imported from @atlaskit/button@17.2.1 or an earlier version has a wider padding around the icon:

New button:

DOM element changes

Buttons with only icons and no visible labels need accessible labels. The legacy Button component supports this through the button aria-label attribute or the label prop on the icon component.

In new icon buttons, we have added a label prop which is required. This is rendered as content inside the icon button using visually hidden. The text is visually hidden, but still functions in all ways as regular text on a page. This means it is translatable, and readable by screenreaders.

What buttons can't be migrated automatically yet?

These buttons are still being developed and reviewed in the new designs, or they just can't be migrated automatically yet. Here's what to do in these situations:

Old button property	What to do
`appearance` set to `link` or `subtle link` on non-link buttons	Consider using semantically correct buttons and links instead, or the new Link component or Anchor primitive.
`style` or `css` props	Consider using Pressable to build custom buttons with Atlassian Design System styling.
`component` prop	Buttons using `component` prop for routing can be migrated to the new link button.
`overlay` prop	The `overlay` prop has been removed in new buttons. It only existed in legacy buttons to support loading spinners, which can be achieved in the new button using the `isLoading` prop.

Not all old buttons have a 1:1 replacement in the new components. We're still working to cover all valid uses in the new APIs. For now, we recommend migrating the buttons you can and waiting for an update on the ones you can't migrate yet.

If you have a button that can't be migrated or changed, keep using legacy buttons from @atlaskit/button for now, and monitor this page or the button changelogs for updates.

More information

Was this page helpful?

We use this feedback to improve our documentation.