InputCheckbox

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: Auswahlfeld, Häkchen-Feld, Ankreuzfeld, Toggle

Beschreibung: Die InputCheckbox-Komponente ist ein Eingabefeld, das Nutzer:innen ermöglicht, Optionen an- oder abzukreuzen. Sie wird als einzelnes Feld oder in Gruppen verwendet und ermöglicht die Auswahl einer oder mehrerer Optionen aus einer vordefinierten Menge.

Beispiel

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

<KolInputCheckbox _label="Akzeptiere die Bedingungen" />

Barrierefreiheit

• Label-Pflicht: Jede Checkbox muss über das Attribut _label eine eindeutige Beschriftung erhalten. Diese wird von Screenreadern vorgelesen und ermöglicht eine klare Identifikation des Eingabefelds.
• Fokusmanagement: Die Komponente ist vollständig über die Tastatur bedienbar mit klaren Fokusindikatoren.
• Leer-Taste: Der Zustand Indeterminate kann über die Tastatur nicht direkt hergestellt werden – diese Funktion wird typischerweise programmatisch verwendet.
• Hinweistexte: Mit _hint können zusätzliche Informationen bereitgestellt werden, die für alle Nutzer zugänglich sind und von Screenreadern vorgelesen werden.
• Fehlermeldungen: Fehleingaben können über das Attribut _msg mit aussagekräftigen Fehlermeldungen versehen werden.
• Alternativen bei vielen Optionen: Bei längeren Listen von Checkbox-Optionen sollte alternativ eine in Betracht gezogen werden, um die Seite übersichtlich zu halten.

Links und Referenzen

Verwendung

Tastatursteuerung

Taste	Funktion
Tab	Fokussiert die Checkbox bzw. ermöglicht den Wechsel zwischen Checkboxen einer Liste.
Leer	Aktiviert bzw. deaktiviert die Checkbox. Der Zustand Indeterminate ist über die Tastatur nicht möglich.

Best Practices / Empfehlungen

• Einzelne Checkboxen: Verwenden Sie eine einzelne Checkbox, wenn Sie von Nutzer:innen eine einfache Bestätigung wünschen, z. B. Akzeptieren von Bedingungen oder Einwilligungen.
• Checkbox-Gruppen: Verwenden Sie mehrere Checkboxen, um Nutzer:innen die Möglichkeit zu geben, eine oder mehrere Werte aus einer Menge auszuwählen.
• Übersichtlichkeit: Vermeiden Sie zu viele Checkboxen auf einer Seite, da dies die Inhalte schnell unübersichtlich macht. Erwägen Sie in solchen Fällen eine .
• Sinnvolle Beschriftungen: Verwenden Sie klare und präzise Labels, die den Zweck der Checkbox deutlich machen.
• Pflichtfelder markieren: Kennzeichnen Sie erforderliche Checkboxen mit _required.

Anwendungsfälle

• Datenschutzerklärung und Nutzungsbedingungen akzeptieren
• Einwilligungen und Opt-ins erfassen
• Mehrzellige Auswahl aus einer endlichen Liste von Optionen
• Zugriff auf Features oder Dienste gewähren/verweigern
• Filterung oder Auswahl von Eigenschaften in Formularen oder Dashboards

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:

<KolInputCheckbox _icons="fa-solid fa-check" _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" | "_variant" | "_hasCloser" | "_label" | "_level"> & { _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.

---