Form

A native form element with consolidated error handling.

<script lang="ts">
	import { Button } from '@sveltery/base/button';
	import { Field } from '@sveltery/base/field';
	import { Form, type FormErrors } from '@sveltery/base/form';

	let errors = $state<FormErrors>({});
	let loading = $state(false);

	async function submitForm(value: string) {
		await new Promise((resolve) => {
			setTimeout(resolve, 1000);
		});

		try {
			const url = new URL(value);

			if (url.hostname.endsWith('example.com')) {
				return { error: 'The example domain is not allowed' };
			}
		} catch {
			return { error: 'This is not a valid URL' };
		}

		return { success: true };
	}
</script>

<Form
	class="flex w-full max-w-64 flex-col gap-4"
	bind:errors
	onsubmit={async (event) => {
		event.preventDefault();
		const formData = new FormData(event.currentTarget);
		const value = formData.get('url') as string;

		loading = true;
		const response = await submitForm(value);
		const serverErrors: FormErrors = response.error ? { url: response.error } : {};

		errors = serverErrors;
		loading = false;
	}}
>
	<Field.Root name="url" class="flex flex-col items-start gap-1">
		<Field.Label class="text-sm font-bold text-neutral-950 dark:text-white">Homepage</Field.Label>
		<Field.Control
			type="url"
			required
			defaultValue="https://example.com"
			placeholder="https://example.com"
			pattern="https?://.*"
			class="h-8 w-full border border-neutral-950 bg-white dark:bg-neutral-950 px-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 placeholder:text-neutral-500 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white dark:border-white dark:text-white dark:placeholder:text-neutral-400"
		/>
		<Field.Error class="text-sm text-red-700 dark:text-red-400" />
	</Field.Root>
	<Button
		disabled={loading}
		focusableWhenDisabled
		type="submit"
		class="flex h-8 items-center justify-center gap-2 rounded-none border border-neutral-950 bg-white px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 select-none hover:not-data-disabled:bg-neutral-100 active:not-data-disabled:bg-neutral-200 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:border-white dark:bg-neutral-950 dark:text-white dark:hover:not-data-disabled:bg-neutral-800 dark:active:not-data-disabled:bg-neutral-700 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400"
	>
		Submit
	</Button>
</Form>

Anatomy

Form is composed together with Field. Import the components and place them together:

<script lang="ts">
	import { Field } from '@sveltery/base/field';
	import { Form } from '@sveltery/base/form';
</script>

<Form>
	<Field.Root>
		<Field.Label />
		<Field.Control />
		<Field.Error />
	</Field.Root>
</Form>

Forms can be submitted with a SvelteKit form action instead of onsubmit. Return the action's errors from fail() and pass them to errors. The demo below mimics the action with onFormSubmit. Connect a form action shows the real +page.server.ts and use:enhance.

<script lang="ts">
	import { Button } from '@sveltery/base/button';
	import { Field } from '@sveltery/base/field';
	import { Form, type FormErrors } from '@sveltery/base/form';

	let errors = $state<FormErrors>({});
	let loading = $state(false);

	async function submitForm(formValues: Record<string, unknown>) {
		await new Promise((resolve) => {
			setTimeout(resolve, 1000);
		});

		try {
			const username = formValues.username as string | null;

			if (username === 'admin') {
				return { success: false, serverErrors: { username: "'admin' is reserved for system use" } };
			}

			const success = Math.random() > 0.5;

			if (!success) {
				return {
					serverErrors: { username: `${username} is unavailable` }
				};
			}
		} catch {
			return { serverErrors: { username: 'A server error has occurred' } };
		}

		return {};
	}
</script>

<Form
	class="flex w-full max-w-64 flex-col gap-4"
	bind:errors
	onFormSubmit={async (formValues) => {
		loading = true;
		const result = await submitForm(formValues);
		errors = result.serverErrors ?? {};
		loading = false;
	}}
