InputEmail

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

Synonyme: E-Mail-Eingabefeld, E-Mail-Feld, Email Input, Email Field

Beschreibung: Mit InputEmail können E-Mail-Adressen eingegeben und bearbeitet werden.

Die Komponente basiert auf dem nativen HTML5-Eingabetyp email und unterstützt die Eingabe einer oder mehrerer E-Mail-Adressen.

Beispiel

Darstellung der Komponente ohne optional gesetzte Felder.

<KolInputEmail _label="E-Mail-Adresse" />

Barrierefreiheit

• Das Eingabefeld muss mit einer aussagekräftigen Beschriftung (_label) versehen werden.
• Zusätzliche Hinweise können über _hint, Fehlermeldungen über _msg bereitgestellt werden.
• Ist _multiple gesetzt, wird die Eingabe mehrerer, durch Komma getrennter E-Mail-Adressen erwartet und entsprechend an assistive Technologien kommuniziert.
• Über _icons eingebundene Icons sind rein dekorativ und werden vor assistiven Technologien verborgen (aria-hidden).

Konkrete Designentscheidungen

Entscheidung	Begründung
Verwendung des nativen HTML5-Eingabetyps email	Die Komponente nutzt bewusst den nativen HTML5-Eingabetyp email 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 bei jeder Eingabe zu unterbrechen. Ist kein Zeichenzähler aktiv, aber _max-length gesetzt, wird stattdessen ein versteckter, nur für assistive Technologien sichtbarer Hinweis bereitgestellt.

Links und Referenzen

Verwendung

• Verwenden Sie _multiple, um die Eingabe mehrerer, durch Komma getrennter E-Mail-Adressen zu ermöglichen.
• 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.
• Nutzen Sie _pattern, wenn zusätzlich zur nativen E-Mail-Validierung weitere Formatvorgaben erforderlich sind.

Hinweis: Die native Formatprüfung des HTML5-Eingabetyps email erfolgt unabhängig von _msg und _touched. Sollen Validierungsfehler in der Komponente angezeigt werden, müssen diese durch die Anwendung ausgewertet und über _msg sowie _touched="true" bereitgestellt werden.

Tastatursteuerung

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

Best Practices / Empfehlungen

• Verlassen Sie sich nicht ausschließlich auf die native Formatprüfung des Browsers. Werten Sie Validierungsfehler in der Anwendung aus und stellen Sie über _msg zusammen mit _touched="true" eine aussagekräftige Fehlermeldung bereit.
• Formulieren Sie Fehlermeldungen konkret und lösungsorientiert, damit Nutzende erkennen können, wie die eingegebene E-Mail-Adresse korrigiert werden muss.
• Verwenden Sie _pattern nur für fachlich notwendige zusätzliche Anforderungen, beispielsweise wenn ausschließlich E-Mail-Adressen einer bestimmten Domain zulässig sind.
• Weisen Sie bei Verwendung von _multiple deutlich darauf hin, dass mehrere E-Mail-Adressen durch Kommas getrennt eingegeben werden müssen.
• Verwenden Sie _placeholder ausschließlich als zusätzliche Orientierung und nicht als Ersatz für eine aussagekräftige Beschriftung (_label).
• Setzen Sie _auto-complete passend zum Anwendungsfall ein, beispielsweise mit dem Wert email, wenn die Browser-Autovervollständigung unterstützt werden soll.

Anwendungsfälle

• Eingabe einer E-Mail-Adresse in Kontakt-, Registrierungs- oder Anmeldeformularen
• Erfassung einer geschäftlichen oder privaten E-Mail-Adresse in Benutzerprofilen
• Eingabe einer Empfängeradresse für Benachrichtigungen oder den Versand von Informationen
• Erfassung mehrerer E-Mail-Adressen, beispielsweise für Einladungen oder Verteiler
• Eingabe einer E-Mail-Adresse zur Anmeldung für Newsletter oder andere Mitteilungen

FAQ

Wie kann ich Validierungsfehler barrierefrei anzeigen?
Die native Formatprüfung des HTML5-Eingabetyps email ersetzt keine barrierefreie Fehlermeldung. Werten Sie das Ergebnis der Validierung in Ihrer Anwendung aus und stellen Sie Validierungsfehler über _msg zusammen mit _touched="true" bereit.

Wie werden mehrere E-Mail-Adressen bei _multiple verarbeitet?
Der native Wert des Eingabefelds enthält weiterhin den vollständigen, durch Kommas getrennten String. Eine automatische Aufteilung in einzelne E-Mail-Adressen erfolgt nicht durch die Komponente.

