InputRadio

Synonyme: Optionsfeld, Radiobutton, Radio Buttons, Radio Group, Auswahlgruppe, Choice Group

Beschreibung: Mit InputRadio wählen Nutzende genau eine Option aus einer Gruppe sich gegenseitig ausschließender Optionen aus.

Die Komponente basiert auf dem nativen HTML5-Eingabetyp radio und profitiert dadurch von dessen Semantik sowie der standardisierten Unterstützung durch Browser und assistive Technologien. KoliBri fasst die Radio-Buttons einer Gruppe in einem nativen fieldset zusammen und gibt die Beschriftung der Gruppe als legend aus.

Beispiel

Standard-Auswahlgruppe mit drei Optionen ohne optional gesetzte Felder:

<KolInputRadio _label="Anrede" _options={[ { "label": "Herr", "value": "male" }, { "label": "Frau", "value": "female" }, { "label": "Firma", "value": "company" } ]} />

Barrierefreiheit

• Die Auswahlgruppe muss mit einer aussagekräftigen Beschriftung (_label) versehen werden. Auch jede Option benötigt eine eindeutige Beschriftung (label in _options).

• 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.

• Radio-Button und Beschriftung einer Option bilden eine gemeinsame Klickfläche, die mindestens der barrierefreien Mindestgröße für Bedienelemente entspricht.
• Der ausgewählte Zustand bleibt auch im Kontrastmodus des Betriebssystems (Forced Colors) sichtbar.
• Die Komponente markiert das aktuell fokussierte Element deutlich.

Konkrete Designentscheidungen

Entscheidung	Begründung
Gruppierung mit fieldset und legend	Die Komponente nutzt die nativen HTML-Elemente zur Gruppierung von Formularfeldern. Screenreader geben den Gruppennamen beim Betreten der Gruppe aus.
Native Tastaturbedienung	Die Bedienung mit Tab- und Pfeiltasten übernimmt der Browser: Die Gruppe bildet einen einzelnen Tab-Stopp, die Pfeiltasten wechseln die Auswahl. KoliBri ergänzt lediglich das Absenden des Formulars per Enter.
Gruppenbeschriftung bleibt sichtbar	Die Beschriftung der Gruppe wird auch bei _hideLabel nicht ausgeblendet. _hideLabel wirkt ausschließlich auf die Beschriftungen der einzelnen Optionen.
Hinweis- und Fehlertexte an der Gruppe	Hinweise und Fehlermeldungen beziehen sich auf die Gruppe als Ganzes und werden beim Betreten der Gruppe ausgegeben. Im Fehlerfall wird jeder Radio-Button als ungültig ausgegeben.
Fokus auf die ausgewählte Option	Die Methode focus() setzt den Fokus auf die ausgewählte Option bzw. – falls keine Option ausgewählt ist – auf die erste nicht deaktivierte Option. Das entspricht dem Einstiegspunkt, den auch die Tab-Taste wählt.

Links und Referenzen

Verwendung

• Verwenden Sie InputRadio, wenn genau eine von mehreren Optionen ausgewählt werden muss. Für unabhängig voneinander wählbare Optionen nutzen Sie die Komponente .
• Definieren Sie die Optionen über _options als Array von Objekten mit label und value. Einzelne Optionen können über disabled: true deaktiviert werden.
• Steuern Sie die ausgewählte Option über _value. Der Wert muss dem value einer Option entsprechen.
• Legen Sie mit _orientation fest, ob die Optionen untereinander (vertical, Standard) oder nebeneinander (horizontal) angeordnet werden.
• Setzen Sie _name, damit der Wert beim Absenden des Formulars unter dem gewünschten Namen übermittelt wird.

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 in die Gruppe setzen – auf die ausgewählte Option bzw. die erste Option, wenn noch keine ausgewählt ist – oder die Gruppe verlassen.
Shift+Tab	Fokus auf das vorherige fokussierbare Element setzen.
Pfeil-Tasten	Fokus auf die nächste bzw. vorherige Option setzen und diese auswählen – unabhängig von _orientation.
Leertaste	Fokussierte Option auswählen, falls sie noch nicht ausgewählt ist.
Enter	Sendet das umgebende Formular ab (KoliBri-Ergänzung, siehe Hinweis).

