Textarea

Synonyme: Mehrzeiliges Eingabefeld, Textbereich, Texteingabefeld

Beschreibung: Mit Textarea können längere Texte mit Zeilenumbrüchen eingegeben und bearbeitet werden, etwa Beschreibungen, Kommentare oder Begründungen.

Die Komponente basiert auf dem nativen HTML-Element <textarea> und profitiert dadurch von dessen Semantik sowie der standardisierten Unterstützung durch Browser und assistive Technologien.

Über das native Element hinaus bietet die Komponente eine automatische Höhenanpassung an den Inhalt, eine auf die vertikale Richtung beschränkte Größenanpassung sowie einen barrierefreien Zeichenzähler.

Beispiel

Standard-Textarea ohne optional gesetzte Felder:

<KolTextarea _label="Beschreibung" />

Barrierefreiheit

• Das Eingabefeld muss mit einer aussagekräftigen Beschriftung versehen werden. Es darf visuell ausgeblendet werden, wenn der Zweck des Eingabefeldes durch den direkten visuellen Kontext absolut unmissverständlich ist.

• Im Fehlerfall wird die Fehlermeldung direkt an der Komponente dargestellt und automatisch mit ihr verknüpft, sodass sie auch assistiven Technologien zur Verfügung steht.

• Der Zeichenzähler (_hasCounter) wird Screenreader-Nutzenden nicht bei jedem Tastendruck, sondern gesammelt nach einer Eingabepause von etwa einer Sekunde angesagt, damit das Tippen nicht durch laufende Ansagen unterbrochen wird. Ist die Zeichengrenze bei _maxLengthBehavior="hard" erreicht, wird dies zusätzlich angesagt – auch bei jedem weiteren Eingabeversuch –, und beim erneuten Fokussieren des Feldes wird der aktuelle Zählerstand noch einmal ausgegeben. Ist nur _maxLength ohne Zähler gesetzt, erhalten Screenreader-Nutzende die maximale Zeichenanzahl als zusätzlichen Hinweis zum Feld.

• Die Textarea bietet klare Fokusindikatoren.

Konkrete Designentscheidungen

Entscheidung	Begründung
Verwendung des nativen HTML-Elements <textarea>	Die Komponente nutzt bewusst das native Element und profitiert dadurch von dessen standardisierter Unterstützung durch Browser und assistive Technologien, einschließlich der Tastaturbedienung.
Optionale automatische Höhenanpassung (_adjustHeight)	Mit _adjustHeight wächst das Feld mit dem Inhalt, sodass der gesamte Text ohne inneren Scrollbalken sichtbar ist.

Links und Referenzen

Verwendung

• Verwenden Sie die Textarea für mehrzeilige Inhalte. Für kurze, einzeilige Eingaben nutzen Sie die .
• Legen Sie mit _rows eine Starthöhe fest, die zur erwarteten Textmenge passt.
• Begrenzen Sie die Eingabelänge mit _maxLength, wenn dies fachlich erforderlich ist, und machen Sie die Grenze mit _hasCounter transparent.

Hinweis: Bei _maxLengthBehavior="soft" wird das native maxlength-Attribut nicht gesetzt, sodass auch längere Texte eingegeben werden können. Die Validierung der Zeichengrenze muss dann auf Anwendungsebene erfolgen.

Tastatursteuerung

Die Tastaturbedienung wird durch den Browser und das Betriebssystem bestimmt. Daher können sich einzelne Tastaturfunktionen je nach Browser und Endgerät unterscheiden.

Typischerweise werden folgende Funktionen unterstützt:

Taste	Funktion
Tab	Fokus auf die Textarea bzw. das nächste fokussierbare Element setzen.
Shift+Tab	Fokus auf das vorherige fokussierbare Element setzen.
Pfeil-Tasten	Cursor innerhalb des Textes bewegen.
Pos1 / Ende	Zum Anfang bzw. Ende der aktuellen Zeile springen.
Strg+Pos1 / Strg+Ende	Zum Anfang bzw. Ende des gesamten Textes springen.
Strg+A	Gesamten Text in der Textarea markieren.
Enter	Zeilenumbruch einfügen (im Gegensatz zu einzeiligen Eingabefeldern).

