Automattic Design System

Components

Button

Lets users take actions and make choices with a single click or tap.

import { Button } from '@wordpress/components';

View on Storybook

View in Figma

View source on GitHub

PropsPermalink to this section

NameDefaultDescription
__next40pxDefaultSizefalse

boolean

Start opting into the larger default height that will become the default size in a future version.

accessibleWhenDisabledfalse

boolean

Whether to keep the button focusable when disabled.

In most cases, it is recommended to set this to true. Disabling a control without maintaining focusability can cause accessibility issues, by hiding their presence from screen reader users, or by preventing focus from returning to a trigger element.

Learn more about the focusability of disabled controls in the WAI-ARIA Authoring Practices Guide.

children

ReactNode

The button’s children.

description

string

A visually hidden accessible description for the button.

icon

IconType | null | undefined

If provided, renders an Icon component inside the button.

iconPosition'left'

"left" | "right"

If provided with icon, sets the position of icon relative to the text.

iconSize

number

If provided with icon, sets the icon size. Please refer to the Icon component for more details regarding the default value of its size prop.

isBusy

boolean

Indicates activity while a action is being performed.

isDestructive

boolean

Renders a red text-based button style to indicate destructive behavior.

isPressed

boolean

Renders a pressed button style.

label

string

Sets the aria-label of the component, if none is provided. Sets the Tooltip content if showTooltip is provided.

shortcut

string | { display: string; ariaLabel: string; } | undefined

If provided with showTooltip, appends the Shortcut label to the tooltip content. If an object is provided, it should contain display and ariaLabel keys.

showTooltip

boolean

If provided, renders a Tooltip component for the button.

size'default'

"small" | "default" | "compact"

The size of the button.

  • 'default': For normal text-label buttons, unless it is a toggle button.
  • 'compact': For toggle buttons, icon buttons, and buttons when used in context of either.
  • 'small': For icon buttons associated with more advanced or auxiliary features.

If the deprecated isSmall prop is also defined, this prop will take precedence.

text

string

If provided, displays the given text inside the button. If the button contains children elements, the text is displayed before them.

tooltipPosition

"top" | "middle" | "bottom" | "top center" | "top left" | "top right" | "middle center" | "middle left" | "middle right" | "bottom center" | "bottom left" | "bottom right" | "top center left" | "top center right" | "top center top" | "top center bottom" | "top left left" | "top left right" | "top left top" | "top left bottom" | "top right left" | "top right right" | "top right top" | "top right bottom" | "middle center left" | "middle center right" | "middle center top" | "middle center bottom" | "middle left left" | "middle left right" | "middle left top" | "middle left bottom" | "middle right left" | "middle right right" | "middle right top" | "middle right bottom" | "bottom center left" | "bottom center right" | "bottom center top" | "bottom center bottom" | "bottom left left" | "bottom left right" | "bottom left top" | "bottom left bottom" | "bottom right left" | "bottom right right" | "bottom right top" | "bottom right bottom"

If provided with showTooltip, sets the position of the tooltip. Please refer to the Tooltip component for more details regarding the defaults.

variant

"link" | "primary" | "secondary" | "tertiary"

Specifies the button’s style.

The accepted values are:

  1. 'primary' (the primary button styles)
  2. 'secondary' (the default button styles)
  3. 'tertiary' (the text-based button styles)
  4. 'link' (the link button styles)
disabled

boolean

Whether the button is disabled. If true, this will force a button element to be rendered, even when an href is given.

In most cases, it is recommended to also set the accessibleWhenDisabled prop to true.

__experimentalIsFocusablefalse

boolean

Whether to keep the button focusable when disabled.

isDefault

boolean

Gives the button a default style.

isLink

boolean

Gives the button a link style.

isPrimary

boolean

Gives the button a primary style.

isSecondary

boolean

Gives the button a default style.

isTertiary

boolean

Gives the button a text-based style.

isSmall

boolean

Decreases the size of the button.

describedBy

string

A visually hidden accessible description for the button.

href

string

If provided, renders a instead of button.

target

string

If provided with href, sets the target attribute to the a.

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = ( props ) => {
	return <Button __next40pxDefaultSize { ...props }></Button>;
};

PrimaryPermalink to this section

Primary buttons stand out with bold color fills, making them distinct from the background. Since they naturally draw attention, each layout should contain only one primary button to guide users toward the most important action.

const Primary = ( props ) => {
	return <Button __next40pxDefaultSize { ...props }></Button>;
};

SecondaryPermalink to this section

Secondary buttons complement primary buttons. Use them for standard actions that may appear alongside a primary action.

const Secondary = ( props ) => {
	return <Button __next40pxDefaultSize { ...props }></Button>;
};

TertiaryPermalink to this section

Tertiary buttons have minimal emphasis. Use them sparingly to subtly highlight an action.

const Tertiary = ( props ) => {
	return <Button __next40pxDefaultSize { ...props }></Button>;
};

Link buttons have low emphasis and blend into the page, making them suitable for supplementary actions, especially those involving navigation away from the current view.

const Link = ( props ) => {
	return <Button __next40pxDefaultSize { ...props }></Button>;
};

Is DestructivePermalink to this section

Use this variant for irreversible actions. Apply sparingly and only for actions with significant impact.

const IsDestructive = ( props ) => {
	return <Button __next40pxDefaultSize { ...props }></Button>;
};

IconPermalink to this section

const Icon = ( props ) => {
	return <Button __next40pxDefaultSize { ...props }></Button>;
};

Grouped IconsPermalink to this section

function GroupedIcons() {
	return (
		<GroupContainer>
			<Button __next40pxDefaultSize icon={ formatBold } label="Bold" />
			<Button
				__next40pxDefaultSize
				icon={ formatItalic }
				label="Italic"
			/>
			<Button __next40pxDefaultSize icon={ link } label="Link" />
		</GroupContainer>
	);
}