Forms

Form

Groups fields for submission, validation, and a shared necessity indicator.

React Aria SourceView as Markdown Edit on GitHub

Form groups fields for submission. Beyond a native HTML form, it shares a necessity indicator, validation behaviour, and server errors with nested Luke UI fields.

Use a layout component such as Stack to arrange its contents. Prefer action for ordinary submissions and onSubmit when you need the submit event or a form library. Read Submit for the differences.

Form: Basic

Open in playground

import { Button } from '@luke-ui/react/button';
import { Cluster } from '@luke-ui/react/cluster';
import { Form } from '@luke-ui/react/form';
import { Stack } from '@luke-ui/react/stack';
import { Text } from '@luke-ui/react/text';
import { TextInputField } from '@luke-ui/react/text-input-field';
import type { SubmitEvent } from 'react';
import { useState } from 'react';

export default () => {
	const [submitted, setSubmitted] = useState('');

	function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
		event.preventDefault();
		const data = new FormData(event.currentTarget);
		const familyName = data.get('familyName');
		setSubmitted(typeof familyName === 'string' ? familyName : '');
	}

	return (
		<Stack gap="space.16" style={{ maxInlineSize: '20rem' }}>
			<Form necessityIndicator="optional-label" onSubmit={handleSubmit}>
				<Stack gap="space.16">
					<Text elementType="p">All fields are required unless marked optional.</Text>
					<TextInputField isRequired label="Family name" name="familyName" />
					<TextInputField label="Middle name" name="middleName" />
					<Cluster>
						<Button type="submit">Save</Button>
					</Cluster>
				</Stack>
			</Form>
			<Text elementType="p" isVisuallyHidden={!submitted} role="status">
				{submitted ? `Submitted: ${submitted}` : null}
			</Text>
		</Stack>
	);
};

Form: Basic

Loading Form: Basic example

Necessity indicators

Set necessityIndicator on Form to choose how nested fields identify required or optional values. A field's own necessityIndicator overrides the Form setting. When neither sets one, required labels display an asterisk.

The indicator changes the label. It does not make a field required. Set isRequired on each required field.

Form does not generate a legend that explains required or optional markers. Read Required fields for when to add one and how the three indicators differ.

Validation

By default, native validation prevents submission when a field is invalid. Set validationBehavior="aria" when a form library handles validation. An individual field can override the Form setting.

Pass server errors through validationErrors, keyed by each field's name.

Read Validation for validation rules, error precedence, and when messages appear or clear.

Control sizes

Pass controlSize="small" for compact fields and actions. A component's explicit size takes precedence. Without an inherited default, controls use medium. Sizes select the whole control recipe, including its typography and icons.

Form: Control sizes

Open in playground

import { Button } from '@luke-ui/react/button';
import { CheckboxField } from '@luke-ui/react/checkbox-field';
import { Form } from '@luke-ui/react/form';
import { Stack } from '@luke-ui/react/stack';
import { TextInputField } from '@luke-ui/react/text-input-field';

export default () => (
	<Form controlSize="small">
		<Stack gap="space.16">
			<TextInputField label="Name" />
			<CheckboxField label="Subscribe" />
			<Button size="medium">Save</Button>
		</Stack>
	</Form>
);

Form: Control sizes

Loading Form: Control sizes example

Accessibility

Provide an accessible name for the form landmark when the page has more than one form, or when the form's purpose is not clear from surrounding content. Pass aria-label or aria-labelledby.

API

FormProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type	Default
action	((formData: FormData) => Promise<void> \|⁠ void) \|⁠ string \|⁠ undefined	—
React form Action or URL for ordinary submissions. Prefer this over `onSubmit` when you do not need the submit event.
autoCapitalize	'off' \|⁠ 'none' \|⁠ 'on' \|⁠ 'sentences' \|⁠ 'words' \|⁠ 'characters'	—
Controls whether inputted text is automatically capitalized and, if so, in what manner. See MDN.
controlSize		`'medium'`
Default recipe size for fields and actions. An explicit component size takes precedence.
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.
method	'get' \|⁠ 'post' \|⁠ 'dialog'	—
The HTTP method to submit the form with. See MDN.
necessityIndicator		—
Controls how nested fields identify required or optional values. A field's own setting takes precedence.
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.
validationErrors	ValidationErrors \|⁠ undefined	—
Server validation errors keyed by field name.