Hinweis: Tab fügt kein Tabulatorzeichen ein, sondern verlässt das Feld. Tastaturnutzende bleiben dadurch nicht in der Textarea gefangen.

Best Practices / Empfehlungen

• Höhe sinnvoll wählen: Beginnen Sie mit wenigen Zeilen (z. B. _rows mit dem Wert 4) und erlauben Sie bei Bedarf die Größenanpassung über _resize oder die automatische Höhenanpassung über _adjustHeight, aber vermeiden Sie horizontales Scrollen.
• Sinnvolle maximale Länge: Legen Sie eine fachlich begründete maximale Zeichenlänge fest und machen Sie diese mit _hasCounter und _maxLength transparent. Für weiche Grenzen nutzen Sie _maxLengthBehavior="soft".
• Hilfetexte bereitstellen: Geben Sie Formatvorgaben oder Hinweise über _hint vor der Eingabe an, nicht erst nach einem Fehler.
• Kontrolle bei den Nutzenden lassen: Erzwingen Sie keine Groß- oder Kleinschreibung. Nutzende behalten die Kontrolle über den eingegebenen Text.
• Transparenz bei Kürzungen: Schneiden Sie Inhalte nie ohne Hinweis ab und verändern Sie sie nicht unbemerkt. Kommunizieren Sie Kürzungen klar.
• Aussagekräftige Beschriftungen: Verwenden Sie klare und präzise Beschriftungen (_label), die den Zweck des Feldes deutlich machen.
• Konkrete Fehlermeldungen: Geben Sie bei Validierungsfehlern konkrete, verständliche Hinweise über _msg.

Anwendungsfälle

• Erfassen von Kommentaren, Feedback oder Bewertungen
• Eingabe von Produkt-, Artikel- oder Personenbeschreibungen
• Erfassung von Anliegen, Anfragen oder Begründungen in Formularen
• Eingabe von Adressen mit mehreren Zeilen, Notizen oder Anweisungen
• Verfassen von E-Mails, Nachrichten oder Mitteilungen
• Eingabe längerer Texte in Dokumentations- oder Content-Management-Systemen

FAQ

Wird die Zeichengrenze bei _maxLengthBehavior="soft" erzwungen?
Nein. Bei soft können weiterhin Zeichen eingegeben werden; der Zähler zeigt dann an, um wie viele Zeichen die Grenze überschritten ist. Die Validierung muss auf Anwendungsebene erfolgen.

Kann die Textarea horizontal vergrößert werden?
Nein. Horizontales Vergrößern wird seit Version 3 nicht mehr angeboten. _resize unterstützt nur vertical und none.

Kann ich einen Zeichenzähler ohne Zeichengrenze anzeigen?
Ja. Mit _hasCounter ohne _maxLength wird die Anzahl der eingegebenen Zeichen angezeigt.

Playground

Testen Sie die verschiedenen Eigenschaften der Textarea-Komponente:

Icons

Message

<KolTextarea _hint="Hinweistext" _label="Beschreibung" _placeholder="Bitte geben Sie eine Beschreibung ein …" _rows={4} />

Funktionalitäten

Einfaches Eingabefeld

Jedes Feld benötigt mindestens ein Label (_label), um für alle Nutzenden verständlich und zugänglich zu sein. Das Label wird als natives label-Element mit dem Feld verknüpft.

<KolTextarea _label="Beschreibung" />

Formularattribute

Mit den folgenden Properties passen Sie das Feld an gängige Formularanforderungen an:

• _disabled: Deaktiviert das Feld. Deaktivierte Felder sind nicht fokussierbar und können nicht bearbeitet werden (mit Bedacht verwenden!).

• _readOnly: Verhindert die Bearbeitung des Feldes. Das Feld bleibt fokussierbar und lesbar. Hinter der Beschriftung erscheint zusätzlich der Hinweis „(schreibgeschützt)“; er ist vor assistiven Technologien verborgen, da der Zustand bereits über das native readonly-Attribut vermittelt wird.

• _required: Kennzeichnet das Feld als Pflichtfeld.

Die Properties werden 1:1 auf die gleichnamigen nativen HTML-Attribute des textarea-Elements übertragen.

<KolTextarea _label="Beschreibung" _value="Dies ist ein Beispieltext." />

