InputNumber

Synonyme: Zahlenfeld, Numerisches Eingabefeld, Zahleneingabe, Number Input, Number Field

Beschreibung: Mit InputNumber können numerische Werte eingegeben und bearbeitet werden. Der Wert kann direkt eingegeben oder über Erhöhen-/Verringern-Schaltflächen und Pfeiltasten angepasst werden.

Anwendungsfälle:

• Altersangaben in Registrierungs- oder Kontaktformularen
• Eingabe von Mengen, Stückzahlen oder Preisen
• Erfassung von Messwerten wie Gewicht, Länge oder Temperatur
• Konfiguration numerischer Einstellungen, beispielsweise für Grenz- oder Schwellenwerte
• Eingabe von Prozentwerten oder Rabattangaben

Beispiel

Standard-Eingabefeld für numerische Werte ohne optional gesetzte Felder:

<KolInputNumber _label="Zahleneingabe" _value={0} />

Barrierefreiheit

• Die native Semantik des Eingabefeldes ermöglicht es Screenreadern, Spracheingabe und Betriebssystem-Tastaturen (z. B. numerisches Layout auf Mobilgeräten), das Feld automatisch als Zahleneingabe zu erkennen.
• Die Komponente ist vollumfänglich tastaturbedienbar. Mit den Pfeiltasten können Werte erhöht und verringert werden, Enter sendet das umgebende Formular ab und Access- bzw. Shortkeys ermöglichen einen direkten Sprung ins Feld.

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

• Das Eingabefeld wurde um zwei Buttons zum Erhöhen und Verringern ergänzt, deren Größe barrierefreien Anforderungen entspricht.

Konkrete Designentscheidungen

Entscheidung	Begründung
Verwendung des nativen HTML5-Eingabetyps number	Die Komponente nutzt bewusst den nativen HTML5-Eingabetyp statt eines Custom-Elements und profitiert dadurch von dessen standardisierter Unterstützung durch Browser und assistive Technologien.
Erhöhen-/Verringern-Schaltflächen	Neben der direkten Eingabe stellt die Komponente standardmäßig Erhöhen-/Verringern-Schaltflächen für die Bedienung mit Maus und Touch bereit.
Tastaturbedienung	Die Erhöhen-/Verringern-Schaltflächen sind nicht per Tastatur fokussierbar und mittels aria-hidden vollständig aus dem Accessibility-Tree entfernt. Tastaturnutzende und Screenreader-Nutzende können den Wert stattdessen über die Pfeiltasten im Eingabefeld entsprechend der in _step definierten Schrittweite anpassen.

Links und Referenzen

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 Eingabefeld bzw. das nächste fokussierbare Element setzen.
Shift+Tab	Fokus auf das vorherige fokussierbare Element setzen.
Pfeil-Tasten (oben/unten)	Erhöht oder verringert den Wert innerhalb der Attribute _min oder _max entsprechend der im Attribut _step angegebenen Schrittgröße.
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 Erhöhen-/Verringern-Schaltflächen sind nicht fokussierbar – die gleiche Funktionalität steht über die Pfeiltasten zur Verfügung.

Sind _min und/oder _max gesetzt, kann der Wert über die Pfeiltasten nur innerhalb dieses Wertebereichs verändert werden.

FAQ

Wie schränke ich Wertebereiche ein?
Verwenden Sie _min, um den minimalen und _max, um den maximalen erlaubten Wert zu definieren. Diese Attribute wirken zuverlässig bei der Bedienung über Pfeiltasten und Schaltflächen. Beachten Sie aber: Bei manueller Texteingabe können Werte außerhalb des Bereichs eingegeben werden. Die Validierung manuell eingegebener Werte muss auf Anwendungsebene erfolgen.

Wie kann ich die Schrittweite definieren?
Mit _step legen Sie fest, um wie viel der Wert bei jedem Schritt angepasst wird – sowohl bei Pfeiltasten als auch bei den Erhöhen-/Verringern-Schaltflächen. Das Attribut beeinflusst auch, welche manuell eingegebenen Werte technisch gültig sind, führt aber nicht zu automatischer Validierung oder Korrektur.

Wofür sollte ich InputNumber nicht verwenden?
Verwenden Sie InputNumber ausschließlich für Werte, die mathematisch verarbeitet werden. Für Telefonnummern, Postleitzahlen, Kreditkarten- oder Identifikationsnummern sollten Sie stattdessen Texteingabefelder verwenden.

Wie stelle ich sicher, dass Wertebereiche für Nutzende klar sind?
Nutzen Sie die Beschriftung (_label) und ergänzende Hinweise (_hint), um zulässige Wertebereiche oder Einheiten deutlich zu machen. Wählen Sie _min, _max und _step so, dass sie den fachlichen Anforderungen Ihres Anwendungsfalls entsprechen.

Warum unterscheiden sich Eingabefelder je nach Browser?
Das ist normales Verhalten nativer HTML5-Eingabefelder. Darstellung und Verhalten können je nach Browser und Betriebssystem unterscheiden.

Sind die Erhöhen-/Verringern-Schaltflächen fokussierbar?
Nein. Die Erhöhen-/Verringern-Schaltflächen sind nicht Teil der Tab-Reihenfolge. Tastaturnutzende können den Wert stattdessen über die Pfeiltasten im Eingabefeld anpassen.

Können die Erhöhen-/Verringern-Schaltflächen ausgeblendet werden?
Ja. Die Erhöhen-/Verringern-Schaltflächen können über das Theme-seitige Feature-Flag inputNumberButtons (Wert 'hide') ausgeblendet werden.

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.

