InputNumber
Synonyme: Zahlenfeld, Numerisches Eingabefeld, Zahleneingabe, Number Input, Number Field
Beschreibung: Mit InputNumber können numerische Werte eingegeben und bearbeitet werden.
Die Komponente basiert auf dem nativen HTML5-Eingabetyp number und profitiert dadurch von dessen Semantik sowie der standardisierten Unterstützung durch Browser und assistive Technologien.
Neben der direkten Eingabe kann der Wert über die Erhöhen-/Verringern-Schaltflächen oder mithilfe der Pfeiltasten angepasst werden.
Beispiel
Standard-Eingabefeld für numerische Werte ohne optional gesetzte Felder:
<KolInputNumber _label="Zahleneingabe" />Barrierefreiheit
- Die nativen HTML5-Eingabetypen werden von Browsern und assistiven Technologien standardisiert unterstützt.
- Das Eingabefeld muss mit einer aussagekräftigen Beschriftung (
_label) versehen werden. - Zusätzliche Hinweise können über
_hint, Fehlermeldungen über_msgbereitgestellt werden. - Mit
_requiredgekennzeichnete Felder werden über das nativerequired-Attribut an assistive Technologien kommuniziert.
Konkrete Designentscheidungen
| Entscheidung | Begründung |
|---|---|
Verwendung des nativen HTML5-Eingabetyps number | Die Komponente nutzt bewusst den nativen HTML5-Eingabetyp 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. Tastaturnutzende können den Wert stattdessen über die Pfeiltasten im Eingabefeld entsprechend der in _step definierten Schrittweite anpassen. |
Links und Referenzen
Verwendung
- Nutzen Sie
_minund_max, um zulässige Wertebereiche einzuschränken. - Verwenden Sie
_step, um die Schrittweite für die Wertänderung festzulegen. - Berücksichtigen Sie, dass
_stepsowohl die Bedienung über die Pfeiltasten und Erhöhen-/Verringern-Schaltflächen als auch die zulässigen Eingabewerte beeinflusst.
Hinweis: _min, _max und _step verhindern keine manuelle Eingabe außerhalb des zulässigen Wertebereichs bzw. Schrittmaßes. Die Einschränkungen wirken sich hauptsächlich auf die integrierten Erhöhen-/Verringern-Schaltflächen und die Bedienung mit den Pfeiltasten aus. Die Validierung der manuell 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 Eingabefeld bzw. das nächste fokussierbare Element setzen. |
Shift+Tab | Fokus auf das vorherige fokussierbare Element setzen. |
Pfeil-Tasten (oben/unten) | Erhöht oder veringert den Wert innerhalb der Attribute '_min' oder '_max' entsprechen der im Attribut '_step' angegebenen Schrittgröße. |
Die Erhöhen-/Verringern-Schaltflächen sind nicht Teil der Tab-Reihenfolge. Ihre Funktion steht Tastaturnutzenden über die Pfeiltasten im fokussierten Eingabefeld zur Verfügung.
Hinweis: Sind _min und/oder _max gesetzt, kann der Wert über die Pfeiltasten nur innerhalb dieses Wertebereichs verändert werden. Bei manueller Eingabe können hingegen auch Werte außerhalb des definierten Bereichs eingegeben werden. Die Validierung der manuell eingegebenen Werte muss auf Anwendungsebene erfolgen.
Best Practices / Empfehlungen
- Verwenden Sie InputNumber ausschließlich für Werte, die mathematisch verarbeitet werden. Für Telefonnummern, Postleitzahlen, Kreditkarten- oder Identifikationsnummern sollten stattdessen Texteingabefelder verwendet werden.
- Wählen Sie
_min,_maxund_stepso, dass sie den fachlichen Anforderungen des jeweiligen Anwendungsfalls entsprechen. - Stellen Sie sicher, dass zulässige Wertebereiche oder Einheiten für Nutzende eindeutig erkennbar sind, beispielsweise über die Beschriftung (
_label) oder ergänzende Hinweise (_hint). - Berücksichtigen Sie, dass sich Darstellung und Verhalten nativer numerischer Eingabefelder je nach Browser und Betriebssystem unterscheiden können.
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
FAQ
Wann sollte ich _step, _min und _max verwenden?
Verwenden Sie _min und _max, um den zulässigen Wertebereich einzuschränken. Mit _step legen Sie fest, in welchen Schritten der Wert angepasst werden kann. Diese Attribute unterstützen dabei, numerische Eingaben an den jeweiligen Anwendungsfall anzupassen.
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 ein Theme-seitiges Feature-Flag ausgeblendet werden.
Konstruktion / Technik
Playground
Testen Sie die verschiedenen Eigenschaften des InputNumber-Feldes:
<KolInputNumber _label="Zahleneingabe" />Funktionalitäten (mit Code)
Einfaches Eingabefeld
Minimum-Konfiguration mit Label:
<KolInputNumber _label="Zahleneingabe" />Formularattribute
Standard-Attribute für Formulare wie Deaktivierung, Read-Only-Modus und Pflichtfelder:
<KolInputNumber _label="Anzahl" />Verfügbare Attribute:
_disabled: Deaktiviert das Eingabefeld (mit Begründung verwenden!)_readOnly: Verhindert die Bearbeitung des Feldes_required: Kennzeichnet Pflichtfelder
Hinweistexte und Fehlermeldungen
Unterstützung für Hinweistexte und Validierungsmeldungen:
<KolInputNumber _hint="Bitte geben Sie einen Wert in EUR an" _label="Preis" />Verfügbare Attribute:
_hint: Ergänzende Hinweise zur Eingabe (wird immer angezeigt)_msg: Fehlermeldungen oder Validierungshinweise
Numerische Beschränkungen
Konfigurieren Sie Minimal-, Maximalwerte und Schrittweite. _min und _max greifen zuverlässig nur bei der Auswahl über den Steuerelemente. Bei manueller Texteingabe kann ein Wert außerhalb des definierten Bereichs eingegeben werden, ohne dass automatisch eine Korrektur oder Fehlermeldung erfolgt. Die Validierung manueller Eingaben liegt in der Verantwortung der einbindenden Anwendung.
<KolInputNumber _label="Menge" _max={100} _min={1} _step={5} />Verfügbare Attribute:
_min: Minimaler erlaubter Wert_max: Maximaler erlaubter Wert_step: Schrittweite für Pfeiltasten und Spinner
Placeholder und Label-Steuerung
Nutzen Sie Placeholder zur Eingabeformatierung und _hideLabel, um das Label visuell auszublenden:
<KolInputNumber _hideLabel={false} _label="Alter" _placeholder="z.B. 25" />Verfügbare Attribute:
_placeholder: Platzhaltertext (verschwindet beim Tippen)_hideLabel: Blendet das Label visuell aus (bleibt für assistive Technologien sichtbar)
Icons
Definieren Sie linke und/oder rechte Icons für zusätzlichen Kontext:
<KolInputNumber _icons={{ "left": "kolicon-euro" }} _label="Preis" />Verfügbare Positionen:
left: Icon links vom Eingabefeldright: Icon rechts vom Eingabefeld
SmartButton
Ein Button mit beliebiger Aktion kann im Feld platziert werden (nur mit _hideLabel):
<KolInputNumber _hideLabel={true} _label="Mit SmartButton" _placeholder="Platzhalter" _smartButton={{ "_label": "Action" }} />Vorschlagswerte (Suggestions)
Über _suggestions können Vorschlagswerte für die Autovervollständigung bereitgestellt werden:
<KolInputNumber _label="Anzahl" _suggestions={[ 1, 5, 10, 25, 50, 100 ]} />Verfügbare Attribute:
_suggestions: Liste von Vorschlagswerten für die Datalist-Autovervollständigung
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 | Wert wird durch Eingabe geändert | Aktueller Wert des Eingabefelds |
change | Eingabe wurde abgeschlossen | Aktueller Wert des Eingabefelds |
API
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 |
_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 (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 |
_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; } & { _type?: "button" | "reset" | "submit" | undefined; _accessKey?: string | undefined; _on?: ButtonCallbacksPropType<StencilUnknown> | undefined; _ariaExpanded?: boolean | undefined; _tabIndex?: number | undefined; _value?: StencilUnknown; _role?: "tab" | "treeitem" | undefined; _ariaControls?: string | undefined; _ariaDescription?: string | undefined; _ariaSelected?: boolean | 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; _variant?: 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}` | null | number | undefined | undefined |
_variant | _variant | Defines which variant should be used for presentation. | string | undefined | undefined |
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<number | NumberString | null>
Returns the current value.
Returns
Type: Promise<number | NumberString | null>
Slots
| Slot | Description |
|---|---|
| The label of the input field. |