Form

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

Diese Komponente wird erneut auf Barrierefreiheit getestet. Der vollständige Test steht noch aus und kann erst nach einem abgeschlossenen Release erfolgen.

Synonyme: Formularelement-Wrapper, Eingabefeld-Container, Formular-Grundgerüst

Beschreibung: Die Form-Komponente ist ein zweckgebundener Container, der sämtliche Eingabefelder semantisch korrekt umschließt. Sie stellt sicher, dass Pflichtfeld-Hinweistexte korrekt positioniert werden, leitet Browser-Events (submit und reset) weiter und ermöglicht strukturierte Fehlerbehandlung mit Fokus-Management für Barrierefreiheit.

Beispiel

Standard-Formular mit Eingabefeldern und Buttons:

<KolForm _requiredText={true} />

Barrierefreiheit

Die Form-Komponente unterstützt barrierefreie Formularstrukturen nach modernen Standards:

• Semantische Struktur: Die Verwendung des nativen <form>-Elements gewährleistet, dass von Screenreadern das Formular als solches erkannt wird.
• Pflichtfeld-Hinweis: Mit _requiredText wird ein global sichtbarer und von assistiven Technologien interpretierbarer Hinweis auf Pflichtfelder angezeigt.
• Fehlerbehandlung: Die _errorList-Eigenschaft ermöglicht strukturierte Fehlerausgaben, die mit der Methode focusErrorList() angesteuert werden – ideal für Barrierefreiheit.
• Event-Weitergabe: Die Komponente leitet native submit- und reset-Events korrekt weiter, was notwendig für Frameworks und Validierungsbibliotheken ist.
• Fokus-Management: Über die Methode focusErrorList() können Nutzer:innen mit Tastatur und Screenreader direkt zu Fehlern navigiert werden.

Links und Referenzen

Verwendung

Best Practices / Empfehlungen

• Alle Eingabefelder einschließen: Umschließen Sie jeden zusammenhängenden Satz von Eingabefeldern mit einer Form-Komponente.
• Pflichtfelder kennzeichnen: Nutzen Sie _requiredText um transparent zu machen, welche Felder erforderlich sind.
• Fehler strukturiert behandeln: Setzen Sie die _errorList mit Objekten, die Message und Selector enthalten, und nutzen Sie focusErrorList() um Nutzer:innen zu fehlerhaften Feldern zu navigieren.
• Submit und Reset Events: Der Einfachheit halber: nutzen Sie die Standard-Button-Type submit und reset und handeln Sie die Form-Events über die _on-Callbacks ab.
• Nicht verschachteln: Forms sollten nicht verschachtelt werden. Falls mehrere Formularbereiche notwendig sind, nutzen Sie <fieldset> und <legend> zur Strukturierung innerhalb einer Form.
• Mit responsivem Layout: Die Form selbst hat keine Größe – sie passt sich ihrem Container an. Nutzen Sie CSS-Grid oder Flexbox für die innere Anordnung.

Anwendungsfälle

• Kontaktformulare: Sammlung von Name, E-Mail und Nachricht mit Validierung
• Registrierung und Anmeldung: Sichere Erfassung von Zugangsdaten
• Datensätze: Bearbeitung von mehreren Feldern zu einem Datensatz mit Speichern/Abbrechen
• Suchmasken: Strukturierte Eingabe von Suchparametern
• Einstellungen und Konfiguration: Erfassung und Speicherung von Präferenzen

Konstruktion / Technik

Playground

Testen Sie die Form mit verschiedenen Konfigurationen:

<KolForm _requiredText="Sternchen heißt Pflichtfeld." />

Funktionalitäten (mit Code)

Pflichtfeld-Hinweis

Der Text für Pflichtfeld-Hinweise wird über _requiredText gesteuert:

<KolForm _requiredText={true} />

Mit _requiredText="false" wird der Hinweis ausgeblendet. Mit einem benutzerdefinierten String kann der Standard-Text überschrieben werden:

<KolForm _requiredText="Felder mit * sind erforderlich" />

Event-Anbindung

Zur Behandlung von Events bzw. Callbacks siehe .

Die Form-Komponente leitet folgende Events weiter:

Event	Auslöser	Value
submit	Submit-Button wird geklickt	Das native submit-Event
reset	Reset-Button wird geklickt	Das native reset-Event

Die Callbacks werden über die _on-Eigenschaft registriert und ermöglichen es, beispielsweise Formulardaten vor dem Versand zu verarbeiten oder den Formular-Zustand zurückzusetzen.

API

Overview

The Form component is used to wrap all input fields, correctly position the required-fields hint text, and forward the submit and reset events.

Properties

Property	Attribute	Description	Type	Default
_errorList	--	A list of error objects that each describe an issue encountered in the form. Each error object contains a message and a selector for identifying the form element related to the error.	ErrorListPropType[] | undefined	undefined
_on	--	Gibt die EventCallback-Funktionen für die Form-Events an.	undefined | { onSubmit?: EventCallback<Event> | undefined; onReset?: EventCallback<Event> | undefined; }	undefined
_requiredText	_required-text	Defines whether the mandatory-fields-hint should be shown. A string overrides the default text.	boolean | string | undefined	true

Methods

focusErrorList

focusErrorList() => Promise<void>

Scrolls to the error list and focuses the first link.

Returns

Type: Promise<void>

Slots

Slot	Description
	The content of the form.

---