InputRange

Synonyme: Slider, Schieberegler, Bereichsregler, Range Input, Range Slider

Beschreibung: Mit InputRange kann ein numerischer Wert innerhalb eines definierten Bereichs ausgewählt werden.

Die Komponente basiert auf dem nativen HTML5-Eingabetyp range für den Schieberegler und ergänzt ihn um ein natives Zahlenfeld (Eingabetyp number). Beide Elemente zeigen denselben Wert an und profitieren von der standardisierten Unterstützung durch Browser und assistive Technologien.

Der Wert kann mit Maus oder Touch über den Schieberegler oder im Zahlenfeld per direkter Eingabe bzw. mit den Pfeiltasten angepasst werden.

Beispiel

Standard-Schieberegler mit Beschriftung und Zahlenfeld:

<KolInputRange _label="Lautstärke" _max={100} _min={0} _step={1} _value={50} />

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.

• Vorschlagswerte (_suggestions) werden über die native Vorschlagsliste des Browsers bereitgestellt. Deren Unterstützung durch Browser und assistive Technologien ist uneinheitlich. Verlassen Sie sich bei unverzichtbaren Eingabehilfen daher nicht ausschließlich auf diese native Autovervollständigung.

• Der native Schieberegler wurde um ein beschriftetes Zahlenfeld ergänzt, über das sich der Wert exakt und ohne Ziehbewegung einstellen lässt. Nutzende, denen präzise Zeigerbewegungen schwerfallen, erhalten damit eine gleichwertige Alternative zum Schieberegler.

Konkrete Designentscheidungen

Entscheidung	Begründung
Kombination aus Schieberegler und Zahlenfeld	Der Schieberegler ermöglicht eine visuelle Auswahl mit Maus und Touch, das Zahlenfeld zeigt den genauen Wert an. Beide Elemente zeigen stets denselben Wert.
Tastaturbedienung über das Zahlenfeld	Der Schieberegler ist nicht per Tastatur erreichbar und wird von Screenreadern nicht ausgegeben. Tastatur- und Screenreader-Nutzende bedienen die Komponente über das beschriftete Zahlenfeld; der Wert wird dadurch nur einmal angesagt.
Breite des Zahlenfelds	Die Breite des Zahlenfelds richtet sich nach der Stellenanzahl von _min und _max (mindestens vier Stellen), damit der Wert vollständig sichtbar bleibt.

Links und Referenzen

Verwendung

• Nutzen Sie _min und _max, um den Wertebereich festzulegen. Ohne Angabe gilt der Bereich von 0 bis 100.
• Verwenden Sie _step, um die Schrittweite festzulegen. Ohne Angabe gilt die native Schrittweite von 1.
• Der über die Events input und change sowie über getValue() gemeldete Wert wird auf _min bzw. _max begrenzt. Ist die jeweilige Grenze 0, findet diese Begrenzung derzeit nicht statt (siehe ).
• Wurde _value als Zeichenkette übergeben (z. B. '50'), liefern Events und getValue() den Wert ebenfalls als Zeichenkette, andernfalls als Zahl.

Hinweis: Im Zahlenfeld können manuell auch Werte außerhalb des Bereichs bzw. Schrittmaßes eingegeben werden. Die Validierung der eingegebenen Werte muss auf Anwendungsebene erfolgen.

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 das Zahlenfeld bzw. das nächste fokussierbare Element setzen. Der Schieberegler wird übersprungen.
Shift+Tab	Fokus auf das vorherige fokussierbare Element setzen.
Pfeil-Tasten (oben/unten)	Erhöht oder verringert den Wert innerhalb von _min und _max entsprechend der in _step angegebenen Schrittweite.
Enter	Umgebendes Formular absenden.

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 vom nativen Schieberegler bekannten Tasten (Pfeil-Tasten (links/rechts), Pos1, Ende, Bild auf/ab) stehen nicht zur Verfügung, da der Schieberegler nicht fokussierbar ist. Die Pfeiltasten links/rechts bewegen im Zahlenfeld den Textcursor.

Best Practices / Empfehlungen

• Verwenden Sie eine aussagekräftige Beschriftung (_label), um den Zweck des Schiebereglers deutlich zu machen.
• Wählen Sie _min, _max und _step so, dass sie den fachlichen Anforderungen entsprechen, beispielsweise _step = 5 für Fünferschritte.
• Nennen Sie Einheiten (z. B. %, €) und die Bedeutung von Minimal- und Maximalwert in _label oder _hint, da das Zahlenfeld nur den reinen Zahlenwert anzeigt.
• Verwenden Sie InputRange für Werte, bei denen eine ungefähre, visuelle Auswahl sinnvoll ist. Für die reine Eingabe exakter Zahlen eignet sich besser.
• Setzen Sie _name, damit der Wert beim Absenden des Formulars übermittelt wird.

Anwendungsfälle

• Lautstärkeregelung in Multimedia-Anwendungen
• Helligkeits- oder Kontrastanpassung
• Festlegen einer Obergrenze in Suchfiltern, beispielsweise eines Höchstpreises oder einer maximalen Entfernung
• Schwellenwerteinstellung in Verwaltungsoberflächen
• Skalierung oder Zoom-Steuerung
• Gewichtung oder Wertfestlegung in Bewertungssystemen

FAQ