Werden internationalisierte (Unicode-)E-Mail-Adressen unterstützt?
Die Komponente nutzt die native Browservalidierung des HTML5-Eingabetyps email. Ob internationalisierte E-Mail-Adressen unterstützt werden, hängt daher vom jeweiligen Browser ab.

Kann ich die native E-Mail-Validierung erweitern?
Ja. Nutzen Sie _pattern, wenn zusätzlich zur nativen E-Mail-Validierung weitere fachliche Anforderungen geprüft werden sollen, beispielsweise um E-Mail-Adressen auf bestimmte Domains einzuschränken.

Konstruktion / Technik

Playground

Testen Sie die verschiedenen Eigenschaften des InputEmail-Felds:

<KolInputEmail _label="E-Mail-Adresse" />

Funktionalitäten (mit Code)

Basis-Eingabefeld

Standard-E-Mail-Eingabe mit Label:

<KolInputEmail _label="E-Mail-Adresse" />

Mehrfach-Eingabe

Mit _multiple werden mehrere E-Mail-Adressen akzeptiert, kommagetrennt:

<KolInputEmail _hint="Adressen durch Kommas trennen" _label="E-Mail-Adressen" _multiple={true} />

Placeholder und Hinweis

Hilfstexte für bessere Usability:

<KolInputEmail _hint="Wir verwenden Ihre E-Mail für Benachrichtigungen." _label="E-Mail-Adresse" _placeholder="beispiel@domain.de" />

Formularattribute

Standard-Attribute für Formulare:

Tooltip Align

<KolInputEmail _label="E-Mail-Adresse" />

Verfügbare Attribute:

• _disabled: Deaktiviert das Eingabefeld (mit Begründung verwenden!)
• _readOnly: Verhindert die Bearbeitung des Feldes
• _required: Kennzeichnet Pflichtfelder
• _hideLabel: Blendet das Label visuell aus (bleibt für assistive Technologien sichtbar)
• _hideMsg: Blendet die Fehlermeldung visuell aus, hält sie aber im DOM für aria-describedby
• _shortKey: Fügt einen visuellen Shortcut-Hinweis nach dem Label hinzu und liest ihn für Screenreader vor
• _tooltipAlign: Legt fest, wo der Tooltip bevorzugt angezeigt wird ('top' | 'right' | 'bottom' | 'left')

Icons

Icons können links und/oder rechts vom Eingabefeld angezeigt werden:

Icons

<KolInputEmail _icons={{ "left": "kolibri", "right": "fa-solid fa-envelope" }} _label="E-Mail-Adresse" />

Name und ID

Technische Kennzeichnung für Formulare:

<KolInputEmail _label="E-Mail-Adresse" _name="email" />

Hinweis: _name wird als HTML-Attribut name verwendet und ist wichtig für das Absenden des Formulars.

Auto-Vervollständigung und Vorschläge

Mit _autoComplete steuern Sie, ob der Browser Eingabevorschläge anzeigen soll. Der Standardwert ist 'off'. Für Felder, bei denen Browser-Autofill erwünscht ist, setzen Sie _autoComplete="email".

Mit _suggestions können Sie eine Liste von Vorschlagswerten bereitstellen, die dem Nutzer während der Eingabe als auswählbare Datenliste angezeigt werden:

<KolInputEmail _autoComplete="email" _label="E-Mail-Adresse" />

Zeichenbegrenzung und Zeichenzähler

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

<KolInputEmail _hasCounter={true} _label="E-Mail-Adresse" _maxLength={100} />

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	100	(leer) oder hard	n/100 Zeichen
4	true	100	soft	noch 50 Zeichen verfügbar (bzw. 5 Zeichen zu viel)

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

Barrierefreiheit des Zeichenzählers

• 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 100 Zeichen eingeben."

Fehlermeldung und Validierung

Fehlerhafte Eingaben können über _msg mit aussagekräftigen Meldungen versehen werden. Mit _pattern lässt sich zusätzlich ein reguläres Ausdrucks-Muster zur Eingabevalidierung hinterlegen:

Message

<KolInputEmail _label="E-Mail-Adresse" _msg={{ "_description": "Bitte geben Sie eine gültige E-Mail-Adresse ein." }} _touched={true} />

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 Email input type creates an input field for email addresses. It supports built-in format validation, multiple addresses via the _multiple property, and auto-complete suggestions.

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
_multiple	_multiple	Makes the input accept multiple inputs.	boolean | undefined	false
_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
_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.	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>

Slots

Slot	Description
	The label of the input field.

---

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.

Verwendung _msg

Fall	_msg-Wert
Keine Message	undefined
"Standard"-Fehlermeldung	string
Meldung	{_type: 'success', _description: 'Erfolgs-Meldung'}

Beispiele