Buttons allow users to action tasks and navigate between states throughout the interface.
When to use a Button vs a Link
Buttons and links serve different purposes in the interface, and choosing the right one helps create clear, predictable, accessible experiences.
- Buttons are used for anything that triggers an event or performs an in-page action, e.g., submitting a form, opening a modal/drawer/dialog, saving changes, etc.
- Links are for navigation, e.g., moving to a different page, section, or external page. Use a link when the primary outcome is directing the user to a new location rather than performing an action within the current context.
Using the correct element helps users understand what will happen when they interact with it, improving usability, and accessibility. It also keeps implementation simple, since you won’t need to override default behavior to make the component work. If the Button or Link components don’t meet your needs, please reach out to #team-frontend-foundations-requests.
Anatomy
Anatomy summary lists and describes all the elements that exist within a component (including other components nested within).
|
Element |
Description |
Optional? |
|---|---|---|
|
1. 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 |
|
2. 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) |
|
3. 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 | ghost | 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
|
Option |
Description |
|---|---|
|
1. No icon |
A button may have no icon. |
|
2. Leading icon (iconLeading) |
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. |
|
3. Caret icon (expandCollapseIcon) |
A caret icon indicates that clicking the button will display a menu of additional, related actions. |
|
4. Leading and Caret icons |
A button may have both leading and caret icons. |
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.
|
Option |
Description |
|---|---|
|
1. 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). |
|
2. External* (see callout below for specific usage) |
Setting the external prop to true will automatically add the external link icon ( ArrowUpRightFromSquareIcon ) on the right hand side of the button text. |
|
3. 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. |
Styling a Link as a Button
In the rare case that you need to style a Link as a Button, such as directing to another internal page to add an Octopus entity like a Git Credential, use the Link variant of Button (see in Storybook).
Label
For best practices on creating concise, actionable labels that match our guidelines, read Microcopy Patterns → Button.
|
Option |
Description |
|---|---|
|
1. Show label |
The button’s label is visible and can be paired with a leading and/or caret icon. |
|
2. Hide label |
The button’s label can be hidden when only an icon is required for that action. |
|
3. Hover state for icon-only button |
If a button only displays an icon, show a Tooltip on hover to describe the button’s functionality. |
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.”
|
Option |
Description |
|---|---|
|
1. Has permissions |
Button is displayed in its rest state. |
|
2. Does not have permissions |
Button is disabled. The original button label should remain the same. On hover, a tooltip explains why the action is disabled. |
Component dependencies
This component is internally dependent on the following components:
Related components
Recommended reading
Other documentation that will help guide your thinking when working with this component.
Help and support