Hinweistexte und Fehlermeldungen

Mit _hint und _msg geben Sie Nutzenden zusätzliche Orientierung zur Eingabe und machen Validierungsfehler unmittelbar am Feld sichtbar:

• _hint: Ergänzende Hinweise zur Eingabe (wird immer angezeigt und über aria-describedby mit dem Feld verknüpft)
• _msg: Fehlermeldungen oder Validierungshinweise (wird nur in Verbindung mit _touched angezeigt)
• _touched: Zeigt an, ob das Feld von Nutzenden bereits angefasst wurde, und steuert damit, ob _msg sichtbar wird
• _hideMsg: Unterdrückt die Fehlermeldung am Feld, wenn sie an anderer Stelle dargestellt wird

Hinweis: _msg wird erst dann eingeblendet, wenn _touched auf true gesetzt ist. So werden Validierungsfehler nicht bereits beim ersten Rendern, sondern erst nach einer Interaktion mit dem Feld angezeigt. Handelt es sich um eine Fehlermeldung, wird das Feld zusätzlich über aria-invalid als ungültig gekennzeichnet.

Anwendungsfall für _hideMsg: Besteht eine fachliche Einheit aus mehreren Eingabefeldern innerhalb eines Field-Sets, beispielsweise ein sechsstelliger Bestätigungscode mit einem einzelnen Feld je Stelle, kann eine gemeinsame Fehlermeldung für die gesamte Gruppe sinnvoller sein als eine Meldung je Einzelfeld. In diesem Fall unterdrücken Sie die Fehlermeldung an den einzelnen Feldern über _hideMsg und stellen sie stattdessen einmalig am Field-Set dar.

Wichtig: _hideMsg blendet die Fehlermeldung nicht nur visuell aus. Die Meldung wird weder gerendert noch über aria-describedby mit dem Feld verknüpft – lediglich die Kennzeichnung über aria-invalid bleibt erhalten. Stellen Sie daher sicher, dass die gemeinsame Fehlermeldung auf Anwendungsebene für alle Nutzenden, auch für Nutzende assistiver Technologien, wahrnehmbar ist.

Message

<KolTextarea _hideMsg={false} _hint="Beschreiben Sie kurz, warum Sie den Antrag stellen." _label="Begründung" _msg={{ "_description": "Bitte geben Sie eine Begründung an." }} _touched={true} />

Zeilenanzahl

Mit _rows legen Sie die sichtbare Höhe der Textarea in Zeilen fest. Der Wert wird auf das native rows-Attribut übertragen. Ist weder _rows noch _adjustHeight gesetzt, startet die Textarea mit einer Zeile.

<KolTextarea _label="Beschreibung" _rows={6} />

Automatische Höhenanpassung

Mit _adjustHeight passt die Textarea ihre Zeilenanzahl bei jeder Eingabe an den Inhalt an, sodass der gesamte Text ohne inneren Scrollbalken sichtbar ist. Beim ersten Rendern wird mindestens die über _rows festgelegte Höhe verwendet.

<KolTextarea _adjustHeight={true} _label="Beschreibung" _value="Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat." />

Größenanpassung (Resize)

Mit _resize legen Sie fest, ob Nutzende die Höhe der Textarea selbst verändern können. Die horizontale Größenanpassung wird nicht angeboten.

Verfügbare Werte sind:

• vertical: Die Höhe kann vergrößert und verkleinert werden (Standard).
• none: Keine Größenanpassung durch Nutzende möglich.

<KolTextarea _label="Beschreibung" _resize="vertical" />

Zeichenbegrenzung und Zeichenzähler

Mit _maxLength, _maxLengthBehavior und _hasCounter begrenzen Sie die Eingabelänge und geben Nutzenden gleichzeitig Rückmeldung über die bereits eingegebenen bzw. noch verfügbaren Zeichen.

Properties

Property	Typ	Standard	Beschreibung
_hasCounter	boolean	false	Blendet den Zeichenzähler ein. Ohne dieses Property wird kein Zähler ausgegeben.
_maxLength	number	–	Maximale Anzahl erlaubter Zeichen.
_maxLengthBehavior	'hard' | 'soft'	'hard'	Legt fest, wie die Grenze aus _maxLength behandelt wird: - hard: Setzt das native maxlength-Attribut und verhindert weitere Eingaben – auch ohne Zähler. - soft: Lässt weitere Eingaben zu; der Zähler zeigt verbleibende bzw. überschrittene Zeichen an.

