Split-Button

This documentation is currently being revised and is in beta status. Content may still change.

This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

Synonyms: Split Button, Action Button with Menu, Dropdown Button

Description: The Split-Button is a two-part button consisting of a primary button for a main action and a secondary button for a context menu (Popover). The secondary button opens a dropdown menu with additional actions, while the primary button can optionally be configured for a specific main action. If no dedicated event handler is defined for the primary button, it also opens the menu.

Example

Standard Split-Button with context menu:

Variant

Tooltip Align

Icons

<KolSplitButton _label="Split Button" />

Accessibility

• The Split-Button requires a visible label via _label to be correctly recognized by screen readers.
• The dropdown menu is keyboard-accessible and is recognized by assistive technologies as an expandable element.
• The state of the menu (open/closed) should be clearly indicated through visual and semantic cues.
• _ariaExpanded can be used to communicate the current state of the menu to assistive technologies.
• _shortKey can be used to add keyboard shortcuts that are read aloud by screen readers.
• The _accessKey attribute allows the definition of key combinations for quick access.

Links and References

Usage

Keyboard Navigation

Key	Function
Tab	Focuses the Split-Button.
Enter	Activates the primary button or opens the menu (if configured).
Space	Opens the dropdown menu (secondary button).
Arrow Keys	Navigation in the dropdown menu when it is open.
Escape	Closes the dropdown menu.

Best Practices / Recommendations

• Use the Split-Button when you need both a primary action and additional related actions.
• Place the most important/frequent action in the primary button and alternatives in the menu.
• Use meaningful icons in the _icons property to make the function immediately understandable.
• Define an event handler for the primary button only if it should have a separate action — otherwise it also opens the menu.
• Limit the number of menu items to a manageable amount (typically 3–6 entries).
• Use variants like _variant="danger" for destructive actions to visually warn users.
• With _hideLabel you can visually hide the label and make it only visible as a tooltip and for screen readers.

Use Cases

• Download buttons with various file formats
• Edit menus with options such as Edit, Duplicate, Delete
• Quick actions in table rows (e.g. more-actions buttons)
• Media player controls with playback options
• Related actions in toolbars or navigation bars

Construction / Technical

Playground

Variant

Tooltip Align

Icons

<KolSplitButton _label="Split Button" />

Features (with Code)

Label and Basic Configuration

Minimum configuration for a functional Split-Button: _label.

<KolSplitButton _label="Split Button" />

Variants

The Split-Button supports various visual variants for different contexts:

Variant

<KolSplitButton _label="Split Button" _variant="primary" />

Available variants:

• normal: Default design
• primary: Primary / main action
• secondary: Secondary action
• tertiary: Tertiary / subtle action
• danger: Warning for destructive actions
• ghost: Subtle design without background
• custom: Custom styling via _custom-class

Icons and Label Styling

Icons can be added via _icons and the label can be hidden via _hideLabel:

Icons

<KolSplitButton _label="Split Button" />

Tooltip and Keyboard Shortcuts

Configure tooltip position and keyboard shortcuts:

Tooltip Align

<KolSplitButton _label="Split Button" />

Disabled State

The Split-Button can be disabled via _disabled:

<KolSplitButton _disabled={true} _label="Split Button" />

Events

For the handling of events or callbacks, see .

Event	Trigger	Value
click	Primary or secondary button is clicked	_value property
onMouseDown	A pointing device key is pressed while the pointer is inside the element	-

API

Overview

The SplitButton component can be used to display a two-part button. The primary button is typically used for a main action, while the secondary button opens a context menu (Popover) that contains additional actions.

Properties

Property	Attribute	Description	Type	Default
_accessKey	_access-key	Defines the key combination that can be used to trigger or focus the component's interactive element.	string | undefined	undefined
_ariaControls	_aria-controls	Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls)	string | undefined	undefined
_ariaDescription	_aria-description	Defines the value for the aria-description attribute.	string | undefined	undefined
_ariaExpanded	_aria-expanded	Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded)	boolean | undefined	undefined
_ariaSelected	_aria-selected	Defines whether the interactive element of the component is selected (e.g. role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected)	boolean | undefined	undefined
_customClass	_custom-class	Defines the custom class attribute if _variant="custom" is set.	string | undefined	undefined
_disabled	_disabled	Makes the element not focusable and ignore all events.	boolean | undefined	false
_hideLabel	_hide-label	Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it.	boolean | undefined	false
_icons	_icons	Defines the icon classnames (e.g. _icons="fa-solid fa-user").	KoliBriHorizontalIcons & KoliBriVerticalIcons | string | undefined	undefined
_label (required)	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).	string	undefined
_name	_name	Defines the technical name of an input field.	string | undefined	undefined
_on	--	Defines the callback functions for button events.	undefined | { onClick?: EventValueOrEventCallback<MouseEvent, StencilUnknown> | undefined; onMouseDown?: EventCallback<MouseEvent> | undefined; }	undefined
_role	_role	[DEPRECATED] We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future. Defines the role of the components primary element.	"tab" | "treeitem" | undefined	undefined
_shortKey	_short-key	Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud.	string | undefined	undefined
_tooltipAlign	_tooltip-align	Defines where to show the Tooltip preferably: top, right, bottom or left.	"bottom" | "left" | "right" | "top" | undefined	'top'
_type	_type	Defines either the type of the component or of the components interactive element.	"button" | "reset" | "submit" | undefined	'button'
_value	_value	Defines the value of the element.	boolean | null | number | object | string | undefined	undefined
_variant	_variant	Defines which variant should be used for presentation.	"custom" | "danger" | "ghost" | "normal" | "primary" | "secondary" | "tertiary" | undefined	'normal'

Methods

click

click() => Promise<void>

Clicks the primary interactive element inside this component.

Returns

Type: Promise<void>

closePopup() => Promise<void>

Closes the dropdown.

Returns

Type: Promise<void>

focus() => Promise<void>

Sets focus on the internal element.

Returns

Type: Promise<void>

getValue() => Promise<StencilUnknown>

Returns the current value.

Returns

Type: Promise<StencilUnknown>

Slots

Slot	Description
	Allows arbitrary HTML to be inserted into the dropdown.

---