Formsnap Documentation

The Field component provides the necessary context for its children to react to changes in the form state. It manages field-specific information such as IDs required for ARIA attributes and accessibility.

Important: The Field component does not render any HTML elements itself; it strictly provides context to its children.

Each Field creates its own context, and children only access the context of their immediate parent Field.

<Field {form} {name}>
  {#snippet children(fieldProps)}
    <!-- Your field UI here using fieldProps -->
  {/snippet}
</Field>

Formsnap is a wrapper for sveltekit-superforms that provides accessible form components. The workflow follows three main steps:

1. Define a schema: Use a library like Zod to define your form data structure.
2. Server-side validation: Use superValidate in your SvelteKit load function to return the form object to the client.
3. Client-side rendering: Use Formsnap components (Field, Control, FieldErrors, etc.) in your Svelte component to build the UI. You connect the Formsnap components to your Superforms instance by passing the form object and the specific field name.

Formsnap provides specific data-* attributes on its rendered elements. You can use these attributes as CSS selectors to style components globally or to target specific states (like validation errors) on parent elements. This is useful for styling elements that change based on the form's state without needing to manage complex class logic manually.

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

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

In Formsnap, a Control is used to wrap any interactive form element (like an <input>, <select>, or custom checkbox) to ensure it is correctly associated with a Label for accessibility.

Because the Control component does not render an HTML element itself, it uses a children snippet to provide necessary attributes (like id, aria-describedby, etc.) to the actual input element. This separation allows Field components to be used for multi-control inputs like radio groups or checkbox groups without being tied to a single specific element.

To use it, wrap your input inside the Control component and use the children snippet to access and spread the provided props onto your element.

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

Use the sv CLI to scaffold a new Svelte project. You can either initialize the project in the current directory or specify a new directory name.

To create a project in the current directory:

npx sv create

To create a project in a specific directory (e.g., my-app):

npx sv create my-app

To use Formsnap, install it along with sveltekit-superforms and your preferred schema validation library (e.g., zod).

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

If you are using a utility-first CSS framework like TailwindCSS or UnoCSS, you can style Formsnap components by passing the class prop directly to them. This allows you to apply framework-specific utility classes to the underlying HTML elements rendered by the components.

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

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

The *Field* components (e.g., Field) no longer use slot props to expose state. Instead, they provide state values via the children snippet.

v1 (Old):

<Field {form} name="name" let:value let:errors let:tainted let:constraints>
	<!-- ... -->
</Field>

v2 (New):

<Field {form} name="name">
	{#snippet children({ value, errors, tainted, constraints })}
		<!-- ... access values here -->
	{/snippet}
</Field>

If you do not need to access the field state, you can simply use the component without a snippet:

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