Ausgabevarianten des Zählers

Fall	_hasCounter	_maxLength	_maxLengthBehavior	Sichtbarer Text
1	(leer) oder false	–	–	– (kein Zähler)
2	true	(leer)	(leer) oder hard	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)

Hinweis: Bei _maxLengthBehavior="soft" wird das native maxlength-Attribut nicht gesetzt. Die Einhaltung der Zeichengrenze muss dann auf Anwendungsebene validiert werden. Ohne _maxLength wird bei soft kein Zähler angezeigt.

<KolTextarea _hasCounter={true} _label="Beschreibung" _maxLength={100} _rows={3} _value="Initialer Text" />

Placeholder

Mit _placeholder zeigen Sie einen Platzhaltertext an, solange noch kein Wert eingegeben bzw. ausgewählt ist – etwa ein Format- oder Eingabebeispiel. Der Platzhalter ist kein Ersatz für die Beschriftung (_label), da er nach der Eingabe verschwindet und von assistiven Technologien nicht zuverlässig ausgegeben wird.

<KolTextarea _label="Beschreibung" _placeholder="z. B. Lieferung an die Hintertür" />

Label ausblenden

Mit _hideLabel blenden Sie das Label visuell aus, um das Feld kompakter zu gestalten. Für assistive Technologien bleibt die Beschriftung als zugänglicher Name (aria-label) weiterhin verfügbar; sehende Nutzende erhalten sie bei Maus-Hover und Tastaturfokus als Tooltip.

<KolTextarea _hideLabel={false} _label="Beschreibung" />

Icons

Mit _icons versehen Sie das Feld links und/oder rechts mit zusätzlichen Icons, um visuellen Kontext zu geben.

Verfügbare Positionen sind:

• left: Icon links vom Feld
• right: Icon rechts vom Feld

Wird ein Icon nur über seine Icon-Klasse angegeben, gilt es als dekorativ und wird vor assistiven Technologien verborgen. Trägt ein Icon eine Information, die nicht bereits aus Label oder Hinweis hervorgeht, übergeben Sie es als Objekt mit label – das Icon erhält dann eine zugängliche Beschriftung.

Icons

<KolTextarea _icons={{ "left": "kolicon-kolibri" }} _label="Beschreibung" />

API

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
click	Textarea wird angeklickt	-
focus	Textarea wird fokussiert	-
blur	Textarea verliert Fokus	-
keydown	Taste wird in der Textarea gedrückt	-
input	Wert wird durch Eingabe geändert	Aktueller Wert der Textarea
change	Eingabe wurde abgeschlossen	Aktueller Wert der Textarea

Overview

The Textarea component provides a larger input field for content. Unlike InputText, it also allows extensive content to be entered, including line breaks.

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
_adjustHeight	_adjust-height	Adjusts the height of the element to its content.	boolean | undefined	false
_ariaDetails	_aria-details	References an external element by ID that provides accessible details for this textarea.	string | undefined	undefined
_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.	string | undefined | { right?: IconOrIconClass | undefined; left?: IconOrIconClass | undefined; }	undefined
_infoPopover	_info-popover	Defines the informational popover after the label.	any	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
_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
_resize	_resize	Defines whether and in which direction the size of the input can be changed by the user. (https://developer.mozilla.org/de/docs/Web/CSS/resize) In version 3 (v3), horizontal resizing is abolished. The corresponding property is then reduced to the properties vertical (default) and none.	"none" | "vertical" | undefined	'vertical'
_rows	_rows	Maximum number of visible rows of the element.	number | undefined	undefined
_shortKey	_short-key	Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud.	string | undefined	undefined
_spellCheck	_spell-check	Defines whether the browser should check the spelling and grammar.	boolean | 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 | string[] | undefined	undefined

Methods

click

click() => Promise<void>

Clicks the primary interactive element inside this component.

Returns

Type: Promise<void>

focus(options?: KolFocusOptions) => Promise<void>

Sets focus on the internal element.

Parameters

Name	Type	Description
options	KolFocusOptions | undefined

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.

---