Formsnap

https://github.com/svecosystem/formsnap
Admin
Formsnap is a library that wraps SvelteKit Superforms with accessible, customizable, and...
Tokens:31,917
Snippets:259
Trust Score:7.4
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Start the development server

Source: https://github.com/svecosystem/formsnap/blob/main/docs/README.md

Run npm run dev to start the development server. Use the -- --open flag to open the app in a new browser tab.

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

--------------------------------

### Install Formsnap and dependencies

Source: https://github.com/svecosystem/formsnap/blob/main/README.md

Install the required packages: formsnap, sveltekit-superforms, and your schema library (e.g., zod).

```bash
npm i formsnap sveltekit-superforms <your-schema-library>
```

--------------------------------

### Setup the form in the page component

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/quick-start.md

Initialize the super form using superForm and pass the form from PageData. Enable client-side validation with validators and set up the form with enhance.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { Field } from "formsnap";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { allergies, schema, themes } from "./schema.js";
	import SuperDebug from "sveltekit-superforms";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});
	const { form: formData, enhance } = form;
</script>

<form method="POST" use:enhance>
	<!-- ... -->
</form>
<SuperDebug data={$formData} />
```

--------------------------------

### Setup load function and actions in +page.server.ts

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/checkbox-groups.md

Creates a server load function and default action using superValidate with the Zod schema. Returns a 400 fail response when validation fails.

```ts
import { superValidate } from "sveltekit-superforms";
import type { Actions, PageServerLoad } from "./$types";
import { schema } from "./+page.svelte";
import { zod } from "sveltekit-superforms/adapters";
import { fail } from "@sveltejs/kit";

export const load: PageServerLoad = async () => {
	return {
		form: await superValidate(zod(schema)),
	};
};

export const actions: Actions = {
	default: async (event) => {
		const form = await superValidate(event, zod(schema));

		if (!form.valid) {
			return fail(400, { form });
		}

		return { form };
	},
};
```

--------------------------------

### asChild to child snippet migration (v1 vs v2)

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/v2-migration-guide.md

In v1, the `asChild` prop was used to opt out of rendering the default HTML element. In v2, it is replaced by the `child` snippet, which exposes a `props` snippet prop to spread onto your own element. The v1 example uses `let:labelAttrs` to receive attributes, while the v2 example uses `{#snippet child({ props })}`.

```svelte
<!-- This could apply to any component that rendered an HTML element -->
<Label asChild let:labelAttrs>
	<label {...labelAttrs}>Name</label>
</Label>
```

```svelte
<!-- This applies to any component that renders an HTML element -->
<Label>
	{#snippet child({ props })}
		<label {...props}>Name</label>
	{/snippet}
</Label>
```

--------------------------------

### Setup the superForm and Bits UI Select in +page.svelte

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/bits-ui-select.md

Sets up a superForm with client-side validation using zodClient. The form includes a Field for 'language' with a Bits UI Select.Root bound to the form data. The Select.Trigger receives the control props for accessibility, and Select.Root uses props.name to render a hidden input. The selected language label is derived from the form data.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { Select } from "bits-ui";
	import { Field, Control, Label, FieldErrors, Description } from "formsnap";
	import { schema, languages } from "./schema.js";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});

	const { form: formData, enhance } = form;

	const selectedLanguageLabel = $derived(
		$formData.language ? languages[$formData.language] : "Select a language"
	);
</script>

<form method="POST" use:enhance>
	<Field {form} name="language">
		<Control>
			{#snippet children({ props })}
				<Label>Language</Label>
				<Select.Root type="single" bind:value={$formData.language} name={props.name}>
					<Select.Trigger {...props}>
						{selectedLabel}
					</Select.Trigger>
					<Select.Content>
						{#each Object.entries(languages) as [value, label]}
							<Select.Item {value}>
								{label}
							</Select.Item>
						{/each}
					</Select.Content>
				</Select.Root>
			{/snippet}
		</Control>
		<Description>The docs will be translated to your preferred language.</Description>
		<FieldErrors />
	</Field>
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Basic email field with formsnap

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/quick-start.md

Initial setup of a settings form with a single email field. Uses superForm from sveltekit-superforms with zodClient validation. The Control component syncs label and input via the props snippet prop. Description and FieldErrors are synced with aria-describedby for accessibility.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { Field, Control, Label, Description, FieldErrors } from "formsnap";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { allergies, schema, themes } from "./schema.js";
	import SuperDebug from "sveltekit-superforms";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});
	const { form: formData, enhance } = form;
