The Button element is allows users to action tasks and navigate between states or pages throughout the interface.
Anatomy
Anatomy summary lists and describes all the elements that exist within a component (including other components nested within).
|
Element |
Description |
Optional? |
|---|---|---|
|
iconLeading |
A supporting visual for the label so that the button is more noticeable and the action is more easily understood at a glance. |
Yes |
|
Label |
Very concise description of the action. For best practices on creating concise, actionable labels that match our guidelines, read Microcopy Patterns → Button. |
Yes (if replaced by an icon) |
|
Caret |
Indicates that clicking the button will display a menu of additional, related actions. |
Yes |
Variants
Variants contain different versions of the component depending on specific properties, such as state, size, colour, optional iconography, etc.
| Property | Values | Default |
|---|---|---|
| size Variant | medium | small | medium |
| type Variant | primary | secondary | tertiary | neutral | quiet | loud | destructive | primary |
| state Variant | rest | hover | pressed | focus | rest |
| hasIconLeading Boolean | true | false | true |
| icon InstanceSwap | ||
| showHideExpandCollapseIcon Boolean | true | false | false |
| ✏️ labelText Text | string | Label |
| showHideLabel Boolean | true | false | true |
| isDisabled Variant | false | true | false |
Type
There are 8 button types available:
- Primary
- Secondary
- Tertiary
- Neutral
- Quiet
- Loud
- Destructive
Size
There are two sizes available:
- Medium
- Small
Icon
There are options to use no icon, a leading icon (iconLeading), and/or a caret icon (expandCollapseIcon).
- A leading icon is a supporting visual for the button’s label. It makes the button more noticeable and the action more easily understood at a glance.
- A caret icon indicates that clicking the button will display a menu of additional, related actions.
Downloads and external link icons
The button has built in functionality in code for handling the visual representation of downloads and external links. You cannot change the download or external link icons.
- Download: Setting the isDownload prop to true will automatically add the download icon( ArrowDownToSquareIcon ) on the left hand side of the button text (the iconLeading option).
- External: Setting the external prop to true will automatically add the external link icon ( ArrowUpRightFromSquareIcon ) on the right hand side of the button text.
- Download & External Link: If the button is both a download and an external link ( isDownload and external are set to true) only the download icon will be shown. It is not necessary to have both icons.
Label
For best practices on creating concise, actionable labels that match our guidelines, read Microcopy Patterns → Button.
The button’s label can be hidden when only an icon is required for that action.
All variants
Behavior
Disabled due to permissions requirement
At times we may use a disabled state to indicate that an action is not available, because the user requires permissions to perform such action.
In this case:
- The original button label should remain the same.
- On hover, a tooltip should display the following copy to explain why the action is disabled: “You don’t have permissions to perform this action.”
Component dependencies
This component is internally dependent on the following components:
Recommended reading
Other documentation that will help guide your thinking when working with this component.
Help and support