Form

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.

Synonyms: Form element wrapper, Input field container, Form framework

Description: The Form component is a dedicated container that semantically wraps all input fields. It ensures that mandatory field hint texts are correctly positioned, forwards browser events (submit and reset), and enables structured error handling with focus management for accessibility.

Example

Standard form with input fields and buttons:

<KolForm _requiredText={true} />

Accessibility

The Form component supports accessible form structures according to modern standards:

• Semantic structure: The use of the native <form> element ensures that screen readers recognise the form as such.
• Mandatory field hint: With _requiredText, a globally visible hint about mandatory fields is displayed that can be interpreted by assistive technologies.
• Error handling: The _errorList property enables structured error output, which can be navigated to using the focusErrorList() method – ideal for accessibility.
• Event forwarding: The component correctly forwards native submit and reset events, which is necessary for frameworks and validation libraries.
• Focus management: The focusErrorList() method allows keyboard and screen reader users to navigate directly to errors.

Links and References

Usage

Best Practices / Recommendations

• Include all input fields: Wrap every related set of input fields with a Form component.
• Mark mandatory fields: Use _requiredText to make clear which fields are required.
• Handle errors structurally: Set _errorList with objects containing a message and a selector, and use focusErrorList() to navigate users to erroneous fields.
• Submit and Reset Events: For simplicity, use the standard button types submit and reset and handle form events via the _on callbacks.
• Do not nest: Forms should not be nested. If multiple form areas are necessary, use <fieldset> and <legend> for structuring within a single Form.
• With responsive layout: The Form itself has no size – it adapts to its container. Use CSS Grid or Flexbox for the inner layout.

Use Cases

• Contact forms: Collecting name, email, and message with validation
• Registration and login: Secure collection of access data
• Data records: Editing multiple fields for a record with save/cancel actions
• Search forms: Structured input of search parameters
• Settings and configuration: Capturing and saving preferences

Construction / Technic

Playground

Test the Form with various configurations:

<KolForm _requiredText="Asterisk means required field." />

Functionalities (with Code)

Mandatory Field Hint

The text for mandatory field hints is controlled via _requiredText:

<KolForm _requiredText={true} />

With _requiredText="false" the hint is hidden. With a custom string the default text can be overridden:

<KolForm _requiredText="Fields marked with * are required" />

Event Handling

For the handling of events or callbacks, see .

The Form component forwards the following events:

Event	Trigger	Value
submit	Submit button is clicked	The native submit event
reset	Reset button is clicked	The native reset event

Callbacks are registered via the _on property and allow, for example, processing form data before submission or resetting the form state.

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.

---