Warum kann ich den Schieberegler nicht per Tab-Taste fokussieren?
Der Schieberegler ist nicht Teil der Tab-Reihenfolge und wird mit Maus oder Touch bedient. Tastatur- und Screenreader-Nutzende bedienen die Komponente über das Zahlenfeld, das den gleichen Wert anzeigt und über die Pfeiltasten verändert werden kann.

Kann ich einen Bereich mit zwei Griffen (von–bis) abbilden?
Nein. InputRange verwaltet genau einen Wert. Für einen Wertebereich verwenden Sie zwei separate Felder, beispielsweise zwei InputRange- oder InputNumber-Komponenten für Minimal- und Maximalwert.

Welche Standardwerte gelten für _min und _max?
Ohne Angabe gilt _min = 0 und _max = 100.

Playground

Testen Sie die verschiedenen Eigenschaften der InputRange-Komponente:

Icons

Message

<KolInputRange _label="Wertebereich" _max={100} _min={0} _step={1} _value={50} />

Funktionalitäten

Einfaches Eingabefeld

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.

<KolInputRange _label="Lautstärke" _max={100} _min={0} _step={1} _value={50} />

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!).

Die Property wird auf beide nativen Elemente (Schieberegler und Zahlenfeld) übertragen.

<KolInputRange _label="Helligkeit" _max={100} _min={0} _step={1} _value={50} />

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

<KolInputRange _hideMsg={false} _hint="Wählen Sie einen Wert zwischen 10 und 90 %." _label="Lautstärke (%)" _max={100} _min={0} _msg={{ "_description": "Der Wert muss zwischen 10 und 90 liegen." }} _step={1} _touched={true} _value={5} />

Wertebereich und Schrittweite

Mit _min, _max und _step legen Sie den Wertebereich und die Schrittweite fest. Die Grenzen gelten für den Schieberegler und die Bedienung mit den Pfeiltasten im Zahlenfeld. Bei manueller Eingabe im Zahlenfeld können dennoch Werte außerhalb des Bereichs eingegeben werden; die an Events übergebenen Werte werden auf _min bzw. _max begrenzt (siehe Verwendung).

• _min: Minimaler Wert (Standard 0)
• _max: Maximaler Wert (Standard 100)
• _step: Schrittweite für Schieberegler und Pfeiltasten

<KolInputRange _label="Höchstpreis (€)" _max={1000} _min={0} _step={50} _value={250} />

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.

<KolInputRange _hideLabel={false} _label="Lautstärke" _max={100} _min={0} _step={1} _value={50} />

Icons

Mit _icons versehen Sie das Feld links und/oder rechts mit zusätzlichen Icons, um visuellen Kontext zu geben.

Verfügbare Positionen sind:

• left: Icon links vom Feld
• right: Icon rechts vom Feld

Wird ein Icon nur über seine Icon-Klasse angegeben, gilt es als dekorativ und wird vor assistiven Technologien verborgen. Trägt ein Icon eine Information, die nicht bereits aus Label oder Hinweis hervorgeht, übergeben Sie es als Objekt mit label – das Icon erhält dann eine zugängliche Beschriftung.

Icons

<KolInputRange _icons={{ "left": "kolicon-kolibri" }} _label="Zoom" _max={100} _min={0} _step={1} _value={50} />

Vorschlagswerte (Suggestions)

Mit _suggestions schlagen Sie Nutzenden häufig verwendete Werte vor, um die Eingabe zu beschleunigen. Die Vorschläge werden über das native HTML-Element datalist bereitgestellt. Darstellung und Bedienung der Vorschlagsliste hängen daher vom Browser ab.

Bei InputRange ist die Vorschlagsliste mit dem Schieberegler und dem Zahlenfeld verknüpft. Je nach Browser werden die Werte am Schieberegler als Markierungen und am Zahlenfeld als Auswahlliste angezeigt.

<KolInputRange _label="Deckkraft (%)" _max={100} _min={0} _step={1} _suggestions={[ 0, 25, 50, 75, 100 ]} _value={50} />

API

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
click	Komponente wird angeklickt	-
focus	Zahlenfeld wird fokussiert	-
blur	Zahlenfeld verliert Fokus	-
keydown	Taste wird im Zahlenfeld gedrückt	-
input	Wert wird durch Eingabe oder Schieben geändert	Aktueller Wert, begrenzt auf _min/_max (Zahl oder Zeichenkette)
change	Eingabe wurde abgeschlossen	Aktueller Wert, begrenzt auf _min/_max (Zahl oder Zeichenkette)

Overview

The Range input type creates a slider control for selecting a numeric value within a defined range. Use the _min, _max, and _step properties to configure the range and step size.

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
_autoComplete	_auto-complete	Defines whether the input can be auto-completed.	string | undefined	'off'
_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 | { right?: IconOrIconClass | undefined; left?: IconOrIconClass | 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
_max	_max	Defines the maximum value of the element.	`${number}.${number}` | `${number}` | number | undefined	100
_min	_min	Defines the smallest possible input value.	`${number}.${number}` | `${number}` | number | undefined	0
_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
_shortKey	_short-key	Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud.	string | undefined	undefined
_step	_step	Defines the step size for value changes.	`${number}.${number}` | `${number}` | number | undefined	undefined
_suggestions	_suggestions	Suggestions to provide for the input.	W3CInputValue[] | 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.	`${number}.${number}` | `${number}` | number | undefined	undefined
_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<number | NumberString | undefined>

Returns the current value.

Returns

Type: Promise<number | NumberString | undefined>

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

---