InputCheckbox

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

Synonyme: Auswahlfeld, Häkchen-Feld, Ankreuzfeld

Beschreibung: Die InputCheckbox-Komponente ermöglicht Nutzenden, eine oder mehrere Optionen unabhängig voneinander auszuwählen oder abzuwählen. Sie kann einzeln oder als Teil einer Gruppe verwendet werden.

Die Varianten _variant="default", _variant="switch" und _variant="button" verändern ausschließlich die visuelle Darstellung der Komponente. Technisch bleibt die Komponente unabhängig von der gewählten Variante eine native Checkbox. Verhalten, Semantik und Tastaturbedienung bleiben unverändert.

Beispiel

Darstellung der Komponente ohne optional gesetzte Felder. Code kann eingeblendet werden.

<KolInputCheckbox _label="Akzeptiere die Bedingungen" />

Barrierefreiheit

• Verwenden Sie eine aussagekräftige Beschriftung (_label), damit Nutzende den Zweck der Checkbox eindeutig erkennen können.
• Wird _hideLabel verwendet, bleibt die Beschriftung für assistive Technologien verfügbar. Stellen Sie sicher, dass die ausgeblendete Beschriftung dennoch aussagekräftig ist.
• Nutzen Sie _hint, um zusätzliche Informationen bereitzustellen, wenn diese für das Verständnis der Checkbox erforderlich sind.
• Stellen Sie Validierungsfehler über _msg verständlich und eindeutig dar.
• Die visuellen Varianten (default, switch, button) beeinflussen ausschließlich das Erscheinungsbild. Für assistive Technologien bleibt die Komponente unabhängig von der Darstellung eine native Checkbox.

Konkrete Designentscheidungen

Entscheidung	Begründung
Native Checkbox-Semantik unabhängig von _variant	Alle Varianten verwenden technisch eine native Checkbox. Dadurch bleiben Verhalten, Tastatursteuerung und Unterstützung durch assistive Technologien konsistent.
Bewusster Verzicht auf ARIA-Rollen wie role="switch"	Die native Checkbox-Semantik wird von Screenreadern browser- und plattformübergreifend zuverlässiger unterstützt als nachgebildete Widget-Rollen. Zusätzliche ARIA-Rollen würden keinen Mehrwert bieten und könnten zu inkonsistentem Verhalten führen.

Links und Referenzen

Verwendung

• Verwenden Sie Checkboxen, wenn mehrere Optionen unabhängig voneinander ausgewählt werden können.
• Verwenden Sie keine Checkbox, wenn sich Nutzende zwischen genau einer Option entscheiden müssen. Nutzen Sie hierfür eine Radio-Button-Gruppe.
• Kennzeichnen Sie vorausgewählte Optionen nur, wenn dies fachlich sinnvoll ist.
• Deaktivieren Sie Checkboxen nur, wenn eine Auswahl tatsächlich nicht möglich ist, und erläutern Sie den Grund möglichst im sichtbaren Kontext.
• Verwenden Sie den Indeterminate-Zustand, um eine teilweise Auswahl zu kennzeichnen, beispielsweise wenn bei einer „Alle auswählen“-Funktion nur ein Teil der untergeordneten Optionen ausgewählt ist.
• Ergänzen Sie bei Bedarf Hinweise oder Validierungsnachrichten, um die Nutzung der Checkbox verständlich zu unterstützen.
• Wählen Sie die visuelle Variante ausschließlich nach gestalterischen Anforderungen aus. Das Verhalten der Komponente bleibt in allen Varianten identisch.

Tastatursteuerung

Taste	Funktion
Tab	Fokus auf die Checkbox bzw. das nächste fokussierbare Element setzen.
Shift+Tab	Fokus auf das vorherige fokussierbare Element setzen.
Leertaste	Auswahlzustand der fokussierten Checkbox ändern.

Best Practices / Empfehlungen

• Gruppieren Sie zusammengehörige Checkboxen logisch und versehen Sie Gruppen bei Bedarf mit einer gemeinsamen Beschriftung.
• Prüfen Sie bei umfangreichen Auswahllisten, ob eine Combobox mit Mehrfachauswahl besser geeignet ist.
• Ergänzen Sie keine zusätzlichen ARIA-Rollen oder ARIA-Attribute, um das Verhalten nativer Checkboxen zu verändern.

Anwendungsfälle

• Zustimmung zu Datenschutzbestimmungen, Nutzungsbedingungen oder Einwilligungen
• Auswahl mehrerer unabhängiger Optionen, beispielsweise Interessen, Kategorien oder Filter
• Aktivieren oder Deaktivieren einzelner Einstellungen, die unabhängig voneinander gewählt werden können
• „Alle auswählen“-Funktion mit Indeterminate-Zustand, wenn eine Checkbox den Auswahlstatus einer Gruppe von Unter-Checkboxen repräsentiert
• Formulare, in denen der Auswahlzustand als Formularwert gespeichert und gemeinsam mit den übrigen Eingaben übermittelt werden soll

FAQ

Ändert _variant="switch" die Ansage für Screenreader?

Nein. Alle drei Varianten (default, switch und button) bleiben technisch eine Checkbox. Screenreader geben unabhängig von der gewählten Variante eine Checkbox aus und keinen Schalter.

