Buttons facilitate actions through an application. Priority and intent can be communicated by using different variants.
Overview
Buttons communicate actions that the user can take. It is important to note that the primary Button should be used sparingly as it utilizes the Brand color, which typically stands out in the interface. You will find Button usage guidelines in the Usage section of this documentation.
From the user experience perspective there is a difference between a Button and a Link. Buttons should be used when you are performing a task such as: “Create new,” “Submit,” “Upload,” etc. Link usage should be based on navigating to another place, such as: “View all”, "Profile", "Learn more" etc.
Usage
- User actions
Sample
<calcite-button>Add layer</calcite-button>
Best Practices
Make sure that Button usage is consistent across your application. This will ensure that the user has a consistent experience when taking actions. Avoid using different styles for primary action Buttons.


Recommendations
In cases where the component is loading and interaction should not be supported, such as a click event, use both the loading
and disabled
attributes. While the loading
attribute provides context the component is loading - interaction is not prevented. To display a loading state and disable interaction, use both attributes with one another.
Accessibility
Icons
Buttons can be used without text, when supplied with an icon or icons that represent actions a user can take, when accompanied with an label
attribute to provide context to assistive technologies:
<calcite-button icon-start="folder-plus" label="Add new folder"></calcite-button>
Links
If adding a link to the component with the href
attribute, it is strongly recommended to use a unique identifier with the label
attribute to distinguish individual links.
Different identifiers are important to distinguish where multiple instances are present so users can navigate through the application's links effectively. The label's context provides a purpose to assistive technologies and a larger audience. For instance:
<p>Null Island</p>
<calcite-button
href="https://www.arcgis.com/apps/mapviewer/index.html?marker=0;0;4326;Null Island;;¢er=0;0&level=6"
icon-end="launch"
label="Open Null Island in map"
target="_blank">
Open in map
</calcite-button>
<p>Mariana Trench</p>
<calcite-button
href="https://www.arcgis.com/apps/mapviewer/index.html?marker=142.1994;11.3498;4326;Mariana Trench;;¢er=142.1994;11.3498&level=6"
icon-end="launch"
label="Open Mariana Trench in map"
target="_blank">
Open in map
</calcite-button>
<p>Mount Everest</p>
<calcite-button
href="https://www.arcgis.com/apps/mapviewer/index.html?marker=86.9249;27.9886;4326;Mount Everest;;¢er=86.9249;27.9886&level=6"
icon-end="launch"
label="Open Mount Everest in map"
target="_blank">
Open in map
</calcite-button>
Keyboard navigation
Key | Function |
---|---|
Space | Presses the component. Note: If the href property is used, the component behaves like a link and can only be pressed with the Enter key. |
Enter | Presses the component. |
Tab | Moves focus in and out of the component. |
Tab and Shift | Moves focus in and out of the component. |
Writing and copy
API reference
Properties
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
alignment | alignment | Specifies the alignment of the component's elements. | "center" | "end" | "icon-end-space-between" | "icon-start-space-between" | "space-between" | "start" | "center" |
appearance | appearance | Specifies the appearance style of the component. | "outline" | "outline-fill" | "solid" | "transparent" | "solid" |
disabled | disabled | When true , interaction is prevented and the component is displayed with lower opacity. | boolean | false |
download | download | Prompts the user to save the linked URL instead of navigating to it. Can be used with or without a value: Without a value, the browser will suggest a filename/extension. | boolean | string | false |
form | form | The id of the form that will be associated with the component.
When not set, the component will be associated with its ancestor form element, if any. | string | |
href | href | Specifies the URL of the linked resource, which can be set as an absolute or relative path. | string | |
iconEnd | icon-end | Specifies an icon to display at the end of the component. | string | |
iconFlipRtl | icon-flip-rtl | Displays the iconStart and/or iconEnd as flipped when the element direction is right-to-left ("rtl" ). | "both" | "end" | "start" | |
iconStart | icon-start | Specifies an icon to display at the start of the component. | string | |
kind | kind | Specifies the kind of the component, which will apply to the border and background if applicable. | "brand" | "danger" | "inverse" | "neutral" | "brand" |
label | label | Accessible name for the component. | string | |
loading | loading | When true , a busy indicator is displayed and interaction is disabled. | boolean | false |
messageOverrides | Use this property to override individual strings used by the component. | { loading?: string; } | ||
name | name | Specifies the name of the component on form submission. | string | |
rel | rel | Defines the relationship between the href value and the current document. | string | |
round | round | When true , adds a round style to the component. | boolean | false |
scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
splitChild | split-child | Specifies if the component is a child of a calcite-split-button . | "primary" | "secondary" | boolean | false |
target | target | Specifies where to open the linked document defined in the href property. | string | |
type | type | Specifies the default behavior of the component. | string | "button" |
width | width | Specifies the width of the component. [Deprecated] The "half" value is deprecated, use "full" instead. | "auto" | "full" | "half" | "auto" |
Slots
Name | Description |
---|---|
default (unnamed) | A slot for adding text. |
Styles
Name | Description |
---|---|
--calcite-button-background-color | Specifies the component's background color when appearance="solid" or appearance="outline-fill". |
--calcite-button-border-color | Specifies the component's border color when it has appearance="outline" or appearance="outline-fill". |
--calcite-button-corner-radius | Specifies the component's corner radius. |
--calcite-button-loader-color | Specifies the component's loader color. |
--calcite-button-shadow-color | Specifies the component's box-shadow color. |
--calcite-button-text-color | Specifies the component's text color. |
Methods
Name | Description | Signature |
---|---|---|
componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
setFocus | Sets focus on the component. | setFocus(): Promise<void> |