Split-Button

Diese Dokumentation wird aktuell überarbeitet und befindet sich im Beta-Status. Inhalte können sich noch ändern.

Diese Komponente wird erneut auf Barrierefreiheit getestet. Der vollständige Test steht noch aus und kann erst nach einem abgeschlossenen Release erfolgen.

Synonyme: Geteilter Button, Action-Button mit Menü, Dropdown-Button

Beschreibung: Der Split-Button ist ein zweigeteilter Button, der aus einem primären Button für eine Hauptaktion und einem sekundären Button für ein Kontextmenü (Popover) besteht. Der Sekundär-Button öffnet ein Dropdown-Menü mit zusätzlichen Aktionen, während der Primär-Button optional für eine spezifische Haupt-Aktion konfiguriert werden kann. Wenn kein spezieller Event-Handler für den Primär-Button definiert ist, öffnet dieser ebenfalls das Menü.

Beispiel

Standard Split-Button mit Kontextmenü:

Variant

Tooltip Align

Icons

<KolSplitButton _label="Split-Button" />

Barrierefreiheit

• Der Split-Button benötigt ein sichtbares Label über _label, um von Screenreadern korrekt erkannt zu werden.
• Das Dropdown-Menü ist über Tastatur bedienbar und wird von assistiven Technologien als erweiterbares Element erkannt.
• Der Status des Menüs (geöffnet/geschlossen) sollte durch visuelle und semantische Indikatoren deutlich gemacht werden.
• Mit _ariaExpanded kann der aktuelle Zustand des Menüs für assistive Technologien kommuniziert werden.
• Mit _shortKey können Tastaturkürzel hinzugefügt werden, die von Screenreadern vorgelesen werden.
• Das _accessKey Attribut erlaubt die Definition von Tastenkombinationen für schnellen Zugriff.

Links und Referenzen

Verwendung

Tastatursteuerung

Taste	Funktion
Tab	Fokussiert den Split-Button.
Enter	Aktiviert den primären Button oder öffnet das Menü (falls konfiguriert).
Leertaste	Öffnet das Dropdown-Menü (sekundärer Button).
Pfeil-Tasten	Navigation im Dropdown-Menü wenn dieses offen ist.
Escape	Schließt das Dropdown-Menü.

Best Practices / Empfehlungen

• Verwenden Sie den Split-Button, wenn Sie sowohl eine Primäraktion als auch zusätzliche verwandte Aktionen benötigen.
• Platzieren Sie die wichtigste/häufigsten Aktion im Primär-Button und Alternativen ins Menü.
• Nutzen Sie aussagekräftige Icons in der _icons Eigenschaft, um die Funktion auf den ersten Blick verständlich zu machen.
• Definieren Sie einen Event-Handler für den Primär-Button nur, wenn dieser eine separate Aktion haben soll – ansonsten öffnet er ebenfalls das Menü.
• Begrenzen Sie die Anzahl der Menü-Elemente auf eine übersichtliche Menge (typischerweise 3–6 Einträge).
• Verwenden Sie Varianten wie _variant="danger" für destruktive Aktionen, um Nutzer:innen visuell zu warnen.
• Mit _hideLabel können Sie das Label visuell verstecken und nur als Tooltip und für Screenreader sichtbar machen.

Anwendungsfälle

• Download-Buttons mit verschiedenen Dateiformaten
• Bearbeitungsmenüs mit Optionen wie Bearbeiten, Duplizieren, Löschen
• Schnellaktionen in Tabellenzeilen (z. B. Mehr-Aktionen-Buttons)
• Media-Player-Steuerelemente mit Wiedergabeoptionen
• Verwandte Aktionen in Toolbars oder Navigationsleisten

Konstruktion / Technik

Playground

Variant

Tooltip Align

Icons

<KolSplitButton _label="Split-Button" />

Funktionalitäten (mit Code)

Label und grundlegende Konfiguration

Mindestangaben für einen funktionsfähigen Split-Button: _label.

<KolSplitButton _label="Split-Button" />

Varianten

Der Split-Button unterstützt verschiedene visuelle Varianten für unterschiedliche Kontexte:

Variant

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

Verfügbare Varianten:

• normal: Standard-Design
• primary: Primäre/Haupt-Aktion
• secondary: Sekundäre Aktion
• tertiary: Tertiäre/subtile Aktion
• danger: Warnung für destruktive Aktionen
• ghost: Dezentes Design ohne Hintergrund
• custom: Benutzerdefiniertes Styling über _custom-class

Icons und Label-Styling

Icons können über _icons hinzugefügt und das Label über _hideLabel verborgen werden:

Icons

<KolSplitButton _label="Split-Button" />

Tooltip und Tastaturkürzel

Tooltip-Position und Tastaturkürzel konfigurieren:

Tooltip Align

<KolSplitButton _label="Split-Button" />

Deaktivierter Zustand

Der Split-Button kann über _disabled deaktiviert werden:

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

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
click	Primärer oder sekundärer Button wird angeklickt	_value-Property
onMouseDown	Eine Taste eines Zeigegeräts wird gedrückt, während der Zeiger sich innerhalb des Elements befindet	-

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.

---