Button

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

Synonyme: Schaltfläche, Schalter, Call-to-Action (CTA), Aktionsschaltfläche

Beschreibung: Die Button-Komponente stellt Schaltflächen zur Verfügung, mit denen Nutzende Aktionen auslösen können. Unterschiedliche Varianten unterstützen die visuelle Priorisierung und erleichtern die Orientierung innerhalb einer Anwendung.

Beispiel

Darstellung der Komponente mit Standard-Label und ohne optional gesetzte Felder.

<KolButton _label="Click me" />

Barrierefreiheit

• Die Property _label ist verpflichtend und stellt den zugänglichen Namen (Accessible Name) des Buttons bereit. Die Beschriftung wird von Screenreadern ausgegeben und ermöglicht die Identifikation der Funktion des Buttons.
• Die Komponente unterstützt die Bedienung per Tastatur.
• Der Button kann über die Tabulatortaste fokussiert und über Enter oder Leertaste aktiviert werden.
• Auch bei ausgeblendeter sichtbarer Beschriftung (_hideLabel) bleibt der zugängliche Name erhalten. Die Beschriftung wird als Tooltip angezeigt und von Screenreadern beim Fokus vorgelesen.
• Die Komponente stellt einen sichtbaren Fokuszustand bereit.
• Die Komponente basiert auf dem nativen HTML-Element button und unterstützt dadurch etablierte Bedienmuster sowie assistive Technologien.
• Für Menschen mit eingeschränktem Sichtfeld ist die Positionierung von Icons links von der Beschriftung optimal.

Konkrete Designentscheidungen

Entscheidung	Begründung
Verwendung des nativen HTML-Elements button	Native Buttons bieten bereits die erforderliche Semantik, Tastaturbedienung und Unterstützung durch assistive Technologien.
Verpflichtende Angabe von _label	Jede Schaltfläche benötigt einen zugänglichen Namen, damit ihre Funktion von Screenreadern erkannt werden kann.
Unterstützung von Icon-only-Buttons nur mit Label	Auch bei ausgeblendeter Beschriftung bleibt ein zugänglicher Name erforderlich. Dadurch bleibt die Schaltfläche für Screenreader verständlich.
Orientierung am nativen Tastaturverhalten	Nutzende profitieren von bekannten Bedienmustern und einer konsistenten Interaktion über verschiedene Anwendungen hinweg.
Deaktivierte Schaltflächen sind nicht fokussierbar	Das Verhalten entspricht dem nativen HTML-Standard und reduziert unnötige Fokusziele bei der Tastaturnavigation.

Links und Referenzen

Verwendung

• Die Button-Komponente wird verwendet, um Aktionen innerhalb einer Anwendung auszulösen.
• Schaltflächen sollten immer eine konkrete Aktion ausführen und keine reine Navigation übernehmen.
• Die Beschriftung sollte die auszuführende Aktion möglichst eindeutig beschreiben.
• Buttons können durch unterschiedliche Varianten visuell priorisiert werden.
• Die Komponente eignet sich für einzelne Aktionen sowie für Aktionsgruppen innerhalb eines gemeinsamen Kontexts.

Tastatursteuerung

Taste	Funktion
Tab	Fokus auf die nächste Schaltfläche setzen
Shift+Tab	Fokus auf die vorherige Schaltfläche setzen
Enter / Space	Schaltfläche aktivieren

Best Practices / Empfehlungen

• Verwenden Sie möglichst aussagekräftige Beschriftungen, die die auszuführende Aktion beschreiben.
• Verwenden Sie Verben wie „Speichern“, „Absenden“ oder „Löschen“ statt allgemeiner Bezeichnungen wie „OK“ oder „Weiter“. Die Beschriftung muss die Aktion beschreiben.
• Heben Sie innerhalb eines Bereichs nur die wichtigste Aktion als primäre Schaltfläche hervor. Weitere Buttons sollten als sekundäre Schaltflächen dargestellt werden.
• Verwenden Sie nicht mehrere Buttons im Stil „primär" innerhalb einer Gruppierung.
• Verwenden Sie Schaltflächen nicht für Navigation zwischen Seiten. Nutzen Sie hierfür Links oder die LinkButton-Komponente.
• Verwenden Sie Icons als Ergänzung zur Beschriftung, nicht als deren Ersatz.
• Verwenden Sie Icon-only-Buttons nur, wenn die Funktion auch ohne sichtbaren Text eindeutig erkennbar bleibt.
• Gruppieren Sie zusammengehörige Aktionen räumlich und visuell.

Anwendungsfälle

• Absenden eines Formulars
• Speichern von Daten
• Öffnen oder Schließen eines Dialogs
• Bestätigen oder Abbrechen einer Aktion
• Starten eines Prozesses oder Workflows
• Auslösen einer Suche
• Bearbeiten oder Löschen eines Datensatzes
• Navigation innerhalb von Wizards oder mehrstufigen Prozessen

FAQ

Wann sollte ein Button statt eines Links verwendet werden?

• Buttons lösen Aktionen innerhalb der aktuellen Seite oder Anwendung aus.
• Beispiele: Speichern, Löschen, Absenden, Dialog öffnen.
• Links dienen der Navigation zu anderen Seiten, Ansichten oder Ressourcen.

Wann sollte die LinkButton-Komponente statt der Button-Komponente verwendet werden?

• LinkButton für Navigation mit schaltflächenähnlicher Darstellung.
• Button für Aktionen innerhalb der Anwendung.
• Die Wahl sollte sich an der Funktion und nicht am visuellen Erscheinungsbild orientieren.

Warum ist die Property _label verpflichtend?

