---
name: Button
package: '@wordpress/components'
category: Actions
status: stable
canonical: 'https://system.automattic.design/components/button/'
storybook: 'https://wordpress.github.io/gutenberg/?path=/docs/components-button--docs'
github: 'https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/button'
figma: 'https://www.figma.com/design/jMgzw8IhsMC4gpMbMko4lv/WPDS--Gutenberg-22.3-?node-id=991-34617'
---

# Button

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

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

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `__next40pxDefaultSize` | `boolean` | `false` | Start opting into the larger default height that will become the default size in a future version. |
| `accessibleWhenDisabled` | `boolean` | `false` | Whether to keep the button focusable when disabled.<br>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.<br>Learn more about the [focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols) 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" \| "right"` | `'left'` | 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` | `"small" \| "default" \| "compact"` | `'default'` | The size of the button.<br>- `'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.<br>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.<br>The accepted values are:<br>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.<br>In most cases, it is recommended to also set the `accessibleWhenDisabled` prop to `true`. |
| `__experimentalIsFocusable` | `boolean` | `false` | 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`. |


## Examples

### Default

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

### Primary

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.

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

### Secondary

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

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

### Tertiary

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

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

### Link

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.

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

### Is Destructive

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

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

### Icon

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

### Grouped Icons

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