InputCheckbox

Synonyme: Kontrollkästchen, Auswahlfeld, Ankreuzfeld, Häkchen-Feld, Checkbox, Switch, Toggle

Beschreibung: Mit InputCheckbox können Nutzende eine Option unabhängig von anderen Optionen aktivieren oder deaktivieren. Die Komponente kann einzeln oder als Teil einer Gruppe verwendet werden.

Die Komponente basiert auf dem nativen HTML5-Eingabetyp checkbox und profitiert dadurch von dessen Semantik sowie der standardisierten Unterstützung durch Browser und assistive Technologien.

Die Varianten default, switch und button (_variant) verändern ausschließlich die visuelle Darstellung. Technisch bleibt die Komponente in allen Varianten eine native Checkbox – Verhalten, Semantik und Tastaturbedienung bleiben unverändert.

Beispiel

Standard-Checkbox ohne optional gesetzte Felder:

<KolInputCheckbox _label="Ich akzeptiere die Nutzungsbedingungen" />

Barrierefreiheit

• Das Eingabefeld muss mit einer aussagekräftigen Beschriftung versehen werden. Es darf visuell ausgeblendet werden, wenn der Zweck des Eingabefeldes durch den direkten visuellen Kontext absolut unmissverständlich ist.

• Im Fehlerfall wird die Fehlermeldung direkt an der Komponente dargestellt und automatisch mit ihr verknüpft, sodass sie auch assistiven Technologien zur Verfügung steht.

• Checkbox, Zustandssymbol und Beschriftung bilden eine gemeinsame Klickfläche, die mindestens der barrierefreien Mindestgröße für Bedienelemente entspricht.

Konkrete Designentscheidungen

Entscheidung	Begründung
Native Checkbox-Semantik unabhängig von _variant	Alle Varianten verwenden technisch eine native Checkbox. Screenreader geben daher in jeder Variante eine Checkbox aus; Verhalten und Tastatursteuerung bleiben identisch.
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.
Indeterminate-Zustand nur programmatisch	Der Zustand _indeterminate kann ausschließlich über die API gesetzt werden. Bei einer Interaktion durch Nutzende wird er zurückgesetzt und _checked umgeschaltet – entsprechend dem Verhalten nativer Checkboxen.

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 für genau eine von mehreren Optionen entscheiden müssen. Nutzen Sie hierfür die Komponente .
• Legen Sie mit _value fest, welcher Wert im aktivierten Zustand übermittelt wird (Standard: true). Ist die Checkbox nicht aktiviert, ist der Wert null.
• Verwenden Sie den Zustand _indeterminate, um eine teilweise Auswahl zu kennzeichnen, beispielsweise wenn bei einer „Alle auswählen“-Funktion nur ein Teil der untergeordneten Optionen ausgewählt ist.

Tastatursteuerung

Die Tastaturbedienung wird durch den Browser und das Betriebssystem bestimmt. Daher können sich einzelne Tastaturfunktionen je nach Browser und Endgerät unterscheiden.

Typischerweise werden folgende Funktionen unterstützt:

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.
Enter	Sendet das umgebende Formular ab (KoliBri-Ergänzung, siehe Hinweis).

Hinweis: Das Absenden per Enter wird von KoliBri ergänzt, da das native Element im Shadow DOM der Komponente liegt: Befindet sich die Komponente innerhalb eines form- bzw. kol-form-Elements, sucht sie dieses – auch über Shadow-DOM-Grenzen hinweg – und löst dort das Absenden aus.

Der Auswahlzustand der Checkbox wird dabei nicht verändert.

Best Practices / Empfehlungen

• Formulieren Sie die Beschriftung so, dass der aktivierte Zustand eindeutig verständlich ist, beispielsweise „Newsletter abonnieren“ statt „Newsletter“.
• Setzen Sie Vorauswahlen (_checked) nur, wenn dies fachlich sinnvoll ist.
• Ergänzen Sie bei Bedarf Hinweise oder Validierungsnachrichten, um die Nutzung der Checkbox verständlich zu unterstützen.
• Deaktivieren Sie Checkboxen nur, wenn eine Auswahl tatsächlich nicht möglich ist, und erläutern Sie den Grund möglichst im sichtbaren Kontext.
• Wählen Sie die visuelle Variante ausschließlich nach gestalterischen Anforderungen aus. Das Verhalten der Komponente bleibt in allen Varianten identisch.
• Gruppieren Sie zusammengehörige Checkboxen logisch und versehen Sie Gruppen mit einer gemeinsamen Beschriftung, beispielsweise mit einem fieldset und einer legend.
• Prüfen Sie bei umfangreichen Auswahllisten, ob eine Mehrfachauswahl über die Komponente 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 untergeordneter Checkboxen repräsentiert
• Formulare, in denen der Auswahlzustand als Formularwert 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 _indeterminate gesetzt werden. Eine Interaktion durch Nutzende setzt ihn zurück und schaltet den Auswahlzustand um.

