SingleSelect

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: Dropdown, Auswahlfeld, Einfache Auswahl

Beschreibung: Die SingleSelect-Komponente erstellt eine Auswahlbox, mit der Nutzer:innen genau eine vordefinierte Option aus einer Liste auswählen können. Das Eingabefeld kombiniert die Funktionalität eines Textfelds mit einer Dropdown-Liste und bietet optional eine Suchfunktion zum Filtern der verfügbaren Optionen.

Beispiel

Darstellung der Komponente mit den wesentlichen Eigenschaften. Code kann eingeblendet werden.

<KolSingleSelect _label="Auswählen" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} _placeholder="Bitte wählen Sie eine Option" />

Barrierefreiheit

Die SingleSelect-Komponente wurde mit Fokus auf Barrierefreiheit entwickelt:

• Label-Pflicht: Jede Instanz muss über das Attribut _label eine eindeutige Beschriftung erhalten. Dies gewährleistet, dass Screenreader-Nutzer verstehen, welche Auswahl sie treffen.
• Hinweistexte: Mit _hint können zusätzliche Informationen bereitgestellt werden, die von Screenreadern vorgelesen werden.
• Fehlermeldungen: Mit _msg können Fehlermeldungen ausgegeben werden, die automatisch mit dem Eingabefeld verknüpft sind.
• Tastaturnavigation: Die Komponente ist vollständig über die Tastatur bedienbar mit intuitiver Navigation durch die Optionsliste.
• Statusanzeige: Der gewählte Zustand wird korrekt an assistive Technologien kommuniziert.
• Pflichtfelder: Mit _required gekennzeichnete Felder werden an assistive Technologien signalisiert.

Links und Referenzen

Verwendung

Tastatursteuerung

Taste	Funktion
Tab	Fokussiert das SingleSelect-Feld oder wechselt zum nächsten Element.
Shift + Tab	Wechselt zum vorherigen interaktiven Element.
Leer / Enter	Öffnet die Dropdown-Liste oder wählt die fokussierte Option aus.
Pfeil-oben	Navigiert zur vorherigen Option in der Liste.
Pfeil-unten	Navigiert zur nächsten Option in der Liste.
Pos1	Springt zur ersten Option in der Liste.
Ende	Springt zur letzten Option in der Liste.
Escape	Schließt die Dropdown-Liste ohne zu speichern.
Zeichen	Filtert die Optionen nach Eingabe (bei aktivierter Suchfunktion).

Best Practices / Empfehlungen

• Aussagekräftige Labels: Verwenden Sie klare, verständliche Beschriftungen, die den Zweck der Auswahl deutlich machen.
• Sinnvolle Optionen: Gestalten Sie die Optionsliste nicht zu lang; verwenden Sie bei Bedarf Gruppierung oder Pagination.
• Placeholder sinnvoll nutzen: Der Placeholder sollte nur als ergänzende Hilfe dienen, nicht als Instruktion.
• Standardwert prüfen: Überlegen Sie, ob ein vernünftiger Standardwert gesetzt werden sollte, um Fehlbedienungen zu minimieren.
• Fehlermeldungen konkret: Geben Sie aussagekräftige Validierungsfehlermeldungen über _msg vor.
• Klare Gruppierung: Bei vielen Optionen (mehr als 15) erwägen Sie eine andere Komponente wie eine Tabelle oder Combobox.
• Klare Button: Setzen Sie bei Bedarf einen expliziten Senden/Absenden-Button, um Nutzer:innen Sicherheit zu geben.

Anwendungsfälle

• Auswahl von Titel, Anrede oder Geschlecht in Formularen
• Wahl eines Landes oder einer Region
• Auswahl einer Kategorie oder eines Status
• Filterung nach einem einzigen Kriterium
• Auswahl eines Datums oder einer Uhrzeit aus vordefinierten Werten
• Einzelauswahl in Einstellungen oder Konfigurationen

Konstruktion / Technik

Playground

Testen Sie die verschiedenen Eigenschaften der SingleSelect-Komponente:

Icons

Message

<KolSingleSelect _label="Anrede" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />

Funktionalitäten (mit Code)

Einfache Auswahl

Standard-auswahl mit Beschriftung und Optionsliste:

<KolSingleSelect _label="Auswählen" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />

Placeholder

Ein Placeholder-Text wird angezeigt, wenn noch keine Option ausgewählt wurde:

<KolSingleSelect _label="Auswählen" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} _placeholder="Bitte wählen Sie eine Option" />

Formularattribute

Standard-Attribute für Formulare:

Message

<KolSingleSelect _label="Auswählen" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />

Verfügbare Attribute:

• _required: Kennzeichnet das Feld als Pflichtfeld
• _disabled: Deaktiviert das Eingabefeld
• _hideLabel: Blendet das Label visuell aus (bleibt für assistive Technologien sichtbar)
• _msg: Fehlermeldungen oder Validierungshinweise
• _hideMsg: Blendet die Fehlermeldung visuell aus, erhält sie aber im DOM für aria-describedby

Clear-Button

Der Clear-Button ermöglicht es, die aktuelle Auswahl zu löschen:

<KolSingleSelect _hasClearButton={true} _label="Auswählen" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />

Icons

Links und rechts vom Eingabefeld können Icons angezeigt werden:

Icons

<KolSingleSelect _icons="fa-solid fa-location-dot" _label="Auswählen" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />

Hinweistext und Fehlermeldung

Hinweistexte können vor der Eingabe bereitgestellt werden, Fehlermeldungen nach ungültiger Auswahl:

Message

<KolSingleSelect _hint="Ergänzende Hinweise zur Auswahl" _label="Auswählen" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />

Dropdown-Höhe

Die maximale Anzahl sichtbarer Optionen wird über _rows gesteuert:

<KolSingleSelect _label="Auswählen" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} _rows={3} />

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
click	Eingabefeld wird angeklickt	-
focus	Eingabefeld wird fokussiert	-
blur	Eingabefeld verliert Fokus	-
input	Option wird ausgewählt	value-Attribut der Option
change	Option wird ausgewählt	value-Attribut der Option

API

Overview

The SingleSelect component creates a dropdown list from which exactly one predefined option can be selected.

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
_disabled	_disabled	Makes the element not focusable and ignore all events.	boolean | undefined	false
_hasClearButton	_has-clear-button	Shows the clear button if enabled.	boolean | undefined	true
_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 | { right?: IconOrIconClass | undefined; left?: IconOrIconClass | 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
_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
_options (required)	_options	Options the user can choose from.	Option<StencilUnknown>[] | string	undefined
_placeholder	_placeholder	Defines the placeholder for input field. To be shown when there's no value.	string | undefined	undefined
_required	_required	Makes the input element required.	boolean | undefined	false
_rows	_rows	Maximum number of visible rows of the element.	number | 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'
_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	null

Methods

focus

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
	The label of the input field.

---