InputNumber

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: Nummernfeld, Zahleneingabe, numerisches Eingabefeld

Beschreibung: Die InputNumber-Komponente ist ein spezialisiertes Eingabefeld für numerische Werte. Sie unterstützt Beschränkungen durch Minimal- und Maximalwerte sowie configurable Schrittweiten und ermöglicht eine barrierefreie Eingabe von Zahlen.

Beispiel

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

<KolInputNumber _label="Zahleneingabe" />

Barrierefreiheit

Die InputNumber-Komponente wurde mit Fokus auf Barrierefreiheit entwickelt:

• Label-Pflicht: Jedes InputNumber-Feld muss über das Attribut _label eine sichtbare Beschriftung erheben. Dies gewährleistet, dass Screenreader-Nutzer verstehen, welchen Zweck das Eingabefeld erfüllt.
• Hinweistexte: Mit _hint können zusätzliche Informationen bereitgestellt werden, die von Screenreadern vorgelesen werden.
• Fehlermeldungen: Das Attribut _msg ermöglicht aussagekräftige Fehlermeldungen, die von assistiven Technologien erkannt werden.
• Fokusmanagement: Das Feld ist vollständig über die Tastatur bedienbar mit klaren Fokusindikatoren.
• Pflichtfelder: Mit _required gekennzeichnete Felder werden korrekt an assistive Technologien kommuniziert.
• Pfeiltasten-Steuerung: Die Auf- und Ab-Pfeiltasten ermöglichen eine feinkörnige Wertanpassung für Nutzer, die keine genaue Wertangabe eingeben möchten.

Links und Referenzen

Verwendung

Tastatursteuerung

Taste	Funktion
Tab	Fokussiert das Eingabefeld.
Shift + Tab	Wechselt zum vorherigen interaktiven Element.
Pfeil-Tasten (oben / unten)	Erhöht oder verringert den Wert innerhalb der Attribute _min und _max entsprechend der im Attribut _step angegebenen Schrittgröße.

Best Practices / Empfehlungen

• Sinnvolle Grenzen setzen: Verwenden Sie _min und _max, um Wertbereiche zu definieren. Dies verbessert sowohl die Nutzererfahrung als auch die Datenvalidierung.
• Schrittweite konfigurieren: Nutzen Sie _step, um die Inkrement-Größe bei Pfeiltasten-Navigation festzulegen. Beispiel: _step="5" für 5er-Schritte.
• Alternative zu direkter Eingabe: Bieten Sie bei großen Wertbereichen Pfeiltasten oder Spinner-Buttons als visuelle Alternativen zur Direkteingabe an.
• Name und ID: Achten Sie darauf, _name und eine eindeutige _id korrekt zu setzen, damit die Daten beim Formularabsenden mitgesendet werden.
• Placeholder beschreibend nutzen: Ein Placeholder kann ein Beispielformat zeigen (z.B. "z.B. 150"), sollte aber nie Pflichtinformationen enthalten.
• Validierungsfeedback: Nutzen Sie _msg und _hint für klare Vorgaben und Fehlermeldungen.

Anwendungsfälle

• Zahleneingaben in Formularen: Preise, Mengen, Altersangaben
• Bereichsangaben: Minimum/Maximum-Wertfestlegung
• Konfigurationsfelder: Numerische Parameter in Einstellungen
• Messgrößen: Längen, Gewichte, Temperaturen
• Identifikatoren: Nummern, Codes, Referenzen

FAQ

Kann ich Dezimalzahlen eingeben?
Ja, mit _step können Sie auch Dezimalzahlen unterstützen. Beispiel: _step="0.5" für 0,5er-Schritte.

Wie funktioniert die Schrittweite mit Min/Max?
Die Pfeiltasten addieren/subtrahieren den _step-Wert. Die Grenzen _min und _max verhindern, dass der Wert diese Grenzen überschreitet.

Muss ich _name setzen?
Ja, wenn das Feld Teil eines Formulars ist. Der _name wird beim Absenden als Feldname mitgesendet.

Kann ich Vorschlagswerte anzeigen?
Ja, über das Attribut _suggestions können Sie eine Liste von Vorschlagswerten bereitstellen, die dem Nutzer als Autocomplete-Optionen angeboten werden.

Konstruktion / Technik

Playground

Testen Sie die verschiedenen Eigenschaften des InputNumber-Feldes:

Icons

Message

<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:

Message

<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:

<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:

Icons

<KolInputNumber _icons={{"left":"kolicon-euro"}} _label="Preis" />

Verfügbare Positionen:

• left: Icon links vom Eingabefeld
• right: 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" | "_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
_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; } & { _on?: ButtonCallbacksPropType<StencilUnknown> | undefined; _type?: "button" | "reset" | "submit" | undefined; _ariaExpanded?: boolean | undefined; _tabIndex?: number | undefined; _value?: StencilUnknown; _accessKey?: string | undefined; _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

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.

---