Welchen Wert übermittelt die Checkbox?
Im aktivierten Zustand wird der Wert aus _value übermittelt (Standard: true), im nicht aktivierten Zustand null.

Playground

Testen Sie die verschiedenen Eigenschaften der InputCheckbox-Komponente:

Message

Icons

<KolInputCheckbox _label="Beispiel-Checkbox" />

Funktionalitäten

Einfache Checkbox

Jedes Feld benötigt mindestens ein Label (_label), um für alle Nutzenden verständlich und zugänglich zu sein. Das Label wird als natives label-Element mit dem Feld verknüpft.

<KolInputCheckbox _label="Newsletter abonnieren" />

Varianten

Mit _variant wählen Sie die visuelle Darstellung der Checkbox. Semantik und Bedienung bleiben in allen Varianten identisch.

Verfügbare Varianten sind:

• default: Klassische Checkbox mit Häkchen (Standard)
• switch: Horizontaler Schalter (rechts = aktiviert, links = deaktiviert)
• button: Schaltflächenartige Darstellung, bei der das Zustandssymbol je nach Zustand wechselt

Auch in den Varianten switch und button wird die Komponente von Screenreadern als Checkbox ausgegeben, nicht als Schalter oder Button. In der Variante button ist die Checkbox selbst nicht sichtbar; die Schaltfläche bleibt per Tastatur fokussierbar und bedienbar.

<KolInputCheckbox _label="Benachrichtigungen aktivieren" _variant="switch" />

Zustände

Mit _checked und _indeterminate steuern Sie den Auswahlzustand der Checkbox:

• _checked: Aktiviert die Checkbox. Der Wert wird bei einer Interaktion aktualisiert und kann gelesen und geschrieben werden.
• _indeterminate: Kennzeichnet eine teilweise Auswahl, beispielsweise bei einer übergeordneten „Alle auswählen“-Checkbox. Der Wert von _checked bleibt dabei unverändert. Assistive Technologien geben den Zustand als teilweise ausgewählt aus. Bei einer Interaktion durch Nutzende wird _indeterminate zurückgesetzt.

<KolInputCheckbox _indeterminate={true} _label="Alle auswählen" />

Formularattribute

Mit den folgenden Properties passen Sie das Feld an gängige Formularanforderungen an:

• _disabled: Deaktiviert das Feld. Deaktivierte Felder sind nicht fokussierbar und können nicht bearbeitet werden (mit Bedacht verwenden!).

• _required: Kennzeichnet das Feld als Pflichtfeld.

Die Properties werden 1:1 auf die gleichnamigen nativen HTML-Attribute des input-Elements übertragen. Mit _name legen Sie den technischen Namen fest, unter dem der Wert aus _value bei aktivierter Checkbox übermittelt wird.

<KolInputCheckbox _label="Ich akzeptiere die Nutzungsbedingungen" />

Hinweistexte und Fehlermeldungen

Mit _hint und _msg geben Sie Nutzenden zusätzliche Orientierung zur Eingabe und machen Validierungsfehler unmittelbar am Feld sichtbar:

• _hint: Ergänzende Hinweise zur Eingabe (wird immer angezeigt und über aria-describedby mit dem Feld verknüpft)
• _msg: Fehlermeldungen oder Validierungshinweise (wird nur in Verbindung mit _touched angezeigt)
• _touched: Zeigt an, ob das Feld von Nutzenden bereits angefasst wurde, und steuert damit, ob _msg sichtbar wird
• _hideMsg: Unterdrückt die Fehlermeldung am Feld, wenn sie an anderer Stelle dargestellt wird

Hinweis: _msg wird erst dann eingeblendet, wenn _touched auf true gesetzt ist. So werden Validierungsfehler nicht bereits beim ersten Rendern, sondern erst nach einer Interaktion mit dem Feld angezeigt. Handelt es sich um eine Fehlermeldung, wird das Feld zusätzlich über aria-invalid als ungültig gekennzeichnet.

