InputText

Synonyms: Text Field

The input type Text creates an input field for normal text, search terms, URLs or phone numbers.

The component has known issues regarding browser dependency and accessibility. Further information can be found at KNOWN_ISSUES.md.

Construction

Code

<kol-input-text
 _type="text"
 _label="Texteingabe"
 _icons='{"left": "codicon codicon-arrow-left", "right": {"icon": "codicon codicon-arrow-right", "style": {"font-size": "200%"}}}'
></kol-input-text>
<kol-input-text _type="text" _label="Deaktiviert" _disabled></kol-input-text>
<kol-input-text _type="text" _label="Schreibgeschützt" _read-only></kol-input-text>
<kol-input-text
 _type="text"
 _label="Mit Button"
 _smart-button='{"_icons": "codicon codicon-chrome-close", "_hideLabel": true, "_label": "Löschen"}'
></kol-input-text>

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

Example

Usage

Best practices

• Make sure to set id and name correctly so that the data is sent when you submit the form.

Accessibility

Keyboard controls

button	Function
Tab	Focuses the input field.
ESC	Deletes the content (Type = Search only).

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-text _label="Texteingabe" _has-counter></kol-input-text>

<!-- Harte Begrenzung auf 5 Zeichen -->
<kol-input-text _label="Texteingabe" _has-counter _max-length="5"></kol-input-text>

<!-- Weiche Begrenzung auf 5 Zeichen -->
<kol-input-text
 _label="Texteingabe"
 _has-counter
 _max-length="5"
 _max-length-behavior="soft">
</kol-input-text>

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

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
_id	_id	[DEPRECATED] Will be removed in the next major version. Defines the internal ID of the primary component element.	string | 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" | "_hasCloser" | "_label" | "_level" | "_variant"> & { _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; } & { _ariaExpanded?: boolean | undefined; _tabIndex?: number | undefined; _value?: StencilUnknown; _accessKey?: string | undefined; _role?: "tab" | "treeitem" | undefined; _ariaControls?: string | undefined; _ariaDescription?: string | undefined; _ariaSelected?: boolean | undefined; _on?: ButtonCallbacksPropType<StencilUnknown> | undefined; _type?: "button" | "reset" | "submit" | undefined; _variant?: "primary" | "secondary" | "normal" | "tertiary" | "danger" | "ghost" | "custom" | 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; }	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

Methods

getValue

getValue() => Promise<string | undefined>

Returns the current value.

Returns

Type: Promise<string | undefined>

kolFocus() => Promise<void>

Sets focus on the internal element.

Returns

Type: Promise<void>

selectioconEnd() => 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
	Die Beschriftung des Eingabefeldes.

---

Usage _msg

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

View example

Live editor

Examples