On this page
Overview
Show code, CreateProject.tsx
Variants
- Primary
The main action of a group. One per group.
Tones: Neutral (brand blue), danger
- Secondary
Other actions.
Tones: Neutral
- Outline
Other actions on panes, dialogs and rows.
Tones: Neutral, danger
- Ghost
An application's chrome, such as a toolbar.
Tones: Neutral, danger
- Text
A link-like action, underlined where needed.
Tones: Neutral (link blue), danger
- Primary, accent
The main action, where it must stand apart from the brand blue around it.
Tones: Accent
Show code, Variants.tsx
Tones
Only the main action and links are blue: the neutral tone keeps each variant's own color, and the danger tone colors the label, or a primary's fill.
The three primary tones side by side, to compare them; a group still has one primary.
Show code, PrimaryTones.tsx
In a toolbar
A button without a variant of its own takes its container's, such as ghost in a toolbar.
Show code, QuietToolbar.tsx
Links
A button can go to a page instead of acting. Link says when a destination takes a button's shape.
Show code, ButtonLinks.tsx
Icons
A button takes an icon at its start or its end. An IconButton shows an icon alone, with a name for assistive technology.
Show code, Icons.tsx
Groups
A ButtonGroup joins related buttons in a row or a column.
- It joins buttons of one variant, or filled primary and secondary buttons, such as a split button.
- A split button's menu half takes the main half's variant and tone, and shows a chevron. The hairline between the halves then reads as one action with its options, not two actions.
- A group that mixes an outline, ghost or text button with another variant keeps them apart as whole pills, such as an outline Back beside a primary Next.
Show code, ConnectedButtons.tsx
Sizes
Small, medium and large, the control heights of the scale. A button without a size of its own takes its container's, such as small in a table cell, and beside a field it takes the field's.
Anatomy
Container
Start icon
Label
End icon
Show code, ButtonAnatomy.tsx
Behaviour
States
Hover, press, keyboard focus and disabled, for each variant.
- Keyboard focus draws a ring just outside the button. On an outline button the ring lies on its edge, which takes the ring's color; in dark, a primary button's ring takes the text color, apart from its soft blue fill.
- A text button's ring reaches a little past its label, which stays in line with the text around it.
Pending work
While its work runs, a spinner turns over the button and presses do nothing.
- The label and icons stay in place but transparent, so the button keeps its width and its name.
Show code, PendingAction.tsx
Confirm in place
ConfirmButton arms on the first press and acts on the second.
- Esc, leaving it or 4 seconds disarm it.
- Its armed label is short, with no question mark: the verb, or the verb and object, "Remove Sam".
Show code, ConfirmInPlace.tsx
Copy to the clipboard
CopyButton copies a value and shows Copied, or Couldn’t copy, for about two seconds.
Show code, CopyValue.tsx
Adapting to width
A label stays on one line and its button keeps its width, so let a row of buttons wrap: whole buttons move to the next line. Icon-only buttons keep their size.
- A button that fills its container and the buttons of a ButtonGroup can't move, so their labels wrap instead.
- On touch screens every button grows to the size of a fingertip.
- An icon button drawn smaller, such as a close button in a chip or a tab, reaches that size with the area it answers to.
Show code, NarrowActions.tsx
A button or a group can fill its container.
Show code, FillSidebar.tsx
Rules
A button says what will happen, and only the main action of a group stands out.
Use it when
- Starting an action, such as saving or sending
- A prominent destination, such as the next step of a flow
- A familiar action as an icon alone, in a dense placeIconButton
- An action that takes effect at once and can't be undoneConfirmButton
- Copying a value, such as a link or an IDCopyButton
- Related actions that belong togetherButtonGroup
Show code, OnePrimaryAction.tsx
Show code, SeveralPrimaryActions.tsx
Show code, ExplainWhatIsMissing.tsx
Show code, DisabledUntilValid.tsx
Labels
Start with a verb that says what will happen. When the outcome is known, put it in the label.
Show code, SayWhatWillHappen.tsx
Close and remove
An IconButton with the Close cross closes, dismisses or removes what it sits in.
- Name it Close, in the application's language.
- Where several sit together, name what each removes.
Show code, DismissTip.tsx
Beside others like it, each button names what it removes.
Show code, RemovePeople.tsx
Accessibility
| Key | Action |
|---|---|
| Tab, Shift+Tab | Moves to the next or previous button. |
| Enter | Activates a button or follows a link. |
| Space | Activates a button. |
| Esc | Disarms a ConfirmButton; hides a copy result. |