Button

Buttons perform actions. One component covers both standard buttons and icon-only buttons, and six variants set how much emphasis a button carries.

Use a button when activating it changes something: submitting a form, creating a record, opening or closing a panel, running a command, or acting on an object in a row or toolbar.

Use a Link when activating it takes the reader somewhere and changes nothing. For an on/off state use a Toggle; for filtering and selection use a Sticker; when the action is one of several related choices, use a Dropdown Menu.

to changes what Button renders. A relative path renders a react-router-dom link; an absolute https:// URL renders an anchor that opens in a new tab, and target overrides that.

So the button-or-link decision is about how the destination should look and announce itself, not about which component can navigate. A button that navigates still reads as a button to a screen reader, which is why to suits actions that happen to have a URL, like “Open dashboard”, rather than links inside prose.

These six are in emphasis order, loudest first: primary, basic, outline, text, inverse, danger. The props table lists them in the order the type declares them, which carries no meaning.

Use inverse on a dark or colored surface, and onSecondaryBackground when a variant needs adjusting for a secondary background it was not drawn against.

A primary marks the single most important action available. Two of them in one view cancel each other out, because emphasis is relative: the reader cannot tell which one the screen is asking for. Pair a primary with outline or basic for the actions beside it, and drop to text inline or in dense areas.

Placement carries emphasis too. A primary in a position the eye reaches last does not read as the main action however it is styled.

danger is red fill, and red spends attention the rest of the page then cannot use. Keep it for outcomes that actually destroy something, and pair it with text naming the consequence.

isPending shows a spinner and disables the button, and it also fires on its own when onClick returns a promise, clearing once that promise settles. An async handler therefore gets pending state without being asked, so setting isPending by hand as well can leave the button disabled after the promise resolves.

type’s own description records why: many existing call sites depend on a button defaulting to submit, so the default was never changed to button. Inside a form, a button meant only to open a panel will submit that form unless you set type="button".

A standard button takes its accessible name from its visible text. An icon button has no text, so without aria-label it reaches a screen reader as an unnamed button. Name it for the action rather than the glyph: aria-label="Close", not aria-label="X icon". Pair it with width="icon", which sizes the button square to its own height.

Activation works with both Enter and Space. When you disable a button, prefer aria-disabled over removing it from the tab order, so the reason for the disabled state can still be reached.

A button label is the action it performs: “Create invoice”, “Download CSV”. Buttons are read out of context, in a toolbar or a row of icons or a screen reader’s list of elements, so a label that leans on the text beside it has no meaning where it is needed most.

A danger button names the thing it destroys. “Delete file” is recoverable knowledge at the moment of clicking; “Remove” is not.

Capitalization, punctuation and the rules that apply to every label are on Writing.