>
	<Field.Root name="username" class="flex flex-col items-start gap-1">
		<Field.Label class="text-sm font-bold text-neutral-950 dark:text-white">Username</Field.Label>
		<Field.Control
			type="text"
			autocomplete="username"
			required
			defaultValue="admin"
			placeholder="e.g. alice132"
			class="h-8 w-full border border-neutral-950 bg-white dark:bg-neutral-950 px-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 placeholder:text-neutral-500 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white dark:border-white dark:text-white dark:placeholder:text-neutral-400"
		/>
		<Field.Error class="text-sm text-red-700 dark:text-red-400" />
	</Field.Root>
	<Button
		type="submit"
		disabled={loading}
		focusableWhenDisabled
		class="flex h-8 items-center justify-center gap-2 rounded-none border border-neutral-950 bg-white px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 select-none hover:not-data-disabled:bg-neutral-100 active:not-data-disabled:bg-neutral-200 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:border-white dark:bg-neutral-950 dark:text-white dark:hover:not-data-disabled:bg-neutral-800 dark:active:not-data-disabled:bg-neutral-700 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400"
	>
		Submit
	</Button>
</Form>

Submit form values as a JavaScript object

You can use onFormSubmit instead of the native onsubmit to access form values as a JavaScript object. This is useful when you need to transform the values before submission, or integrate with 3rd party APIs.

<Form
	onFormSubmit={async (formValues: { id: string; quantity: number }) => {
		const payload = {
			product_id: formValues.id,
			order_quantity: formValues.quantity
		};

		const response = await fetch('https://api.example.com', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify(payload)
		});
	}}
/>

When used, preventDefault is called on the native submit event.

Using with Zod

When parsing the schema using schema.safeParse(), the z.flattenError(result.error).fieldErrors data can be used to map the errors to each field's name. The demo below uses Valibot, where v.flatten(result.issues).nested gives the same shape.

<script lang="ts">
	import * as v from 'valibot';
	import { Button } from '@sveltery/base/button';
	import { Field } from '@sveltery/base/field';
	import { Form, type FormErrors } from '@sveltery/base/form';

	const schema = v.object({
		name: v.pipe(v.string(), v.minLength(1, 'Name is required')),
		age: v.pipe(
			v.string(),
			v.transform(Number),
			v.number('Age must be a number'),
			v.gtValue(0, 'Age must be a positive number')
		)
	});

	async function submitForm(formValues: Record<string, unknown>) {
		const result = v.safeParse(schema, formValues);

		if (!result.success) {
			return {
				errors: (v.flatten(result.issues).nested ?? {}) as FormErrors
			};
		}

		return {
			errors: {}
		};
	}

	let errors = $state<FormErrors>({});
</script>

<Form
	class="flex w-full max-w-64 flex-col gap-4"
	bind:errors
	onFormSubmit={async (formValues) => {
		const response = await submitForm(formValues);
		errors = response.errors;
	}}
>
	<Field.Root name="name" class="flex flex-col items-start gap-1">
		<Field.Label class="text-sm font-bold text-neutral-950 dark:text-white">Name</Field.Label>
		<Field.Control
			placeholder="Enter name"
			class="h-8 w-full border border-neutral-950 bg-white dark:bg-neutral-950 px-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 placeholder:text-neutral-500 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white dark:border-white dark:text-white dark:placeholder:text-neutral-400"
		/>
		<Field.Error class="text-sm text-red-700 dark:text-red-400" />
	</Field.Root>
	<Field.Root name="age" class="flex flex-col items-start gap-1">
		<Field.Label class="text-sm font-bold text-neutral-950 dark:text-white">Age</Field.Label>
		<Field.Control
			placeholder="Enter age"
			class="h-8 w-full border border-neutral-950 bg-white dark:bg-neutral-950 px-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 placeholder:text-neutral-500 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white dark:border-white dark:text-white dark:placeholder:text-neutral-400"
		/>
		<Field.Error class="text-sm text-red-700 dark:text-red-400" />
	</Field.Root>
	<Button
		type="submit"
		class="flex h-8 items-center justify-center gap-2 rounded-none border border-neutral-950 bg-white px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 select-none hover:not-data-disabled:bg-neutral-100 active:not-data-disabled:bg-neutral-200 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:border-white dark:bg-neutral-950 dark:text-white dark:hover:not-data-disabled:bg-neutral-800 dark:active:not-data-disabled:bg-neutral-700 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400"
	>
		Submit
	</Button>
