No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

Button

A button triggers an action or event when activated.

See also:

MenuButton, ToggleButton, CompoundButton

Best Practices

Layout

  • For dialog boxes and panels, where people are moving through a sequence of screens, right-align buttons with the container.
  • For single-page forms and focused tasks, left-align buttons with the container.
  • Always place the primary button on the left, the secondary button just to the right of it.
  • Show only one primary button that inherits theme color at rest state. If there are more than two buttons with equal priority, all buttons should have neutral backgrounds.
  • Don't use a button to navigate to another place; use a link instead. The exception is in a wizard where "Back" and "Next" buttons may be used.
  • Don't place the default focus on a button that destroys data. Instead, place the default focus on the button that performs the "safe act" and retains the content (such as "Save") or cancels the action (such as "Cancel").

Content

  • Use sentence-style capitalization—only capitalize the first word. For more info, see Capitalization in the Microsoft Writing Style Guide.
  • Make sure it's clear what will happen when people interact with the button. Be concise; usually a single verb is best. Include a noun if there is any room for interpretation about what the verb means. For example, "Delete folder" or "Create account".

Default

Open in CodeSandbox
NameDescriptionDefaultControl
icon
Icon that renders either before or after the children as specified by the iconPosition prop.
ShorthandProps<{ as?: "span"; } & Pick<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "key" | keyof HTMLAttributes<...>> & { ...; } & { ...; }>
-
as
"a""button"
-
disabledFocusable

When set, allows the button to be focusable even when it has been disabled. This is used in scenarios where it is important to keep a consistent tab order for screen reader and keyboard users. The primary example of this pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.

boolean
false
appearance

A button can have its content and borders styled for greater emphasis or to be subtle. - 'primary': Emphasizes the button as a primary action. - 'outline': Removes background styling. - 'subtle': Minimizes emphasis to blend into the background until hovered or focused. - 'transparent': Removes background and border styling.

"outline""subtle""primary""transparent"
-
block
A button can fill the width of its container.
boolean
false
iconPosition
A button can format its icon to appear before or after its content.
"before""after"
"'before'"
shape
A button can be rounded, circular, or square.
"circular""square""rounded"
"'rounded'"
size
A button supports different sizes.
"small""medium""large"
"'medium'"

Stories

Shape

A button can be rounded, circular, or square.

Open in CodeSandbox

Appearance

  • (undefined): the button appears with the default style
  • primary: emphasizes the button as a primary action.
  • outline: removes background styling.
  • subtle: minimizes emphasis to blend into the background until hovered or focused
  • transparent: removes background and border styling.
Open in CodeSandbox

Icon

Button has an icon slot that, if specified, renders an icon either before or after the children, as specified by the iconPosition prop.

Open in CodeSandbox

Size

A button supports small, medium and large size. Default size is medium.

small

medium

large

Open in CodeSandbox

Disabled

A button can be disabled or disabledFocusable. disabledFocusable is used in scenarios where it is important to keep a consistent tab order for screen reader and keyboard users. The primary example of this pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.

Open in CodeSandbox

With Long Text

Text truncates after it hits the max width theme token value.

Open in CodeSandbox