Deaktivierte Optionen werden bei der Bedienung mit den Pfeiltasten übersprungen.

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.

Die Auswahl wird dabei nicht verändert.

Best Practices / Empfehlungen

• Verwenden Sie für die Gruppe eine klare, präzise Beschriftung, die den Zweck der Auswahl deutlich macht, beispielsweise „Anrede“ oder „Versandart“.
• Formulieren Sie die Beschriftungen der Optionen kurz, eindeutig und voneinander unterscheidbar.
• Begrenzen Sie die Anzahl der Optionen auf etwa 3–7. Für umfangreichere Auswahllisten sind die Komponenten oder besser geeignet.
• Wählen Sie eine Option nur dann vor, wenn es einen fachlich sinnvollen Standardwert gibt; ein solcher Standardwert unterstützt die Benutzerführung. Bei Pflichtangaben, die bewusst getroffen werden sollen, verzichten Sie auf eine Vorauswahl.
• Nutzen Sie _orientation="vertical" bei mehreren Optionen, um das Überfliegen der Liste zu erleichtern. _orientation="horizontal" eignet sich für wenige, kurze Optionen.
• Deaktivieren Sie einzelne Optionen nur, wenn sie tatsächlich nicht verfügbar sind, und erläutern Sie den Grund möglichst im sichtbaren Kontext. Andernfalls blenden Sie nicht verfügbare Optionen besser aus. Für dynamische Filterung verwenden Sie statt deaktivierter Radio-Elemente die oder andere Komponenten.
• Geben Sie zusätzliche Erklärungen über _hint an, falls die Optionen nicht selbsterklärend sind.

Anwendungsfälle

• Auswahl einer Geschlechtsangabe oder Anrede
• Wahl zwischen Zahlungsmethoden, beispielsweise Kreditkarte, Überweisung oder PayPal
• Auswahl von Lieferoptionen, beispielsweise Express, Standard oder Economy
• Beantwortung von Einfachauswahl-Fragen in Umfragen
• Auswahl der Kundenart bei der Registrierung, beispielsweise Privatperson oder Unternehmen
• Festlegen von Prioritätsstufen in Ticketing-Systemen

FAQ

Kann ich die Beschriftung der Gruppe ausblenden?
Nein. Die Beschriftung der Gruppe (legend) bleibt immer sichtbar. _hideLabel blendet ausschließlich die Beschriftungen der einzelnen Optionen visuell aus.

Ändert sich die Tastaturbedienung bei horizontaler Ausrichtung?
Nein. _orientation verändert nur die Anordnung. Die Optionen können in beiden Ausrichtungen mit allen Pfeiltasten gewechselt werden.

Welcher Wert wird bei den Events übermittelt?
Die Events input und change übermitteln den value der ausgewählten Option aus _options – nicht das technische value-Attribut des nativen Radio-Buttons.

Playground

Testen Sie die verschiedenen Eigenschaften der InputRadio-Komponente:

Options (Label/Value)

Orientation

Message

<KolInputRadio _label="Anrede" _options={[ { "label": "Herr", "value": "male" }, { "label": "Frau", "value": "female" }, { "label": "Firma", "value": "company" } ]} />

Funktionalitäten

Optionen und Beschriftung

Jede Auswahlgruppe benötigt eine Beschriftung (_label), die als legend der Gruppe ausgegeben wird. Die Optionen definieren Sie über _options als Array von Objekten mit label und value. Jede Option wird als natives label-Element mit ihrem Radio-Button verknüpft.

Options (Label/Value)

<KolInputRadio _label="Versandart" _options={[ { "label": "Express (1–2 Tage)", "value": "express" }, { "label": "Standard (3–5 Tage)", "value": "standard" }, { "label": "Economy (5–10 Tage)", "value": "economy" } ]} />

Ausrichtung

Mit _orientation legen Sie fest, ob die Optionen untereinander (vertical, Standard) oder nebeneinander (horizontal) angeordnet werden. Die Tastaturbedienung bleibt davon unberührt.

Orientation

<KolInputRadio _label="Zahlungsmethode" _options={[ { "label": "Kreditkarte", "value": "card" }, { "label": "Überweisung", "value": "transfer" }, { "label": "PayPal", "value": "paypal" } ]} _orientation="horizontal" />

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.

