Split Buttons contain two buttons paired to provide different, but related actions.
Overview
Split Buttons house variations of the same action, and are a good utility to save space in the interface. Avoid relying on Split Buttons frequently or in groups.
Split Buttons carry the same color styles and appearances as Buttons.
Usage
Split Buttons can be used to accommodate many workflows. For instance:
| Primary | Secondary |
|---|---|
| Save | Save as |
| Download | Download with a specific file extension |
| Open | Open with a specific program |
| Edit | Edit with |
| Add layer | Type of layer |
Sample
Best practices
Below are important guidelines on using the Split Button component.
Accessibility
Keyboard navigation
| Key | Function |
|---|---|
Enter | If focused on the button, presses the component. If focused on the calcite-dropdown-group, expands or collapses the calcite-dropdown-items. |
Space | If focused on the button, presses the component. If focused on the calcite-dropdown-group, expands or collapses the calcite-dropdown-items. |
Tab | Moves focus to the calcite-dropdown-group. If the calcite-dropdown-group is focused, the focus will leave the component. |
Tab and Shift | Moves focus to the button. If the button is focused, the focus will leave the component. |
Refer to Dropdown for keyboard navigation.
Writing and copy
Refer to Button for writing and copy guidelines.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
| 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 |
| dropdownIconType | dropdown-icon-type | Specifies the icon used for the dropdown menu. | "caret" | "chevron" | "ellipsis" | "overflow" | "chevron" |
| dropdownLabel | dropdown-label | Accessible name for the dropdown menu. | string | |
| flipPlacements | Specifies the component's fallback slotted content placement when it's initial or specified placement has insufficient space available. | Array<"top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end" | "leading-start" | "leading" | "leading-end" | "trailing-end" | "trailing" | "trailing-start"> | ||
| href | href | Specifies the URL of the linked resource, which can be set as an absolute or relative path. | string | |
| kind | kind | Specifies the kind of the component, which will apply to border and background, if applicable. | "brand" | "danger" | "inverse" | "neutral" | "brand" |
| loading | loading | When true, a busy indicator is displayed on the primary button. | boolean | false |
| overlayPositioning | overlay-positioning | Determines the type of positioning to use for the overlaid content.
Using "absolute" will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.
"fixed" should be used to escape an overflowing parent container, or when the reference element's position CSS property is "fixed". | "absolute" | "fixed" | "absolute" |
| placement | placement | Determines where the component will be positioned relative to the container element. | "bottom" | "bottom-end" | "bottom-start" | "top" | "top-end" | "top-start" | "bottom-end" |
| primaryIconEnd | primary-icon-end | Specifies an icon to display at the end of the primary button. | string | |
| primaryIconFlipRtl | primary-icon-flip-rtl | Displays the primaryIconStart and/or primaryIconEnd as flipped when the element direction is right-to-left ("rtl"). | "both" | "end" | "start" | |
| primaryIconStart | primary-icon-start | Specifies an icon to display at the start of the primary button. | string | |
| primaryLabel | primary-label | Accessible name for the primary button. | string | |
| primaryText | primary-text | Text displayed in the primary button. | string | |
| rel | rel | Defines the relationship between the href value and the current document. | string | |
| scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
| target | target | Specifies where to open the linked document defined in the href property. | string | |
| 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 calcite-dropdown content. |
Events
| Name | Description | Behavior |
|---|---|---|
| calciteSplitButtonPrimaryClick | Fires when the primary button is clicked. | |
| calciteSplitButtonSecondaryClick | Fires when the dropdown menu is clicked. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
| setFocus | Sets focus on the component's first focusable element. | setFocus(): Promise<void> |