</script>

<form method="POST" use:enhance>
	<Field {form} name="email">
		<Control>
			{#snippet children({ props })}
				<Label>Email</Label>
				<input {...props} type="email" bind:value={$formData.email} />
			{/snippet}
		</Control>
		<Description>Use your company email if you have one.</Description>
		<FieldErrors />
	</Field>
</form>
<SuperDebug data={$formData} />
```

--------------------------------

### Element reference migration: `el` to `ref` (v1 vs v2)

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/v2-migration-guide.md

In v1, you bound to the `el` prop to get a reference to the underlying HTML element. In v2, this is replaced by the `ref` prop, which is `$bindable` and should be used with `$state` in Svelte 5. The v2 example shows the new syntax with `let labelRef = $state<HTMLLabelElement | null>(null)`.

```svelte
<script lang="ts">
	import { Label } from "formsnap";
	let labelEl: HTMLLabelElement;
</script>

<Label bind:el={labelEl}>Name</Label>
```

```svelte
<script lang="ts">
	import { Label } from "formsnap";
	let labelRef = $state<HTMLLabelElement | null>(null);
</script>

<Label bind:ref={labelRef}>Name</Label>
```

--------------------------------

### Custom component using useFormControl (LabelInput.svelte)

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/composition/use-form-control.md

Shows how to use useFormControl inside a custom component to get spreadable attributes for label and control elements. The component receives a label prop and passes the control's labelProps and props to custom components.

```svelte
<script lang="ts">
	import { useFormControl } from "formsnap";
	import CustomLabel from "$lib/components/CustomLabel.svelte";
	import CustomInput from "$lib/components/CustomInput.svelte";

	let { label }: { label: string } = $props();

	const control = useFormControl();
</script>

<CustomLabel {...control.labelProps}>
	{label}
</CustomLabel>
<CustomInput {...control.props} />
```

--------------------------------

### Style with data attributes in app.pcss

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/styling.md

Use data attributes like data-fs-error and data-fs-control as CSS selectors to style form parts. This example shows a CSS file (app.pcss) with rules for error and control elements.

```css
[data-fs-error] {
	color: red;
}

[data-fs-control] {
	border: 1px solid #ccc;
}

/* ... */
```

--------------------------------

### Usage of Description component within a Field

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/components/description.md

Place the Description component inside a Field, Fieldset, or ElementField. It automatically links to the Control using aria-describedby. The example shows a basic usage with a label and input.

```svelte
<Field name="name" {form}>
	<Control>
		{#snippet children({ props })}
			<Label>Name</Label>
			<input type="text" {...attrs} />
		{/snippet}
	</Control>
	<Description>Your full name, including your middle name.</Description>
</Field>
```

--------------------------------

### Slot props to snippet props migration (v1 vs v2)

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/v2-migration-guide.md

In v1, `*Field*` components provided slot props like `value`, `errors`, `tainted`, and `constraints`. In v2, these are provided as snippet props to the `children` snippet. The v2 example shows both the snippet usage and the simpler form when you don't need access to those values.

```svelte
<Field {form} name="name" let:value let:errors let:tainted let:constraints>
	<!-- ... you can access those slot props here -->
</Field>
```

```svelte
<Field {form} name="name">
	{#snippet children({ value, errors, tainted, constraints })}
		<!-- ... you can access those snippet props here -->
	{/snippet}
</Field>

<!-- or if you don't need access to those values -->

<Field {form} name="name">
	<!-- ... your form components here -->
</Field>
```

--------------------------------

### Build the production version

Source: https://github.com/svecosystem/formsnap/blob/main/docs/README.md

Run npm run build to create a production version of the app. Preview the build with npm run preview.

```bash
npm run build
```

--------------------------------

### Initialize SuperForm and set up the form structure

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/multiple-select.md

Sets up the SuperForm with the form data from the load function and the Zod client validator. Imports the schema, flavors, and toppings from the schema file, and creates the basic form structure with a submit button.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { schema, flavors, toppings } from "./schema.js";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});

	const { form: formData } = form;
</script>

<form use:form.enhance method="POST">
	<!-- ... -->
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Create a new Svelte project with sv

Source: https://github.com/svecosystem/formsnap/blob/main/docs/README.md

Use npx sv create to scaffold a new Svelte project. Run in the current directory or specify a project name like my-app.

```bash
# create a new project in the current directory
npx sv create

# create a new project in my-app
npx sv create my-app
```

--------------------------------

### Pass class prop to Label component in Svelte

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/styling.md

Use the class prop on Formsnap components like Label to apply CSS framework classes. This Svelte example shows a Label with Tailwind-like classes.

```svelte
<script lang="ts">
	import { Label } from "formsnap";
</script>

<form>
	<!-- ... -->
	<Label class="text-black hover:text-orange-500">First Name</Label>
	<!-- ... -->
</form>
```

--------------------------------

### Initialize SuperForm and basic form structure

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/dynamic-fields.md

Sets up the SuperForm with the form data from the load function and the Zod client validator. Provides the basic form structure with a submit button.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { schema } from "./schema.js";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});

	const { form: formData } = form;
</script>

<form use:form.enhance method="POST">
	<!-- ... -->
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Set up the multi-select form with Bits UI

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/bits-ui-select.md

Sets up a superForm with client-side validation and renders a Bits UI Select with multiple selection. The control props are applied to the trigger for accessibility, and the name prop is applied to the root to render a hidden input.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { Select } from "bits-ui";
	import { Field, Control, Label, FieldErrors, Description } from "formsnap";
	import { schema, colors } from "./schema.js";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});

	const { form: formData } = form;

	const selectedColors = $derived(
		$formData.colors.length ? $formData.colors.map((c) => colors[c]).join(",") : "Select colors"
	);
</script>

<form method="POST" use:form.enhance>
	<Field {form} name="colors">
		<Control>
			{#snippet children({ props })}
				<Label>Favorite colors</Label>
				<Select.Root type="multiple" bind:value={$formData.colors} name={props.name}>
					<Select.Trigger {...props}>
						{selectedColors}
					</Select.Trigger>
					<Select.Content>
						{#each Object.entries(colors) as [value, label]}
							<Select.Item {value} {label} />
						{/each}
					</Select.Content>
				</Select.Root>
			{/snippet}
		</Control>
		<Description>We'll use these colors to customize your experience.</Description>
		<FieldErrors />
	</Field>
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Grouped Form Sections with Native fieldset

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/components/fieldset.md

Use native <fieldset> elements to group related fields in large forms, such as Billing and Shipping Address sections. This example does not use the Fieldset component because the groups do not represent a single form field.

```svelte
<form>
	<fieldset>
		<legend>Billing Address</legend>
		<!-- ... billing address fields -->
	</fieldset>
	<fieldset>
		<legend>Shipping Address</legend>
		<!-- ... shipping address fields -->
	</fieldset>
</form>
```

--------------------------------

### Complete settings form with all fields

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/quick-start.md

Full settings form with email, bio, language select, theme radio group, marketing emails checkbox, and allergies checkbox group. Uses Fieldset and Legend for grouping. Demonstrates binding to form data with bind:value, bind:group, and bind:checked.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { Field, Control, Label, Description, FieldErrors, Fieldset, Legend } from "formsnap";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { allergies, schema, themes } from "./schema.js";
	import SuperDebug from "sveltekit-superforms";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});
	const { form: formData, enhance } = form;
</script>

<form use:enhance class="mx-auto flex max-w-md flex-col" method="POST">
	<Field {form} name="email">
		<Control>
			{#snippet children({ props })}
				<Label>Email</Label>
				<input {...props} type="email" bind:value={$formData.email} />
			{/snippet}
		</Control>
		<Description>Company email is preferred</Description>
		<FieldErrors />
	</Field>
	<Field {form} name="bio">
		<Control>
			{#snippet children({ props })}
				<Label>Bio</Label>
				<textarea {...props} bind:value={$formData.bio} />
			{/snippet}
		</Control>
		<Description>Tell us a bit about yourself.</Description>
		<FieldErrors />
	</Field>
	<Field {form} name="language">
		<Control>
			{#snippet children({ props })}
				<Label>Language</Label>
				<select {...props} bind:value={$formData.language}>
					<option value="fr">French</option>
					<option value="es">Spanish</option>
					<option value="en">English</option>
				</select>
			{/snippet}
		</Control>
		<Description>Help us address you properly.</Description>
		<FieldErrors />
	</Field>
	<Fieldset {form} name="theme">
		<Legend>Select your theme</Legend>
		{#each themes as theme}
			<Control>
				{#snippet children({ props })}
					<Label>{theme}</Label>
					<input {...props} type="radio" value={theme} bind:group={$formData.theme} />
				{/snippet}
			</Control>
		{/each}
		<Description>We prefer dark mode, but the choice is yours.</Description>
		<FieldErrors />
	</Fieldset>
	<Field {form} name="marketingEmails">
		<Control>
			{#snippet children({ props })}
				<input {...props} type="checkbox" bind:checked={$formData.marketingEmails} />
				<Label>I want to receive marketing emails</Label>
			{/snippet}
		</Control>
		<Description>Stay up to date with our latest news and offers.</Description>
		<FieldErrors />
	</Field>
	<Fieldset {form} name="allergies">
		<Legend>Food allergies</Legend>
		{#each allergies as allergy}
			<Control>
				{#snippet children({ props })}
					<input
						{...props}
						type="checkbox"
						bind:group={$formData.allergies}
						value={allergy}
					/>
					<Label>{allergy}</Label>
				{/snippet}
			</Control>
		{/each}
		<Description>When we provide lunch, we'll accommodate your needs.</Description>
		<FieldErrors />
	</Fieldset>
	<button>Submit</button>
</form>
<SuperDebug data={$formData} />
```

--------------------------------

### Superforms + Formsnap: Simplified Accessible Sign-up Form in +page.svelte

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/index.md

The same sign-up form using Formsnap components (Field, Control, Label, FieldErrors, Description) to reduce boilerplate. It retains the same functionality while making the form accessible by default, as shown in the comparison.

```svelte
<script lang="ts">
	import { Field, Control, Label, FieldErrors, Description } from "formsnap";
	import { signupFormSchema } from "./schema.ts";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { superForm } from "sveltekit-superforms";
	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(signupFormSchema),
	});
	const { form: formData, enhance } = form;
</script>

<form method="POST" use:enhance>
	<Field {form} name="name">
		<Control>
			{#snippet children({ props })}
				<Label>Name</Label>
				<input {...props} bind:value={$formData.name} />
			{/snippet}
		</Control>
		<Description>Be sure to use your real name.</Description>
		<FieldErrors />
	</Field>
	<Field {form} name="email">
		<Control>
			{#snippet children({ props })}
				<Label>Email</Label>
				<input {...props} type="email" bind:value={$formData.email} />
			{/snippet}
		</Control>
		<Description>It's preferred that you use your company email.</Description>
		<FieldErrors />
	</Field>
	<Field {form} name="password">
		<Control>
			{#snippet children({ props })}
				<Label>Password</Label>
				<input {...props} type="password" bind:value={$formData.password} />
			{/snippet}
		</Control>
		<Description>Ensure the password is at least 10 characters.</Description>
		<FieldErrors />
	</Field>
</form>
```

--------------------------------

### Import Formsnap components and enhance the form

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/checkbox-groups.md

Imports Fieldset, Legend, Label, Control, FieldErrors, and Description from Formsnap. Sets up a form element with the enhance action for progressive enhancement.

```svelte
<!-- script context="module" tag  -->
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { Fieldset, Legend, Label, Control, FieldErrors, Description } from "formsnap";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});
	const { form: formData } = form;
</script>

<form method="POST" use:form.enhance>
	<!-- ... -->
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Multiple Select Form with Scoops and Flavors Fields

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/multiple-select.md

Creates a form with a single select for scoops and a multiple select for flavors. The flavors select uses the `multiple` attribute and the `selected` attribute to pre-select options from the `formData.flavors` array.

```svelte
<!-- script tag -->
<form use:form.enhance method="POST">
	<Field {form} name="scoops">
		<Control>
			{#snippet children({ props })}
				<div class="flex flex-col items-start gap-1">
					<Label>Number of scoops</Label>
					<select {...props} bind:value={$formData.scoops}>
						{#each Array.from({ length: 5 }, (_, i) => i + 1) as num}
							<option value={num}>
								{num === 1 ? `${num} Scoop` : `${num} Scoops`}
							</option>
						{/each}
					</select>
				</div>
			{/snippet}
		</Control>
		<FieldErrors />
	</Field>
	<Field {form} name="flavors">
		<Control>
			{#snippet children({ props })}
				<div class="flex flex-col items-start gap-1">
					<Label>What flavors do you fancy?</Label>
					<select multiple bind:value={$formData.flavors} {...props}>
						{#each flavors as flavor}
							<option value={flavor} selected={$formData.flavors.includes(flavor)}>
								{flavor}
							</option>
						{/each}
					</select>
				</div>
			{/snippet}
		</Control>
		<FieldErrors />
	</Field>
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Construct the form in the page (+page.svelte)

Source: https://github.com/svecosystem/formsnap/blob/main/packages/formsnap/README.md

Use Formsnap components (Field, Control, Label, etc.) with superForm to build an accessible form.

```svelte
<script lang="ts">
	import { Field, Label, FieldErrors, Control, Description, Fieldset, Legend } from "formsnap";
	import { settingsFormSchema } from "./schemas";
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";

	export let data;

	const form = superForm(data.form, {
		validators: zodClient(settingsFormSchema),
	});

	const { form: formData, enhance } = form;
</script>

<form method="POST" use:enhance>
	<Field {form} name="email">
		<Control let:attrs>
			<Label>Email</Label>
			<input type="email" {...attrs} bind:value={$formData.email} />
		</Control>
		<Description>We'll provide critical updates about your account via email.</Description>
		<FieldErrors />
	</Field>

	<Field {form} name="bio">
		<Control let:attrs>
			<Label>Bio</Label>
			<textarea bind:value={$formData.bio} {...attrs} />
		</Control>
		<FieldErrors />
	</Field>

	<Field {form} name="language">
		<Control let:attrs>
			<Label>Language</Label>
			<select {...attrs} bind:value={$formData.language}>
				<option value="en">English</option>
				<option value="es">Spanish</option>
				<option value="fr">French</option>
			</select>
		</Control>
		<FieldErrors />
	</Field>

	<Field {form} name="marketingEmails">
		<Control let:attrs>
			<Label>Receive marketing emails from us</Label>
			<input type="checkbox" {...attrs} bind:checked={$formData.marketingEmails} />
		</Control>
		<FieldErrors />
	</Field>

	<Fieldset {form} name="theme">
		<Legend>Select your theme</Legend>
		{#each ["light", "dark"] as theme}
			<Control let:attrs>
				<input {...attrs} type="radio" bind:group={$formData.theme} value={theme} />
				<Label>{theme}</Label>
			</Control>
		{/each}
		<FieldErrors />
	</Fieldset>

	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Import Formsnap components for dynamic fields

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/dynamic-fields.md

Adds imports for Fieldset, Legend, ElementField, Control, Label, FieldErrors, and Description from 'formsnap' to build the dynamic field structure.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import {
		Fieldset,
		Legend,
		ElementField,
		Control,
		Label,
		FieldErrors,
		Description,
	} from "formsnap";
	import { schema } from "./schema.js";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});

	const { form: formData } = form;
</script>

<form use:form.enhance method="POST">
	<!-- ... -->
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Return the form from the load function

Source: https://github.com/svecosystem/formsnap/blob/main/README.md

In the server load function, use superValidate with the Zod adapter to create the form data and return it to the page.

```ts
// +page.server.ts
import { superValidate } from "sveltekit-superforms";
import { zod } from "sveltekit-superforms/adapters";
import type { PageServerLoad } from "./$types";
import { settingsFormSchema } from "./schemas";

export const load: PageServerLoad = async () => {
	return {
		form: await superValidate(zod(settingsFormSchema)),
	};
};
```

--------------------------------

### Custom wrapper component around Control

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/components/control.md

Shows how to create a reusable wrapper component that includes a Label and wraps the control in a div, forwarding props and children.

```svelte
<script lang="ts">
	import { Control, Label } from "formsnap";
	import type { ComponentProps } from "svelte";

	let {
		label,
		// Rename the children prop to childrenProp to avoid
		// conflicts with the Control component
		children: childrenProp,
		...restProps
	}: ComponentProps<typeof Control> & {
		label: string;
	} = $props();
</script>

<Control {...restProps}>
	{#snippet children({ props })}
		<div class="flex flex-col gap-2">
			<Label>{label}</Label>
			<!-- Forward the props to the children snippet -->
			{@render childrenProp({ props })}
		</div>
	{/snippet}
</Control>
```

--------------------------------

### Initialize SuperForm in +page.svelte

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/checkbox-groups.md

Initializes the SuperForm with the data from the load function and the zodClient adapter for client-side validation. Exposes the form data via formData.

```svelte
<!-- script context="module" tag -->
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import SuperDebug from "sveltekit-superforms";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});
	const { form: formData } = form;
</script>
```

--------------------------------

### Import Formsnap components for the form

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/multiple-select.md

Adds the necessary Formsnap components (Field, Control, Label, FieldErrors) to the script tag. This is the minimal set of components required to build the form fields.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { Field, Control, Label, FieldErrors } from "formsnap";
	import { schema } from "./schema.js";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});

	const { form: formData } = form;
</script>

<form use:form.enhance method="POST">
	<!-- ... -->
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Basic Control usage with input

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/components/control.md

Wraps an input element with the Control component, using the children snippet to receive props and bind the input value to form data.

```svelte
<Control>
	{#snippet children({ props })}
		<input type="text" {...props} bind:value={$formData.name} />
	{/snippet}
</Control>
```

--------------------------------

### Construct the form in the page

Source: https://github.com/svecosystem/formsnap/blob/main/README.md

Use Formsnap components (Field, Control, Label, etc.) with superForm to build an accessible form. The form is enhanced with use:enhance for progressive enhancement.

```svelte
<script lang="ts">
	import { Field, Label, FieldErrors, Control, Description, Fieldset, Legend } from "formsnap";
	import { settingsFormSchema } from "./schemas";
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(settingsFormSchema),
	});

	const { form: formData, enhance } = form;
</script>

<form method="POST" use:enhance>
	<Field {form} name="email">
		<Control>
			{#snippet children({ props })}
				<Label>Email</Label>
				<input type="email" {...props} bind:value={$formData.email} />
			{/snippet}
		</Control>
		<Description>We'll provide critical updates about your account via email.</Description>
		<FieldErrors />
	</Field>

	<Field {form} name="bio">
		<Control>
			{#snippet children({ props })}
				<Label>Bio</Label>
				<textarea bind:value={$formData.bio} {...props} />
			{/snippet}
		</Control>
		<FieldErrors />
	</Field>

	<Field {form} name="language">
		<Control>
			{#snippet children({ props })}
				<Label>Language</Label>
				<select {...props} bind:value={$formData.language}>
					<option value="en">English</option>
					<option value="es">Spanish</option>
					<option value="fr">French</option>
				</select>
			{/snippet}
		</Control>
		<FieldErrors />
	</Field>

	<Field {form} name="marketingEmails">
		<Control>
			{#snippet children({ props })}
				<Label>Receive marketing emails from us</Label>
				<input type="checkbox" {...props} bind:checked={$formData.marketingEmails} />
			{/snippet}
		</Control>
		<FieldErrors />
	</Field>

	<Fieldset {form} name="theme">
		<Legend>Select your theme</Legend>
		{#each ["light", "dark"] as theme}
			<Control>
				{#snippet children({ props })}
					<input {...props} type="radio" bind:group={$formData.theme} value={theme} />
					<Label>{theme}</Label>
				{/snippet}
			</Control>
		{/each}
		<FieldErrors />
	</Fieldset>

	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Superforms Only: Accessible Sign-up Form in +page.svelte

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/index.md

A SvelteKit page using sveltekit-superforms with zodClient to create an accessible sign-up form. It manually wires up ARIA attributes, error display, and constraints for each field, resulting in verbose, repetitive code.

```svelte
<script lang="ts">
	import type { PageData } from "./$types";
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { signupFormSchema } from "./schema";
	let { data } = $props();

	const { form, errors, enhance, constraints } = superForm(data.form, {
		validators: zodClient(signupFormSchema),
	});
</script>

<form method="POST" use:enhance>
	<label for="name">Name</label>
	<input
		id="name"
		name="name"
		aria-describedby={$errors.name ? "name-error name-desc" : "name-desc"}
		aria-invalid={$errors.name ? "true" : undefined}
		aria-required={$constraints.name?.required ? "true" : undefined}
		bind:value={$form.name}
	/>
	<span id="name-desc">Be sure to use your real name.</span>
	<span id="name-error" aria-live="assertive">
		{#if $errors.name.length}
			{#each $errors.name as err}
				{err}
			{/each}
		{/if}
	</span>
	<label for="email">Email</label>
	<input
		id="email"
		name="email"
		type="email"
		aria-describedby={$errors.email ? "email-error email-desc" : "email-desc"}
		aria-invalid={$errors.email ? "true" : undefined}
		aria-required={$constraints.email?.required ? "true" : undefined}
		bind:value={$form.email}
	/>
	<span id="email-desc">It's preferred that you use your company email.</span>
	<span id="email-error" aria-live="assertive">
		{#if $errors.email.length}
			{#each $errors.email as err}
				{err}
			{/each}
		{/if}
	</span>
	<label for="password">Password</label>
	<input
		id="password"
		name="password"
		type="password"
		aria-describedby={$errors.password ? "password-error password-desc" : "password-desc"}
		aria-invalid={$errors.password ? "true" : undefined}
		aria-required={$constraints.password?.required ? "true" : undefined}
		bind:value={$form.password}
	/>
	<span id="password-desc">Ensure the password is at least 10 characters.</span>
	<span id="password-error" aria-live="assertive">
		{#if $errors.password.length}
			{#each $errors.password as err}
				{err}
			{/each}
		{/if}
	</span>
	<button>Submit</button>
</form>
```

--------------------------------

### Scaffold Fieldset and Legend for URLs

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/dynamic-fields.md

Groups the URL inputs with a Fieldset and Legend, and includes Description and FieldErrors for array-level validation.

```svelte
<!-- script tag -->
<form use:form.enhance method="POST">
	<Fieldset {form} name="urls">
		<Legend>Public URLs</Legend>
		<!-- ... -->
		<Description>Add URLs to your profile that you'd like to share with others.</Description>
		<FieldErrors />
	</Fieldset>
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### useFormControl usage (v2)

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/v2-migration-guide.md

In v2, `useFormControl` returns getters for reactive states. Use the getters directly instead of destructuring.

```svelte
<script lang="ts">
	import { useFormControl } from "formsnap";
	import { MyLabel, MyInput } from "$lib/components";

	let { label }: { label: string } = $props();

	const control = useFormControl();
</script>

<MyLabel {...control.labelProps}>
	{label}
</MyLabel>

<MyInput {...control.props} />
```

--------------------------------

### Usage: Dynamic list of URLs with ElementField

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/components/element-field.md

Shows how to use ElementField within a Fieldset to create a dynamic list of URL inputs. It uses superForm with zod validation and displays per-element errors as well as array-level errors.

```svelte
<script lang="ts">
	import { ElementField, FieldErrors, Control, Label, Fieldset, Description } from "formsnap";
	import { superForm } from "sveltekit-superforms";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { z } from "zod";

	const schema = z.object({
		urls: z.array(z.string().url()).min(2).default(["", ""]),
	});

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});

	const { form: formData, enhance } = form;
</script>

<form use:enhance method="POST">
	<Fieldset {form} name="urls">
		<Legend>Enter your URLS</Legend>
		{#each $formData.urls as _, i}
			<ElementField {form} name="urls[{i}]">
				<Control>
					{#snippet children({ props })}
						<input type="url" bind:value={$formData.urls[i]} {...props} />
					{/snippet}
				</Control>
				<FieldErrors />
			</ElementField>
		{/each}
		<Description>Your URLs will be displayed on your public profile.</Description>
		<FieldErrors />
	</Fieldset>
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Render dynamic URL fields with ElementField

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/dynamic-fields.md

Iterates over the urls array and renders an ElementField for each index, with a Control containing a label and input, plus Description and FieldErrors for individual URL validation.

```svelte
<!-- script tag -->
<form use:enhance method="POST">
	<Fieldset {form} name="urls">
		<Legend>Public URLs</Legend>
		{#each $formData.urls as _, i}
			<ElementField {form} name="urls[{i}]">
				<Control>
					{#snippet children({ props })}
						<Label class="sr-only">URL {i + 1}</Label>
						<input type="url" {...props} bind:value={$formData.urls[i]} />
					{/snippet}
				</Control>
				<Description class="sr-only">
					This URL will be publicly available on your profile.
				</Description>
				<FieldErrors />
			</ElementField>
		{/each}
		<FieldErrors />
	</Fieldset>
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Constructing a form field for email

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/quick-start.md

Construct a form field for the email property using the Field component. Pass the form and name to set up the field context. The name is typed to the schema keys.

```svelte
<script lang="ts">
	import { superForm } from "sveltekit-superforms";
	import { Field } from "formsnap";
	import { zodClient } from "sveltekit-superforms/adapters";
	import { allergies, schema, themes } from "./schema.js";
	import SuperDebug from "sveltekit-superforms";

	let { data } = $props();

	const form = superForm(data.form, {
		validators: zodClient(schema),
	});
	const { form: formData, enhance } = form;
</script>

<form method="POST" use:enhance>
	<Field {form} name="email">
		<!-- ... -->
	</Field>
</form>
<SuperDebug data={$formData} />
```

--------------------------------

### Using LabelInput within a Control component

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/composition/use-form-control.md

Shows how to use the custom LabelInput component within a Field and Control context, passing the form and name to Field.

```svelte
<Field {form} name="email">
	<Control>
		<LabelInput label="Email address" />
	</Control>
</Field>
```

--------------------------------

### Composition: CustomElementField wrapper component

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/components/element-field.md

Shows how to create a wrapper component around ElementField to automatically include FieldErrors and maintain type safety using generics. Note that eslint may complain about the generics, but it's a false positive.

```svelte
<script lang="ts" module>
	import type { FormPathArrays, FormPathLeaves } from "sveltekit-superforms";
	type T = Record<string, unknown>;
	type U = unknown;
</script>

<script lang="ts" generics="T extends Record<string, unknown>, U extends FormPathLeaves<T>">
	import { ElementField, type ElementFieldProps, FieldErrors } from "formsnap";
	import type { SuperForm } from "sveltekit-superforms";

	let { form, name, children: childrenProp }: ElementFieldProps<T, U> = $props();
</script>

<ElementField {form} {name}>
	{#snippet children(snippetProps)}
		{@render childrenProp(snippetProps)}
	{/snippet}
	<FieldErrors />
</ElementField>
```

--------------------------------

### useFormField usage (v2)

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/v2-migration-guide.md

In v2, `useFormField` returns getters for reactive states instead of stores. Do not destructure the returned object; use the getters directly.

```svelte
<script lang="ts">
	import { useFormField } from "formsnap";

	const field = useFormField();
</script>

Errors for this field: {field.errors}
Constraints for this field: {field.constraints}
Is this field tainted? {field.tainted}
```

--------------------------------

### Create the scoops field with a select input

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/multiple-select.md

Builds the scoops field using the Field, Control, Label, and FieldErrors components. The select input is bound to the form data and offers options from 1 to 5 scoops.

```svelte
<!-- script tag -->
<form use:form.enhance method="POST">
	<Field {form} name="scoops">
		<Control>
			{#snippet children({ props })}
				<div class="flex flex-col items-start gap-1">
					<Label>Number of scoops</Label>
					<select {...props} bind:value={$formData.scoops}>
						{#each Array.from({ length: 5 }, (_, i) => i + 1) as num}
							<option value={num}>
								{num === 1 ? `${num} Scoop` : `${num} Scoops`}
							</option>
						{/each}
					</select>
				</div>
			{/snippet}
		</Control>
		<FieldErrors />
	</Field>
	<button type="submit">Submit</button>
</form>
```

--------------------------------

### Binding ref to Description component

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/components/description.md

The ref prop accepts an HTMLElement or null and provides a reference to the underlying div element. Use bind:ref to access the element.

```svelte
<Description bind:ref={descriptionRef}>
	<!-- ... -->
</Description>
```

--------------------------------

### Define the Zod schema for the ice cream order form

Source: https://github.com/svecosystem/formsnap/blob/main/docs/src/content/recipes/multiple-select.md

Defines the validation schema for the form, including arrays of enums for flavors and toppings with custom validation rules. The schema enforces a minimum of one flavor and a maximum of two toppings, and includes a refine rule that limits the number of flavors to the number of scoops.

```ts
import { z } from "zod";

export const flavors = ["vanilla", "chocolate", "cookies and cream", "strawberry"] as const;

export const toppings = ["sprinkles", "hot fudge", "whipped cream", "cherry"] as const;

export const schema = z
	.object({
		scoops: z.number().min(1).default(1),
		flavors: z.array(z.enum(flavors)).min(1, "You must select at least one flavor."),
		toppings: z.array(z.enum(toppings)).max(2, "You can only select up to two toppings."),
	})
	.refine((data) => (data.flavors.length > data.scoops ? false : true), {
		message: "You can only select as many flavors as you have scoops.",
		path: ["flavors"],
	});
```
Tokens:
Raw