_disabled deaktiviert alle Optionen der Gruppe; einzelne Optionen deaktivieren Sie über disabled: true in _options. _required wird auf das native required-Attribut der Radio-Buttons übertragen. Mit _name legen Sie den technischen Namen fest, unter dem der Wert übermittelt wird.

<KolInputRadio _label="Anrede" _options={[ { "label": "Herr", "value": "male" }, { "label": "Frau", "value": "female" }, { "label": "Firma", "value": "company", "disabled": true } ]} />

Hinweistexte und Fehlermeldungen

Mit _hint und _msg geben Sie Nutzenden zusätzliche Orientierung zur Auswahl und machen Validierungsfehler unmittelbar an der Gruppe sichtbar:

• _hint: Ergänzende Hinweise zur Auswahl (wird immer angezeigt und über aria-describedby mit der Gruppe verknüpft)
• _msg: Fehlermeldungen oder Validierungshinweise (wird nur in Verbindung mit _touched angezeigt)
• _touched: Zeigt an, ob die Gruppe von Nutzenden bereits angefasst wurde, und steuert damit, ob _msg sichtbar wird
• _hideMsg: Unterdrückt die Fehlermeldung an der Gruppe, 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 angezeigt. Handelt es sich um eine Fehlermeldung, werden zusätzlich alle Radio-Buttons der Gruppe über aria-invalid als ungültig gekennzeichnet.

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

Message

<KolInputRadio _hideMsg={false} _hint="Die Lieferzeit beginnt ab Zahlungseingang." _label="Versandart" _msg={{ "_description": "Bitte wählen Sie eine Versandart aus." }} _options={[ { "label": "Express (1–2 Tage)", "value": "express" }, { "label": "Standard (3–5 Tage)", "value": "standard" }, { "label": "Economy (5–10 Tage)", "value": "economy" } ]} _touched={true} />

Beschriftungen der Optionen ausblenden

Mit _hideLabel blenden Sie bei InputRadio nicht die Beschriftung der Gruppe, sondern die Beschriftungen der einzelnen Optionen visuell aus. Für assistive Technologien bleibt die Beschriftung jeder Option als zugänglicher Name (aria-label) verfügbar; sehende Nutzende erhalten sie bei Maus-Hover und Tastaturfokus als Tooltip. Die legend der Gruppe bleibt sichtbar.

Nutzen Sie diese Möglichkeit nur, wenn die Bedeutung der einzelnen Optionen durch den visuellen Kontext eindeutig ist.

<KolInputRadio _hideLabel={true} _label="Zufriedenheit" _options={[ { "label": "Sehr unzufrieden", "value": 1 }, { "label": "Unzufrieden", "value": 2 }, { "label": "Neutral", "value": 3 }, { "label": "Zufrieden", "value": 4 }, { "label": "Sehr zufrieden", "value": 5 } ]} _orientation="horizontal" />

API

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Die Events focus und blur beziehen sich auf die Gruppe als Ganzes: Ein Wechsel des Fokus zwischen den Optionen löst sie nicht erneut aus.

Event	Auslöser	Value
focus	Fokus gelangt in die Auswahlgruppe	-
blur	Fokus verlässt die Auswahlgruppe	-
keydown	Taste wird bei fokussierter Option gedrückt	-
input	Option wird ausgewählt	value der ausgewählten Option
change	Option wird ausgewählt	value der ausgewählten Option

Overview

The InputRadio input type consists of a collection of radio elements, providing a choice between different values. Only a single value can be selected at a time. Selected radio elements are typically represented by a filled, visually highlighted circle.

Properties

Property	Attribute	Description	Type	Default
_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
_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	''
_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
_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
_options	_options	Options the user can choose from.	RadioOption<StencilUnknown>[] | string | undefined	undefined
_orientation	_orientation	Defines whether the orientation of the component is horizontal or vertical.	"horizontal" | "vertical" | undefined	'vertical'
_required	_required	Makes the input element required.	boolean | undefined	false
_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
_variant	_variant	Defines which variant should be used for presentation.	string | string[] | undefined	undefined

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

---