Split Button | Calcite Design System

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.

Sample

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

Best practices

Below are important guidelines on using the Split Button component.

Do use text labels to provide context.

Avoid using icon only Split Buttons when the icon's action is unclear.

Accessibility

Key	Function
`Enter`	If focused on the button, presses the component. If focused on the `calcite-dropdown-group`, expands or collapses the `calcite-dropdown-item`s.
`Space`	If focused on the button, presses the component. If focused on the `calcite-dropdown-group`, expands or collapses the `calcite-dropdown-item`s.
`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.	`Extract<"outline" \| "outline-fill" \| "solid" \| "transparent", Appearance>`	`"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.	`string \| boolean`	`false`
dropdownIconType	dropdown-icon-type	Specifies the icon used for the dropdown menu.	`DropdownIconType`	`"chevron"`
dropdownLabel	dropdown-label	Accessible name for the dropdown menu.	`string`
flipPlacements		Specifies the component's fallback `placement` for slotted content when it's initial or specified `placement` has insufficient space available.	`FlipPlacement[]`
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.	`Extract<"brand" \| "danger" \| "inverse" \| "neutral", Kind>`	`"brand"`
loading	loading	When `true`, a busy indicator is displayed on the primary button.	`boolean`	`false`
overlayPositioning	overlay-positioning	Specifies the type of positioning to use for overlaid content, where: `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout, and `"fixed"` is used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.	`OverlayPositioning`	`"absolute"`
placement	placement	Determines where the component will be positioned relative to the container element.	`LogicalPlacement`	`"bottom-end"`
primaryIconEnd	primary-icon-end	Specifies an icon to display at the end of the primary button.	`IconName`
primaryIconFlipRtl	primary-icon-flip-rtl	Displays the `primaryIconStart` and/or `primaryIconEnd` as flipped when the element direction is right-to-left (`"rtl"`).	`FlipContext`
primaryIconStart	primary-icon-start	Specifies an icon to display at the start of the primary button.	`IconName`
primaryLabel	primary-label	Specifies an accessible name for the primary button.	`string`
primaryText	primary-text	Specifies the 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 component's size.	`Scale`	`"m"`
target	target	Specifies where to open the linked document defined in the `href` property.	`string`
topLayerDisabled	top-layer-disabled	When `true` and the component is `open`, disables top layer placement. Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components.	`boolean`	`false`
width	width	Specifies the width of the component. [Deprecated] The `"half"` value is deprecated, use `"full"` instead.	`Extract<Width, "auto" \| "half" \| "full">`	`"auto"`

Slots

Name	Description
default (unnamed)	A slot for adding `calcite-dropdown` content.

Styles

Name	Description
--calcite-split-button-background-color	Specifies the component's background color.
--calcite-split-button-background-color-hover	Specifies the component's background color when hovered.
--calcite-split-button-background-color-focus	Specifies the component's background color when focused.
--calcite-split-button-background-color-press	Specifies the component's background color when active.
--calcite-split-button-border-color	Specifies the component's border color.
--calcite-split-button-corner-radius	Specifies the component's corner radius.
--calcite-split-button-icon-color	Specifies the component's `iconStart` and `iconEnd` color.
--calcite-split-button-loader-color	Specifies the component's loader color.
--calcite-split-button-text-color	Specifies the component's text color.
--calcite-split-button-shadow	Specifies the component's shadow.
--calcite-split-button-divider-border-color	Specifies the component's divider border color.
--calcite-split-button-divider-color	Specifies the component's divider color.
--calcite-split-button-dropdown-width	Specifies the width of the component's dropdown.
--calcite-split-button-dropdown-background-color	Specifies the component's dropdown background color. *

Events

Name	Description	Behavior
calciteSplitButtonPrimaryClick	Fires when the primary button is clicked.	bubblescomposed
calciteSplitButtonSecondaryClick	Fires when the dropdown menu is clicked.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component's first focusable element.	`setFocus(options?: FocusOptions): Promise<void>`