• Stellt den zugänglichen Namen (Accessible Name) der Schaltfläche bereit.
• Wird von Screenreadern ausgegeben.
• Verhindert unbeschriftete und damit schwer verständliche Schaltflächen.

Darf ein Button nur aus einem Icon bestehen?

• Ja. Die sichtbare Beschriftung kann über _hideLabel ausgeblendet werden.
• Ein aussagekräftiges _label bleibt weiterhin erforderlich.
• Die Funktion muss auch ohne sichtbaren Text eindeutig erkennbar sein.

Wie viele primäre Schaltflächen sollten innerhalb eines Bereichs verwendet werden?

• In der Regel nur eine primäre Schaltfläche pro Kontext.
• Die wichtigste Aktion sollte visuell hervorgehoben werden.
• Mehrere primäre Schaltflächen erschweren die Priorisierung von Aktionen.

Können Schaltflächen deaktiviert werden?

• Ja. Deaktivierte Schaltflächen können weder fokussiert noch aktiviert werden.
• Das Verhalten entspricht dem nativen HTML-Button.

Werden eigene Tastaturkürzel unterstützt?

• Nein. Die Komponente unterstützt die standardmäßige Tastaturbedienung nativer HTML-Schaltflächen.
• Zusätzliche Tastaturkürzel müssen durch die Anwendung umgesetzt werden.

Können Schaltflächen ausschließlich über Farben unterschieden werden?

• Davon wird abgeraten. Informationen sollten nicht ausschließlich über Farben vermittelt werden.
• Beschriftung, Position oder weitere visuelle Merkmale sollten die Bedeutung zusätzlich unterstützen.

**Warum wird die Beschriftung bei _hideLabel als Tooltip angezeigt?

• Die Funktion bleibt auch ohne sichtbare Beschriftung nachvollziehbar.
• Sehende Nutzende erhalten zusätzliche Orientierung.
• Der zugängliche Name bleibt für assistive Technologien erhalten.

Konstruktion / Technik

Playground

Variant

Tooltip Align

Icons

<KolButton _label="Button" />

Funktionalitäten (mit Code)

Beschriftung

Die sichtbare Beschriftung wird über _label gesetzt:

<KolButton _label="Schaltflächenbeschriftung" />

Varianten

Die Darstellung wird über _variant gesteuert. Der Standardwert ist normal:

Variant

<KolButton _label="Button" _variant="primary" />

Verfügbare Varianten:

• primary – Primäre Handlungsaufforderung
• secondary – Sekundäre Aktion
• normal – Standard-Variante (Standard)
• danger – Gefährliche oder destruktive Aktion
• ghost – Subtile Variante
• tertiary – Tertiäre Aktion
• custom – Benutzerdefinierte Styling (erfordert _custom-class)

Icons

Icons können über _icons hinzugefügt werden. Als String übergeben Sie die Icon-Klasse (z.B. kolicon-house), das Icon wird links vom Text angezeigt:

Icons

<KolButton _icons="kolicon-house" _label="Home" />

Icons können auch als Objekt mit den Positionen top, right, bottom und left angegeben werden, jeweils mit Icon-Klasse oder Styleobjekt.

Icon-Only-Button

Mit _hideLabel wird nur das Icon angezeigt, die Beschriftung wird als Tooltip angezeigt:

Icons

<KolButton _hideLabel={true} _icons="kolicon-house" _label="Home" />

Hinweis: Das Attribut _label muss auch gesetzt werden, wenn nur ein Icon angezeigt wird – es wird für Screenreader und den Tooltip verwendet.

Button-Typ

Der HTML-Button-Type wird über _type gesteuert:

<KolButton _label="Button" _type="submit" />

Verfügbare Typen:

• button – Standard-Button (Standard)
• submit – Formular absenden
• reset – Formular zurücksetzen

Disabled-Status

Mit _disabled wird der Button deaktiviert:

<KolButton _disabled={true} _label="Deaktiviert" />

Weitere Eigenschaften

Eigenschaft	Beschreibung
_accessKey	Definiert die Tastenkombination zum Auslösen oder Fokussieren des Buttons
_tooltipAlign	Position des Tooltips: top (Standard), right, bottom, left
_shortKey	Definiert einen visuellen Shortcut-Hinweis und liest ihn in Screenreadern vor
_customClass	Benutzerdefinierte CSS-Klasse (nur für _variant="custom")
_name	Technischer Name des Buttons im Formular
_value	Wert des Elements
_inline	Displaymodus ohne Mindestgröße von 44px
_ariaControls	Definiert, welche Elemente durch diesen Button gesteuert werden (aria-controls)
_ariaDescription	Setzt das aria-description-Attribut für eine erweiterte Beschreibung durch Screenreader
_ariaExpanded	Gibt an, ob der Button ein erweitertes Element steuert (aria-expanded)
_ariaSelected	Gibt an, ob das interaktive Element ausgewählt ist, z.B. bei role="tab" (aria-selected)

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
onClick	Button wird angeklickt	_value-Property
onMouseDown	Maustaste wird über dem Button gedrückt	-
onFocus	Button erhält den Fokus	-
onBlur	Button verliert den Fokus	-

API

Overview

The Button component is used to present users with action options and arrange them in a clear hierarchy. It helps users find the most important actions on a page or within a viewport and allows them to execute those actions. The button label clearly indicates which action will be triggered. Buttons allow users to confirm a change, complete steps in a task, or make decisions.

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
_inline	_inline	Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px.	boolean | undefined	false
_label (required)	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to false to enable the expert slot.	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; onFocus?: EventCallback<FocusEvent> | undefined; onBlur?: EventCallback<FocusEvent> | 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>

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
"expert"	Custom label content, e.g. for rich text or icons.

---