Form

Wrap your fields to submit user data and enable input validation.

The <Form> component acts as a container for a set of fields, enabling data transmission to a server. It operates like a standard HTML form, initiating either a request based on the specified method attribute.

Additionally, the <Form> allows to validate user input and offers feedback for incorrect data entries, enhancing the overall resilience and user-friendliness of the form submission process. See the Validation guide to learn more about form validation.

Import

import { Form } from '@marigold/components';

Appearance

PropertyTypeDescription
variant-The available variants of this component.
size-The available sizes of this component.

Props

action?
string | ((formData: FormData) => void | Promise<void>);
Where to send the form-data when the form is submitted. See MDN.
aria-describedby?
string;
Identifies the element (or elements) that describes the object.
aria-details?
string;
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-label?
string;
Defines a string value that labels the current element.
aria-labelledby?
string;
Identifies the element (or elements) that labels the current element.
autoCapitalize?
"off" | "on" | "none" | "sentences" | "words" | "characters";
Controls whether inputted text is automatically capitalized and, if so, in what manner. See MDN.
autoComplete?
"off" | "on";
Indicates whether input elements can by default have their values automatically completed by the browser. See MDN.
children?
ReactNode;
The children of the component.
encType?
"application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain";
The enctype attribute specifies how the form-data should be encoded when submitting it to the server. See MDN.
id?
string;
The element's unique identifier. See MDN.
maxWidth?
0 | "auto" | "full" | "fit" | "min" | "max" | "screen" | "svh" | "lvh" | "dvh" | "px" | "0.5" | 1 | "1.5" | 2 | "2.5" | 3 | "3.5" | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 14 | 16 | 20 | 24 | 28 | ... 37 more ...
Sets the max-width of the element. You can see allowed tokens here.
Defaults to: 
"full"
method?
"get" | "post" | "dialog";
The HTTP method to submit the form with. See MDN.
onInvalid?
(event: FormEvent<HTMLFormElement>) => void;
Triggered for each invalid field when a user submits the form.
onReset?
(event: FormEvent<HTMLFormElement>) => void;
Triggered when a user resets the form.
onSubmit?
(event: FormEvent<HTMLFormElement>) => void;
Triggered when a user submits the form.
role?
"search" | "presentation";
An ARIA role override to apply to the form element.
target?
"_blank" | "_self" | "_parent" | "_top";
The target attribute specifies a name or a keyword that indicates where to display the response that is received after submitting the form. See MDN.
unstyled?
boolean;
Removes the form's visual container so that it does not impact the layout, letting child elements render naturally.
validationBehavior?
"aria" | "native";
Whether to use native HTML form validation to prevent form submission when a field value is missing or invalid, or mark fields as required or invalid via ARIA.
Defaults to: 
'native'
validationErrors?
ValidationErrors;
Validation errors for the form, typically returned by a server. This should be set to an object mapping from input names to errors.

Examples

Setup

This is a simple setup how to use a <Form>.

Handling submission

The onSubmit event is useful for custom form actions, such as calling a REST API, instead of relying on the native form submission. It triggeres when a user submits the form using the Enter key or clicks the submit button. The onReset event is triggered when a user presses a reset button ([type=reset]).

Server Errors

The <Form> component handles passed errors, typically received from a server after form submission. To display validation errors, set the validationErrors prop as an object mapping each field's name prop to a string or array of strings representing errors. These errors appear to the user as soon as the validationErrors prop is set and are cleared when the user modifies the corresponding field's value.

Incorrect password.

For more information about form validation, see the Validation guide.

Focus Management

As you can see in the previous server errors example, when a user submits a form with validation errors, the first invalid field is automatically focused. This behavior can be customized using e.preventDefault during the onInvalid event and manage the focus manually.

Want more?!

You can find more examples and usages of the <Form> component on the Validation page and in the Forms recipes.

Last update: October 25, 2024