</Form>

API reference

A native form element with consolidated error handling. Renders a <form> element.

form S —

Name: form
Description: The external owner of form state, such as a SvelteKit remote form. Its attributes and attachment go on the <form>. Fields bind to its fields.
Type: S

enhance function —

Name: enhance
Description: Runs once the source has validated a submit, with the source's enhance contract. Call submit() to send it. Without this prop, a successful submit resets the form.
Type: (instance: EnhanceInstanceOf<S>) => unknown

validationMode FormValidationMode 'onSubmit'

Name: validationMode
Description: When fields should validate. A <Field.Root validationMode> takes precedence.
Type: FormValidationMode
Default: 'onSubmit'

errors FormErrors —

Name: errors
Description: Errors supplied from outside the form, usually after a server action. Use bind:errors so clearErrors can drop a key. A new object from the parent replaces the current errors.
Type: FormErrors
Binding: bind:errors

onsubmit EventHandler<SubmitEvent, HTMLFormElement> | null —

Name: onsubmit
Description: Native submit listener. Runs after fields validate and only when no invalid field blocks the submit. Call event.preventDefault() to keep the browser from navigating. This does not skip onFormSubmit.
Type: EventHandler<SubmitEvent, HTMLFormElement> | null

onFormSubmit function —

Name: onFormSubmit
Description: Called with each named field's value when submit is not blocked. The native submit is cancelled before this runs. With form, the source submits instead, so use enhance.
Type: (formValues: FormValues, eventDetails: FormSubmitEventDetails) => void

onFocusInvalid function | Promise<void> —

Name: onFocusInvalid
Description: Called in place of focusing the first invalid control, after a blocked submit or once errors or source issues arrive. Use it to reveal a control that is hidden, such as one on an inactive step. Form waits for the returned promise and the next DOM update, then focuses the control, also when the callback throws or rejects, unless focus moved while it ran. Keep a hidden step mounted, because a field that is not rendered does not register. With novalidate={false}, the browser handles a native constraint before Form sees the submit, so this is not called for it.
Type: (detail: FormFocusInvalidDetail) => void | Promise<void>

novalidate boolean true

Name: novalidate
Description: When true (the default), the browser's built-in constraint validation is off. Registered fields still validate through the form. It is set once the form is hydrated, so a page that has not loaded JavaScript keeps the browser's validation.
Type: boolean
Default: true

render Snippet<[props: HTMLFormAttributes, state: FormState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <form>. Spread props onto the host and render children.
Type: Snippet<[props: HTMLFormAttributes, state: FormState, children: Snippet | undefined]>

Error

Messages no field shows: the source's root issues, issues on paths no mounted Field claims, and errors entries no registered Field has. Renders a <div> element. Sveltery addition with no Base UI counterpart. Before hydration only root issues render, because Fields later in the markup have not claimed their paths yet.

role AriaRole | null 'alert'

Name: role
Description: The host's role. Focus moves to no field when only form-level messages fail a submit, so the messages are announced.
Type: AriaRole | null
Default: 'alert'

children Snippet —

Name: children
Description: Replaces the messages.
Type: Snippet

render Snippet<[props: HTMLAttributes<HTMLElement>, state: FormErrorState, children: Snippet | undefined]> —

Name: render
Description: Replace the default <div>. Spread props onto the host element.
Type: Snippet<[props: HTMLAttributes<HTMLElement>, state: FormErrorState, children: Snippet | undefined]>

transitionStatus 'starting' | 'ending' | 'idle' | undefined

Name: transitionStatus
Description: The transition status of the error message.
Type: 'starting' | 'ending' | 'idle' | undefined

data-starting-style

Present when the error begins animating in.

data-ending-style

Present when the error is animating out.