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: Schaltfläche, Call-to-Action, Aktion

Beschreibung: Die Button-Komponente zeigt Nutzern Auswahlmöglichkeiten für Aktionen an und ordnet diese in einer klaren Hierarchie an. Sie hilft Nutzern, die wichtigsten Aktionen einer Seite zu finden und ermöglicht es ihnen, diese auszuführen.

Beispiel

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

<KolButton _label="Click me" />

Barrierefreiheit

• Die Beschriftung über _label ist erforderlich und wird von Screenreadern vorgelesen.
• Für Menschen mit eingeschränktem Sichtfeld ist die Positionierung von Icons links von der Beschriftung optimal.
• Bei aktiviertem _hideLabel wird die Beschriftung als Tooltip angezeigt und von Screenreadern beim Fokus vorgelesen.
• Die Komponente unterstützt Tastaturnavigation über Tab und Enter.

Links und Referenzen

Verwendung

Tastatursteuerung

Taste	Funktion
Tab	Fokussiert den Button.
Enter	Führt die onClick-Aktion des fokussierten Buttons aus.

Best Practices / Empfehlungen

• Verwenden Sie eine primäre Schaltfläche für die nächstbeste Aktion. Verbleibende Calls-to-Action sollten als sekundäre Schaltfläche dargestellt werden.
• Verwenden Sie nur eine primäre Schaltfläche je Viewport. Auf der gesamten Seite kann dieser Stil beliebig oft auftreten.
• Die Beschriftung muss die Aktion beschreiben (z.B. „Speichern", „Abbrechen") und sollte ein Verb enthalten.
• Verwenden Sie keine generischen Bezeichnungen wie „OK", insbesondere nicht im Fehlerfall.
• Verwenden Sie nicht mehrere Buttons im Stil „primär" innerhalb einer Gruppierung.
• Verwenden Sie Buttons nicht als Link oder als Navigationselement.

Anwendungsfälle

• Bestätigung oder Absage von Dialogfenstern
• Absenden von Formulardaten
• Auslösen von Aktionen (speichern, löschen, exportieren, etc.)
• Initiierung von Workflows oder Prozessen
• Wechsel zwischen Zuständen oder Ansichten

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; }	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.

---