Button

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

2 samples
1
<calcite-button>Add layer</calcite-button>
v3.0.3

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.

Do Button Order and Size
Do place primary actions on the rightmost position when grouping Buttons (opposite for RTL languages)
Avoid Button Order and Size
Avoid placing primary actions on the left of other Buttons
Do Button Icons
Do use text labels to provide context.
Avoid Button Icons
Avoid using icon only Buttons when the icon's action is unclear.

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:

1
<calcite-button icon-start="folder-plus" label="Add new folder"></calcite-button>

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<p>Null Island</p>
<calcite-button
    href="https://www.arcgis.com/apps/mapviewer/index.html?marker=0;0;4326;Null Island;;&center=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;;&center=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;;&center=86.9249;27.9886&level=6"
    icon-end="launch"
    label="Open Mount Everest in map"
    target="_blank">
    Open in map
</calcite-button>

Keyboard navigation

KeyFunction
SpacePresses the component. Note: If the href property is used, the component behaves like a link and can only be pressed with the Enter key.
EnterPresses the component.
TabMoves focus in and out of the component.
Tab and ShiftMoves focus in and out of the component.

Writing and copy

Do Button Writing
Do use sentence case for Button text
Avoid Button Writing
Avoid using title case for Button, and avoid using punctuation
Do Button Actionable
Do make Button text actionable
Avoid Button Actionable
Avoid making Button text unclear
Do Button Concise
Do make Button text concise
Avoid Button Concise
Avoid making Button text long or difficult to read, and avoid making Button text specific to a selection

API reference

Properties

PropertyAttributeDescriptionTypeDefault
alignmentalignmentSpecifies the alignment of the component's elements."center" | "end" | "icon-end-space-between" | "icon-start-space-between" | "space-between" | "start""center"
appearanceappearanceSpecifies the appearance style of the component."outline" | "outline-fill" | "solid" | "transparent""solid"
disableddisabledWhen true, interaction is prevented and the component is displayed with lower opacity.booleanfalse
downloaddownloadPrompts 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 | stringfalse
formformThe 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
hrefhrefSpecifies the URL of the linked resource, which can be set as an absolute or relative path.string
iconEndicon-endSpecifies an icon to display at the end of the component.string
iconFlipRtlicon-flip-rtlDisplays the iconStart and/or iconEnd as flipped when the element direction is right-to-left ("rtl")."both" | "end" | "start"
iconStarticon-startSpecifies an icon to display at the start of the component.string
kindkindSpecifies the kind of the component, which will apply to the border and background if applicable."brand" | "danger" | "inverse" | "neutral""brand"
labellabelAccessible name for the component.string
loadingloadingWhen true, a busy indicator is displayed and interaction is disabled.booleanfalse
messageOverridesUse this property to override individual strings used by the component.{ loading?: string; }
namenameSpecifies the name of the component on form submission.string
relrelDefines the relationship between the href value and the current document.string
roundroundWhen true, adds a round style to the component.booleanfalse
scalescaleSpecifies the size of the component."l" | "m" | "s""m"
splitChildsplit-childSpecifies if the component is a child of a calcite-split-button."primary" | "secondary" | booleanfalse
targettargetSpecifies where to open the linked document defined in the href property.string
typetypeSpecifies the default behavior of the component.string"button"
widthwidthSpecifies the width of the component. [Deprecated] The "half" value is deprecated, use "full" instead."auto" | "full" | "half""auto"

Slots

NameDescription
default (unnamed)A slot for adding text.

Styles

NameDescription
--calcite-button-background-colorSpecifies the component's background color when appearance="solid" or appearance="outline-fill".
--calcite-button-border-colorSpecifies the component's border color when it has appearance="outline" or appearance="outline-fill".
--calcite-button-corner-radiusSpecifies the component's corner radius.
--calcite-button-loader-colorSpecifies the component's loader color.
--calcite-button-shadow-colorSpecifies the component's box-shadow color.
--calcite-button-text-colorSpecifies the component's text color.

Methods

NameDescriptionSignature
componentOnReadyCreate a promise that resolves once component is fully loaded.componentOnReady(): Promise<void>
setFocusSets focus on the component.setFocus(): Promise<void>

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close