InputEmail

This documentation is currently being revised and is in beta status. Content may still change.

This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

The input type Email creates an input field for emails.

Construction

<KolInputEmail _label="Email Address" />

Events

For the handling of events or callbacks, see .

Event	trigger	Value
click	Input field is clicked	-
focus	Input field is focused	-
blur	Input field loses focus	-
input	Value is changed by entering	Current value of the input field
change	Entry has been completed	Current value of the input field

Usage

Use the InputEmail component on forms that require the entry of one or more email addresses.

By default, the component is designed to capture a single email address. Set the _multiple attribute to capture multiple email addresses. Separate each email address with a comma (,).

Best practices

• Make sure to set id and name correctly so that the data is sent when you submit the form.
• Use _hint to explain to users when multiple addresses are expected (with _multiple).
• Use _placeholder as a supplementary hint only, not for critical information.

Form attributes

Tooltip Align

<KolInputEmail _label="Email address" />

Available attributes:

• _disabled: Disables the input field (use with justification!)
• _readOnly: Prevents editing of the field
• _required: Marks mandatory fields
• _hideLabel: Hides the label visually (remains visible to assistive technologies)
• _hideMsg: Hides the error message visually but keeps it in the DOM for aria-describedby
• _shortKey: Adds a visual shortcut hint after the label and instructs screen readers to read it aloud
• _tooltipAlign: Defines where the tooltip is preferably shown ('top' | 'right' | 'bottom' | 'left')

Auto-complete and suggestions

Use _autoComplete to control whether the browser may display completion suggestions. The default is 'off'. For fields where browser autofill is desired, set _autoComplete="email".

Use _suggestions to provide a list of suggested values that are displayed to the user as a selectable datalist during input:

<KolInputEmail _autoComplete="email" _label="Email address" />

Accessibility

There is no validation of the recorded email addresses within the component. To indicate failed validation, use the _msg and _touched attributes. Additionally, _pattern can be used to specify a regular expression pattern for input validation.

Use _msg with _touched to show validation errors:

Message

<KolInputEmail _label="Email address" _msg={{"_description":"Please enter a valid email address."}} _touched={true} />

Keyboard controls

button	Function
Tab	Focuses the input field.

Character limit and character counter

With the three attributes _max-length, _max-length-behavior and _has-counter, the input length can be flexibly limited and at the same time provide visual feedback.

Attributes

Attribute	Type	Default	Description
_has-counter	boolean	false	Global switch for the character counter. Only if this attribute is set (= true) will a counter be output.
_max-length	number	—	Maximum number of characters allowed. Effective only if _has-counter is active.
_max-length-behavior	"hard" | "soft"	"hard"	Specifies how the limit is handled if _max-length is set: - hard: Additionally sets the native maxlength attribute and prevents further input. - soft: Allows further input; the counter shows remaining or exceeded characters.

Output variants

case	_has-counter	_max-length	_max-length-behavior	Visible text
1	(empty) or false	—	—	— (no counter)
2	true	(empty)	—	n character
3	true	5	(empty) or hard	n/5 characters
4	true	5	soft	3 characters still available (or 3 characters too many)

If _max-length-behavior="soft" is used, the native maxlength attribute is not set - so the input field is not hard-limited.

Accessibility

• The counter updates with a 500ms delay so that screen reader events are concentrated and do not interrupt typing.
• For screen readers, a hidden text that is only visible to assistive technologies is also displayed, such as: “You can enter up to 10 characters.”

Examples

<!-- Nur Zähler -->
<kol-input-email _label="E-Mail-Adresse" _has-counter></kol-input-email>

<!-- Harte Begrenzung auf 5 Zeichen -->
<kol-input-email _label="E-Mail-Adresse" _has-counter _max-length="5"></kol-input-email>

<!-- Weiche Begrenzung auf 5 Zeichen -->
<kol-input-email
 _label="E-Mail-Adresse"
 _has-counter
 _max-length="5"
 _max-length-behavior="soft">
</kol-input-email>

Summary

• Without _has-counter there is never a counter.
• With _has-counter and without _max-length only the currently entered number of characters is displayed.
• With _has-counter and _max-length, _max-length-behavior determines whether the limit is implemented hard (hard) or softly (soft).

Links and references

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" | "_variant" | "_hasCloser" | "_label" | "_level"> & { _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; } & { _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
_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

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.

---

Usage _msg

Case	_msg-Value
No message	undefined
Default error message	string
Message	{_type: 'success', _description: 'Success message'}

Examples