InputText

Diese Dokumentation wird aktuell überarbeitet und befindet sich im Beta-Status. Inhalte können sich noch ändern.

Synonyme: Texteingabefeld, Textfeld, Eingabefeld, Text Input, Text Field

Beschreibung: Mit InputText können Texte und textbasierte Werte eingegeben und bearbeitet werden.

Die Komponente basiert auf dem nativen HTML5-Element <input> und unterstützt verschiedene Eingabetypen wie text, email, password, search, tel und url.

Beispiel

Standard-Eingabefeld mit Beschriftung:

<KolInputText _label="Texteingabe" />

Barrierefreiheit

• Das Eingabefeld muss mit einer aussagekräftigen Beschriftung (_label) versehen werden.
• Zusätzliche Hinweise können über _hint, Fehlermeldungen über _msg bereitgestellt werden.
• Je nach verwendetem Eingabetyp stellen Browser und assistive Technologien unterschiedliche Funktionen und Eingabehilfen bereit.
• Vorschlagswerte (_suggestions) werden über das native HTML-Element umgesetzt. Die Unterstützung durch Browser und assistive Technologien ist uneinheitlich. Verlassen Sie sich bei unverzichtbaren Eingabehilfen daher nicht ausschließlich auf diese native Autovervollständigung.

Konkrete Designentscheidungen

Entscheidung	Begründung
Verwendung des nativen HTML5-Elements <input>	Die Komponente nutzt bewusst das native HTML5-Element und profitiert dadurch von dessen standardisierter Unterstützung durch Browser und assistive Technologien.
Aktualisierung des Zeichenzählers	Bei aktiviertem Zeichenzähler (_has-counter) wird dieser mit einer Verzögerung von 1000 ms aktualisiert, um Screenreader nicht zu unterbrechen. Zusätzlich wird ein versteckter, nur für assistive Technologien sichtbarer Hinweis bereitgestellt.
Fokusmanagement	Die Basis-Komponente setzt den nativen Fokusring zurück. Der sichtbare Fokusindikator wird durch das jeweils verwendete Theme bereitgestellt.

Links und Referenzen

Verwendung

• Wählen Sie den zum Anwendungsfall passenden Eingabetyp (text, email, password, search, tel oder url).
• Nutzen Sie _max-length, um die maximal zulässige Anzahl an Zeichen zu begrenzen.
• Verwenden Sie _max-length-behavior, um festzulegen, ob die Zeichenbegrenzung nativ durchgesetzt oder lediglich angezeigt wird.

Tastatursteuerung

Die Tastaturbedienung wird durch den Browser und das Betriebssystem bestimmt. Daher können sich einzelne Tastaturfunktionen je nach Browser, Betriebssystem und verwendetem Eingabetyp 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.
Pfeiltasten	Cursor innerhalb des Eingabefelds bewegen.
Pos1 / Ende	Cursor an den Anfang/Ende des Eingabewerts setzen.

Hinweis: Beim Eingabetyp search kann die Esc-Taste das Eingabefeld je nach Browser leeren. Dieses Verhalten ist browserabhängig und kann daher nicht für alle Browser konsistent gewährleistet werden. Weitere Informationen finden Sie unter .

Best Practices / Empfehlungen

• Wählen Sie den Eingabetyp passend zum erwarteten Eingabewert, beispielsweise email für E-Mail-Adressen oder url für Internetadressen.
• Begrenzen Sie die Eingabelänge bei Bedarf über _max-length und wählen Sie mit _max-length-behavior das zum Anwendungsfall passende Verhalten.
• Nutzen Sie Vorschlagswerte (_suggestions) als unterstützende Eingabehilfe. Stellen Sie unverzichtbare Informationen jedoch immer zusätzlich auf anderem Wege bereit.
• Verwenden Sie _placeholder ausschließlich als zusätzliche Orientierung und nicht als Ersatz für eine aussagekräftige Beschriftung (_label).
• Verwenden Sie bei längeren Freitexten die anstelle von InputText. Setzen Sie _auto-complete bewusst ein. Verwenden Sie 'on' oder einen passenden Autocomplete-Token, wenn Browser-Autovervollständigung erwünscht ist.
• Aktivieren oder deaktivieren Sie _spell-check abhängig vom Anwendungsfall, beispielsweise für Freitextfelder oder technische Eingaben.