Kann ich den Indeterminate-Zustand per Tastatur oder Klick setzen?

Nein. Der Indeterminate-Zustand kann ausschließlich programmatisch über die API gesetzt werden. Nutzende können diesen Zustand weder per Tastatur noch durch einen Mausklick aktivieren.

Konstruktion / Technik

Playground

Testen Sie die verschiedenen Eigenschaften der InputCheckbox-Komponente:

Message

<KolInputCheckbox _label="Beispiel-Checkbox" />

Funktionalitäten (mit Code)

Basis-Checkbox

Eine einfache Checkbox ohne spezielle Konfiguration:

<KolInputCheckbox _label="Zustimmen" />

Varianten

Die Checkbox unterstützt drei verschiedene visuelle Varianten über das Attribut _variant:

<KolInputCheckbox _label="Checkbox-Typ" />

Verfügbare Varianten:

• default: Klassische rechteckige Checkbox mit Häkchen (Standard)
• switch: Horizontaler Schalter/Toggle-Button (rechts = aktiv, links = inaktiv)
• button: Button-Stil mit Icon-Wechsel je nach Zustand

Zustände

Verschiedene Zustände und Statusanzeigen:

<KolInputCheckbox _label="Checkbox-Zustand" />

Verfügbare Zustände:

• _checked: Markiert die Checkbox als angekreuzt
• _indeterminate: Setzt die Checkbox in einen unbestimmten Zustand (weder vollständig an noch aus) – typisch für Hierarchien
• _disabled: Deaktiviert die Checkbox (mit Begründung verwenden!)
• _required: Kennzeichnet die Checkbox als erforderlich für Formularvalidierung

Label und Beschriftung

Kontrolle über Sichtbarkeit und Ausrichtung der Beschriftung:

<KolInputCheckbox _label="Beschriftung" />

Verfügbare Optionen:

• _hideLabel: Blendet das Label visuell aus (bleibt für assistive Technologien sichtbar)
• _labelAlign: Ausrichtung der Beschriftung (left oder right, Standard: right)

Formularattribute

Standard-Attribute für die Integration in Formulare:

Message

<KolInputCheckbox _label="Formular-Beispiel" />

Verfügbare Attribute:

• _hint: Ergänzender Hinweistext unter dem Label
• _msg: Fehlermeldung oder Validierungshinweis
• _name: Technischer Name des Input-Felds
• _accessKey: Tastenkombination zum Fokussieren/Auslösen
• _shortKey: Visuelle Shortcut-Hinweis neben dem Label

Benutzerdefinierte Icons

Anpassung der Icon-Darstellung für verschiedene Zustände:

Icons

<KolInputCheckbox _label="Mit benutzerdefinierten Icons" />

Die _icons-Eigenschaft ermöglicht die Anpassung der Icons für die Zustände checked, unchecked und indeterminate.

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
focus	Eingabefeld wird fokussiert	-
click	Eingabefeld wird angeklickt	-
input	Checkbox wird an- oder abgehakt (entspricht nativem input-Event)	Definierter _value wenn aktiv, sonst null
change	Checkbox wird an- oder abgehakt (entspricht nativem change-Event`)	Definierter _value wenn aktiv, sonst null
blur	Eingabefeld verliert Fokus	-
keydown	Eine Taste wird gedrückt	-

API

Overview

The Checkbox input type generates a rectangular box that can be activated and deactivated by clicking. When activated, a colored checkmark is shown inside the box.

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
_checked	_checked	Defines whether the checkbox is checked or not. Can be read and written.	boolean | undefined	false
_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
_hideMsg	_hide-msg	Hides the error message but leaves it in the DOM for the input's aria-describedby.	boolean | undefined	false
_hint	_hint	Defines the hint text.	string | undefined	''
_icons	_icons	Defines the icon classnames (e.g. _icons="fa-solid fa-user").	string | undefined | { checked: string; indeterminate?: string | undefined; unchecked?: string | undefined; } | { checked?: string | undefined; indeterminate: string; unchecked?: string | undefined; } | { checked?: string | undefined; indeterminate?: string | undefined; unchecked: string; }	undefined
_indeterminate	_indeterminate	Puts the checkbox in the indeterminate state, does not change the value of _checked.	boolean | undefined	undefined
_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
_labelAlign	_label-align	Defines which alignment should be used for presentation.	"left" | "right" | undefined	'right'
_msg	_msg	Defines the properties for a message rendered as Alert component.	Omit<AlertProps, "_on" | "_label" | "_level" | "_variant" | "_hasCloser"> & { _description: string; } | string | undefined	undefined
_name	_name	Defines the technical name of an input field.	string | undefined	undefined
_on	--	Gibt die EventCallback-Funktionen für das Input-Event an.	InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown | undefined	undefined
_required	_required	Makes the input element required.	boolean | undefined	false
_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'
_touched	_touched	Shows if the input was touched by a user.	boolean | undefined	false
_value	_value	Defines the value of the element.	boolean | null | number | object | string | undefined	true
_variant	_variant	Defines which variant should be used for presentation.	"button" | "default" | "switch" | undefined	'default'

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"	Checkbox description.

---