<KolInputNumber _label="Zahleneingabe" _value={0} />

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

• _readOnly: Verhindert die Bearbeitung des Feldes. Das Feld bleibt fokussierbar und lesbar. Hinter der Beschriftung erscheint zusätzlich der Hinweis „(schreibgeschützt)“; er ist vor assistiven Technologien verborgen, da der Zustand bereits über das native readonly-Attribut vermittelt wird.

• _required: Kennzeichnet das Feld als Pflichtfeld.

Die Properties werden 1:1 auf die gleichnamigen nativen HTML-Attribute des input-Elements übertragen.

<KolInputNumber _label="Anzahl" _value={0} />

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

<KolInputNumber _hideMsg={false} _hint="Bitte geben Sie einen Wert in EUR an" _label="Preis" _msg={{ "_description": "Bitte geben Sie einen gültigen Preis an." }} _touched={true} _value={0} />

Numerische Beschränkungen

Mit _min, _max und _step grenzen Sie den zulässigen Wertebereich und die Schrittweite der Eingabe ein, um von vornherein unplausible oder ungültige Werte zu vermeiden. Diese Einschränkung wirkt zuverlässig jedoch nur bei der Bedienung über die Steuerelemente (Erhöhen-/Verringern-Schaltflächen und Pfeiltasten): Bei manueller Texteingabe kann dennoch ein Wert außerhalb des definierten Bereichs eingegeben werden, ohne dass automatisch eine Korrektur oder Fehlermeldung erfolgt. Die Validierung manuell eingegebener Werte liegt daher in der Verantwortung der einbindenden Anwendung.

Verfügbare Attribute sind:

• _min: Minimaler erlaubter Wert
• _max: Maximaler erlaubter Wert
• _step: Schrittweite für Pfeiltasten und Spinner

<KolInputNumber _label="Menge" _max={100} _min={5} _step={5} _value={5} />

Placeholder

Mit _placeholder zeigen Sie einen Platzhaltertext an, solange noch kein Wert eingegeben bzw. ausgewählt ist – etwa ein Format- oder Eingabebeispiel. Der Platzhalter ist kein Ersatz für die Beschriftung (_label), da er nach der Eingabe verschwindet und von assistiven Technologien nicht zuverlässig ausgegeben wird.

<KolInputNumber _label="Alter" _placeholder="z.B. 25" />

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.

<KolInputNumber _hideLabel={false} _label="Alter" />

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

<KolInputNumber _icons={{ "left": "kolicon-kolibri" }} _label="Preis" _value={0} />

SmartButton

Mit _smartButton platzieren Sie einen Button mit beliebiger Aktion direkt im Eingabefeld, etwa um eine zugehörige Funktion griffbereit anzubieten. Der SmartButton wird immer als Icon-Button ohne sichtbare Beschriftung dargestellt; sein _label dient als zugänglicher Name und muss die Aktion daher eindeutig beschreiben. Der SmartButton ist per Tastatur erreichbar und wird zusammen mit dem Feld deaktiviert (_disabled).

<KolInputNumber _label="Mit SmartButton" _placeholder="Platzhalter" _smartButton={{ "_label": "Action" }} />

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.

<KolInputNumber _label="Anzahl" _suggestions={[ 1, 5, 10, 25, 50, 100 ]} />

Playground

Testen Sie die verschiedenen Eigenschaften des InputNumber-Feldes:

Icons

Message

<KolInputNumber _label="Zahleneingabe" _value={0} />

API

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
click	Eingabefeld wird angeklickt	-
focus	Eingabefeld wird fokussiert	-
blur	Eingabefeld verliert Fokus	-
keydown	Taste wird im Eingabefeld gedrückt	-
input	Wert wird durch Eingabe geändert	Aktueller Wert des Eingabefelds
change	Eingabe wurde abgeschlossen	Aktueller Wert des Eingabefelds

Overview

The Number input type creates an input field for numeric values. Use the _min, _max, and _step properties to restrict the accepted value range.

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	undefined
_min	_min	Defines the smallest possible input value.	`${number}.${number}` | `${number}` | number | undefined	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
_placeholder	_placeholder	Defines the placeholder for input field. To be shown when there's no value.	string | undefined	undefined
_readOnly	_read-only	Makes the input element read only.	boolean | undefined	false
_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
_smartButton	_smart-button	Allows to add a button with an arbitrary action within the element (_hide-label only).	string | undefined | { _label: string; } & { _ariaExpanded?: boolean | undefined; _tabIndex?: number | undefined; _value?: StencilUnknown; _accessKey?: string | undefined; _role?: "tab" | "treeitem" | undefined; _ariaControls?: string | undefined; _ariaDescription?: string | undefined; _ariaSelected?: boolean | undefined; _on?: ButtonCallbacksPropType<StencilUnknown> | undefined; _type?: "button" | "reset" | "submit" | undefined; _variant?: VariantClassNamePropType | undefined; _customClass?: string | undefined; _disabled?: boolean | undefined; _hideLabel?: boolean | undefined; _icons?: IconsPropType | undefined; _id?: string | undefined; _inline?: boolean | undefined; _name?: string | undefined; _shortKey?: string | undefined; _syncValueBySelector?: string | undefined; _tooltipAlign?: AlignPropType | 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}` | null | 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 | null>

Returns the current value.

Returns

Type: Promise<number | NumberString | null>

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

---