Anwendungsfälle

• Erfassung kurzer Texteingaben, beispielsweise Namen oder Adressen
• Suchfelder
• Eingabe von Kontaktdaten, beispielsweise E-Mail-Adressen oder Telefonnummern
• Eingabe von Internetadressen (URLs)
• Passworteingaben

FAQ

Wann sollte ich _hideLabel verwenden?
Verwenden Sie _hideLabel nur, wenn die Beschriftung visuell ausgeblendet werden soll. Das Label bleibt für assistive Technologien verfügbar und dient weiterhin als zugängliche Beschriftung des Eingabefelds.

Wie kann ich Eingaben validieren?
Nutzen Sie die nativen Validierungsmöglichkeiten des HTML-Elements, beispielsweise _required, _pattern, _min-length oder _max-length. Fehlermeldungen können über _msg ausgegeben werden.

Kann ich Vorschläge anzeigen?
Ja, über _suggestions können Vorschlagswerte bereitgestellt werden. Da die Unterstützung von datalist je nach Browser und assistiven Technologien unterschiedlich ausfällt, sollten Vorschläge nur als ergänzende Eingabehilfe verwendet werden.

Wie unterscheiden sich _max-length und _max-length-behavior?
Mit _max-length wird die maximale Anzahl an Zeichen festgelegt. Über _max-length-behavior kann gesteuert werden, ob die Eingabe nativ begrenzt oder lediglich die Zeichenanzahl angezeigt wird.

Konstruktion / Technik

Playground

Testen Sie die verschiedenen Eigenschaften des Eingabefelds

Icons

<KolInputText _label="Texteingabe" />

Funktionalitäten (mit Code)

Basis-Eingabefeld

Ein einfaches Eingabefeld mit Label:

<KolInputText _label="Texteingabe" />

Eingabefeld-Typen

InputText unterstützt verschiedene Eingabe-Typen über das Attribut _type:

<KolInputText _label="Eingabetyp" _type="text" />

Verfügbare Typen:

• text (Standard): Normales Textfeld
• search: Suchfeld mit ESC-Funktion zum Löschen
• tel: Für Telefonnummern
• url: Für URLs mit entsprechender Validierung

Icons

Links und rechts vom Eingabefeld können Icons platziert werden:

Icons

<KolInputText _icons={{ "left": "kolibri-icon-24", "right": "kolibri-icon-24" }} _label="Mit Icons" />

Validierungszustände

Status-Eigenschaften zur Steuerung von Validierung und Interaktion:

<KolInputText _label="Eingabefeld" />

Verfügbare Zustände:

• _disabled: Deaktiviert das Feld (mit Begründung nutzen)
• _readOnly: Feld ist lesbar, aber nicht editierbar
• _required: Kennzeichnet Pflichtfelder
• _touched: Zeigt an, ob das Feld vom Nutzer angefasst wurde

Label-Verwaltung

Label können visuell verborgen sein, bleiben aber für assistive Technologien sichtbar:

<KolInputText _hideLabel={true} _label="Verborgenes Label" _placeholder="Platzhalter" />

Vorschlagswerte (Suggestions)

Über _suggestions können Vorschlagswerte bereitgestellt werden, die während der Eingabe als auswählbare Datenliste angezeigt werden:

<KolInputText _label="Anrede" _suggestions={[ "Herr", "Frau", "Firma" ]} />

Verfügbares Attribut:

• _suggestions: Liste von Vorschlagswerten für die Datalist-Autovervollständigung

Zeichenbegrenzung und Zeichenzähler

Mit den Attributen _max-length, _max-length-behavior und _has-counter lässt sich die Eingabelänge flexibel begrenzen und gleichzeitig visuelles Feedback geben:

<KolInputText _hasCounter={true} _label="Mit Zeichenzähler" _maxLength={50} />

Attribute

Attribut	Typ	Standard	Beschreibung
_has-counter	boolean	false	Globaler Schalter für den Zeichenzähler. Nur wenn dieses Attribut gesetzt (= true) ist, wird überhaupt ein Zähler ausgegeben.
_max-length	number	—	Maximale Anzahl erlaubter Zeichen. Wirksam nur, wenn _has-counter aktiv ist.
_max-length-behavior	"hard" | "soft"	"hard"	Legt fest, wie die Grenze behandelt wird, falls _max-length gesetzt ist: - hard: Setzt zusätzlich das native maxlength-Attribut und verhindert weitere Eingaben. - soft: Lässt weitere Eingaben zu; der Zähler zeigt verbleibende oder überschrittene Zeichen an.