Anwendungsfall für _hideMsg: Besteht eine fachliche Einheit aus mehreren Eingabefeldern innerhalb eines Field-Sets, beispielsweise ein sechsstelliger Bestätigungscode mit einem einzelnen Feld je Stelle, kann eine gemeinsame Fehlermeldung für die gesamte Gruppe sinnvoller sein als eine Meldung je Einzelfeld. In diesem Fall unterdrücken Sie die Fehlermeldung an den einzelnen Feldern über _hideMsg und stellen sie stattdessen einmalig am Field-Set dar.

Wichtig: _hideMsg blendet die Fehlermeldung nicht nur visuell aus. Die Meldung wird weder gerendert noch über aria-describedby mit dem Feld verknüpft – lediglich die Kennzeichnung über aria-invalid bleibt erhalten. Stellen Sie daher sicher, dass die gemeinsame Fehlermeldung auf Anwendungsebene für alle Nutzenden, auch für Nutzende assistiver Technologien, wahrnehmbar ist.

Message

<KolInputCheckbox _hideMsg={false} _hint="Die Zustimmung ist für die Registrierung erforderlich." _label="Ich akzeptiere die Nutzungsbedingungen" _msg={{ "_description": "Bitte stimmen Sie den Nutzungsbedingungen zu." }} _touched={true} />

Label ausblenden

Mit _hideLabel blenden Sie das Label visuell aus, um das Feld kompakter zu gestalten. Für assistive Technologien bleibt die Beschriftung als zugänglicher Name (aria-label) weiterhin verfügbar; sehende Nutzende erhalten sie bei Maus-Hover und Tastaturfokus als Tooltip.

<KolInputCheckbox _hideLabel={false} _label="Zeile auswählen" />

Ausrichtung der Beschriftung

Mit _labelAlign legen Sie fest, ob die Beschriftung rechts (right, Standard) oder links (left) der Checkbox steht. Die Lese- und Fokusreihenfolge folgt dabei der sichtbaren Anordnung.

<KolInputCheckbox _label="Beschriftung links" _labelAlign="left" />

Zustandssymbole (Icons)

Bei der Checkbox platziert _icons keine zusätzlichen Icons links oder rechts vom Feld, sondern legt die Symbole für die einzelnen Auswahlzustände fest:

• checked: Symbol im aktivierten Zustand (Standard: kolicon-check)
• indeterminate: Symbol im Indeterminate-Zustand (Standard: kolicon-minus)
• unchecked: Symbol im nicht aktivierten Zustand (Standard: kolicon-cross)

Nicht angegebene Zustände behalten ihr Standard-Symbol. Die Symbole sind rein dekorativ und vor assistiven Technologien verborgen; der Zustand wird über die native Checkbox vermittelt. Wo und ob ein Symbol sichtbar ist, hängt von der Variante ab: In der Variante default erscheint es nur im aktivierten bzw. Indeterminate-Zustand.

Icons

<KolInputCheckbox _icons={{ "checked": "kolicon-check", "unchecked": "kolicon-kolibri" }} _label="Mit benutzerdefinierten Symbolen" _variant="button" />

Tastenkürzel

Mit _accessKey und _shortKey weisen Sie auf Tastenkürzel hin. Beide werden als Hinweis hinter der Beschriftung angezeigt:

• _accessKey: Wird auf das native accesskey-Attribut übertragen. Die Tastenkombination zum Auslösen hängt von Browser und Betriebssystem ab.
• _shortKey: Wird über aria-keyshortcuts an assistive Technologien übermittelt. Die Tastenkombination selbst muss von der Anwendung umgesetzt werden.

<KolInputCheckbox _accessKey="S" _label="Automatisch speichern" />

API

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
focus	Checkbox wird fokussiert	-
blur	Checkbox verliert Fokus	-
keydown	Taste wird bei fokussierter Checkbox gedrückt	-
input	Checkbox wird aktiviert oder deaktiviert	Wert aus _value, wenn aktiviert, sonst null
change	Checkbox wird aktiviert oder deaktiviert	Wert aus _value, wenn aktiviert, sonst null

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
_ariaDetails	_aria-details	References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements to cross the Shadow DOM boundary. Supported by desktop screen readers (NVDA, JAWS with Chrome/Firefox). Not yet supported by mobile screen readers (TalkBack, VoiceOver iOS).	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.	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
_infoPopover	_info-popover	Defines the informational popover after the label.	any	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(options?: KolFocusOptions) => Promise<void>

Sets focus on the internal element.

Parameters

Name	Type	Description
options	KolFocusOptions | undefined

Returns

Type: Promise<void>

getValue() => Promise<StencilUnknown>

Returns the current value.

Returns

Type: Promise<StencilUnknown>

Slots

Slot	Description
	The label of the input field.
"expert"	Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot

---