Ausgabevarianten

Fall	_has-counter	_max-length	_max-length-behavior	Sichtbarer Text
1	(leer) oder false	—	—	— (kein Zähler)
2	true	(leer)	—	n Zeichen
3	true	50	(leer) oder hard	n/50 Zeichen
4	true	50	soft	noch 30 Zeichen verfügbar (bzw. 5 Zeichen zu viel)

Wird _max-length-behavior="soft" verwendet, wird das native maxlength-Attribut nicht gesetzt – das Eingabefeld wird also nicht hart begrenzt.

Barrierefreiheit

• Der Zähler aktualisiert sich mit einer Verzögerung von 500 ms, damit Screenreader-Ereignisse gebündelt werden und das Tippen nicht unterbrechen.
• Für Screenreader wird zusätzlich ein versteckter, nur für assistive Technologien sichtbarer Text eingeblendet, etwa: „Sie können bis zu 10 Zeichen eingeben.“

Zusammenfassung

• Ohne _has-counter gibt es nie einen Zähler.
• Mit _has-counter und ohne _max-length wird nur die aktuell eingegebene Zeichenzahl angezeigt.
• Mit _has-counter und _max-length bestimmt _max-length-behavior, ob die Grenze hart (hard) oder weich (soft) umgesetzt wird.

SmartButton

Ein Schaltfläche mit beliebiger Aktion kann im Feld platziert werden (nur mit _hideLabel):

<KolInputText _hideLabel={true} _label="Mit SmartButton" _placeholder="Platzhalter" _smartButton={{ "_label": "Action" }} />

Hinweistexte und Fehlermeldungen

Zusätzliche Informationen und Fehler-Feedback:

Message

<KolInputText _hint="Das ist ein Hinweis" _label="Mit Hinweis" _msg="Das ist eine Fehlermeldung" />

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 Text input type creates an input field for plain text, search terms, URLs, or phone numbers.

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
_hasCounter	_has-counter	Shows a character counter for the input element.	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
_maxLength	_max-length	Defines the maximum number of input characters.	number | undefined	undefined
_maxLengthBehavior	_max-length-behavior	Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input.	"hard" | "soft" | undefined	'hard'
_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
_pattern	_pattern	Defines a validation pattern for the input field.	string | 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
_spellCheck	_spell-check	Defines whether the browser should check the spelling and grammar.	boolean | 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
_type	_type	Defines either the type of the component or of the components interactive element.	"search" | "tel" | "text" | "url" | undefined	'text'
_value	_value	Defines the value of the element.	string | 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<string | undefined>

Returns the current value.

Returns

Type: Promise<string | undefined>

selectionEnd() => Promise<number | null | undefined>

Get selection end of internal element.

Returns

Type: Promise<number | null | undefined>

selectionStart() => Promise<number | null | undefined>

Get selection start of internal element.

Returns

Type: Promise<number | null | undefined>

setRangeText(replacement: string, selectionStart?: number, selectionEnd?: number, selectMode?: "select" | "start" | "end" | "preserve") => Promise<void>

Add string at position of internal element; just like https://developer.mozilla.org/docs/Web/API/HTMLInputElement/setRangeText

Parameters

Name	Type	Description
replacement	string
selectionStart	number | undefined
selectionEnd	number | undefined
selectMode	"select" | "start" | "end" | "preserve" | undefined

Returns

Type: Promise<void>

setSelectionRange(selectionStart: number, selectionEnd: number, selectionDirection?: "forward" | "backward" | "none") => Promise<void>

Set selection start and end, and optional in which direction, of internal element; just like https://developer.mozilla.org/docs/Web/API/HTMLInputElement/setSelectionRange

Parameters

Name	Type	Description
selectionStart	number
selectionEnd	number
selectionDirection	"none" | "forward" | "backward" | undefined

Returns

Type: Promise<void>

setSelectionStart(selectionStart: number) => Promise<void>

Set selection start (and end = start) of internal element.

Parameters

Name	Type	Description
selectionStart	number

Returns

Type: Promise<void>

Slots

Slot	Description
	The label of the input field.

---