# Formisch
The modular and type-safe form library for any framework.
## Get started
### Introduction
Formisch is a schema-based, headless form library for Qwik. It manages form state and validation. It is type-safe, fast by default and its bundle size is small due to its modular design. Try it out in our playground!
#### Highlights
- Small bundle size starting at 2.5 kB
- Schema-based validation with Valibot
- Type safety with autocompletion in editor
- It's fast – DOM updates are fine-grained
- Minimal, readable and well thought out API
- Supports all native HTML form fields
#### Example
Every form starts with the `useForm$` hook. It initializes your form's store based on the provided Valibot schema and infers its types. Next, wrap your form in the `` component. It's a thin layer around the native `` element that handles form validation and submission. Then, you can access the state of a field with the `useField$` hook or the `` component to connect your inputs.
```tsx
import { Field, Form, useForm$ } from '@formisch/qwik';
import { component$ } from '@qwik.dev/core';
import * as v from 'valibot';
const LoginSchema = v.object({
email: v.pipe(v.string(), v.email()),
password: v.pipe(v.string(), v.minLength(8)),
});
export default component$(() => {
const loginForm = useForm$(() => ({
schema: LoginSchema,
}));
return (
);
});
```
In addition, Formisch offers several functions (we call them "methods") that can be used to read and manipulate the form state. These include `focus`, `getAllErrors`, `getErrors`, `getInput`, `handleSubmit`, `insert`, `move`, `remove`, `replace`, `reset`, `setErrors`, `setInput`, `submit`, `swap` and `validate`. These methods allow you to control the form programmatically.
#### Comparison
What makes Formisch unique is its framework-agnostic core, which is fully native to the framework you are using. It works by inserting framework-specific reactivity blocks when the core package is built. The result is a small bundle size and native performance for any UI update. This feature, along with a few others, distinguishes Formisch from other form libraries. My vision for Formisch is to create a framework-agnostic platform similar to Vite, but for forms.
#### Partners
Thanks to our partners who support the development! Join them and contribute to the sustainability of open source software!
#### Feedback
Find a bug or have an idea how to improve the library? Please fill out an issue. Together we can make forms even better!
#### License
This project is available free of charge and licensed under the MIT license.
### Installation
Below you will learn how to add Formisch to your project.
#### TypeScript
If you are using TypeScript, we recommend that you enable strict mode in your `tsconfig.json` so that all types are calculated correctly.
> The minimum required TypeScript version is v5.0.2.
```ts
{
"compilerOptions": {
"strict": true,
// ...
}
}
```
#### Install Valibot
Formisch uses [Valibot](https://valibot.dev/) for schema-based validation. You need to install it first because it is a peer dependency.
```bash
npm install valibot # npm
yarn add valibot # yarn
pnpm add valibot # pnpm
bun add valibot # bun
deno add npm:valibot # deno
```
#### Install Formisch
You can add Formisch to your project with a single command using your favorite package manager.
```bash
npm install @formisch/qwik # npm
yarn add @formisch/qwik # yarn
pnpm add @formisch/qwik # pnpm
bun add @formisch/qwik # bun
deno add npm:@formisch/qwik # deno
```
Then you can import it into any JavaScript or TypeScript file.
```ts
import { … } from '@formisch/qwik';
```
#### For AI Agents
We provide agent skills that teach AI agents the correct patterns for working with Valibot and Formisch. You can install them by running the following command in your terminal:
```bash
npx skills add open-circle/agent-skills
```
You can learn more about the Valibot and Formisch agent skill [here](https://github.com/open-circle/agent-skills).
### LLMs.txt
If you are using AI to generate forms with Formisch, you can use our LLMs.txt files to help the AI better understand the library.
#### What is LLMs.txt?
An [LLMs.txt](https://llmstxt.org/) file is a plain text file that provides instructions or metadata for large language models (LLMs). It often specifies how the LLMs should process or interact with content. It is similar to a robots.txt file, but is tailored for AI models.
#### Available routes
We provide several LLMs.txt routes. Use the route that works best with your AI tool.
- [`llms.txt`](/llms.txt) contains a table of contents with links to all Markdown files
- [`llms-qwik.txt`](/llms-qwik.txt) contains a table of contents with links to Qwik related files
- [`llms-qwik-full.txt`](/llms-qwik-full.txt) contains the Markdown content of the entire Qwik docs
- [`llms-qwik-guides.txt`](/llms-qwik-guides.txt) contains the Markdown content of the Qwik guides
- [`llms-qwik-api.txt`](/llms-qwik-api.txt) contains the Markdown content of the Qwik API reference
> We also provide a Markdown version of every documentation page. You can access it by replacing the trailing slash (`/`) in the URL with `.md`. For example, `/qwik/guides/installation/` becomes `/qwik/guides/installation.md`.
#### For AI Agents
Our [`SKILL.md`](https://github.com/open-circle/agent-skills/blob/main/skills/formisch/SKILL.md) contains specialized instructions for AI agents to build forms and manage state.
#### How to use it
To help you get started, here are some examples of how the LLMs.txt files can be used with various AI tools.
> Please help us by adding more examples of other AI tools. If you use a tool that supports LLMs.txt files, please [open a pull request](https://github.com/fabian-hiller/valibot/pulls) to add it to this page.
##### Cursor
You can add a custom documentation as context in Cursor using the `@Docs` feature. Read more about it [here](https://docs.cursor.com/context/@-symbols/@-docs).
## Main concepts
### Define your form
Creating a form in Formisch starts with defining a Valibot schema. The schema serves as the blueprint for your form, outlining the structure, data types, and validation rules for each field.
#### Schema definition
Formisch is a schema-first form library built on top of [Valibot](https://valibot.dev/). When you create a form with `useForm$`, TypeScript types are automatically inferred from your schema, giving you full autocompletion and type safety throughout your form without needing to write any manual type definitions.
##### Example schema
The following schema defines a form with two required string fields. The `email` field must be a valid email format, and the `password` field must be at least 8 characters long. Each validation includes custom error messages that will be displayed when validation fails.
> For more complex schema examples, check out the schemas of our playground.
```ts
import * as v from 'valibot';
const LoginSchema = v.object({
email: v.pipe(
v.string('Please enter your email.'),
v.nonEmpty('Please enter your email.'),
v.email('The email address is badly formatted.')
),
password: v.pipe(
v.string('Please enter your password.'),
v.nonEmpty('Please enter your password.'),
v.minLength(8, 'Your password must have 8 characters or more.')
),
});
```
#### Schema validation
Your schema definition should reflect exactly the data you expect when submitting the form. For example, if the value of a field is optional and will only be submitted in certain cases, your schema should reflect this information by using `v.optional(…)`.
```ts
import * as v from 'valibot';
const ProfileSchema = v.object({
name: v.pipe(v.string(), v.nonEmpty()),
bio: v.optional(v.string()), // <- Optional field
});
```
Formisch validates your form values against the schema before submission, ensuring that your form can only be submitted if it matches your schema definition.
#### Next steps
Now that you understand how to define your form schema, continue to the create your form guide to learn how to initialize your form with `useForm$`.
### Create your form
Formisch consists of hooks, components and methods. To create a form you use the `useForm$` hook.
#### Form hook
The `useForm$` hook initializes and returns the store of your form. The store contains the state of the form and can be used with other Formisch hooks, components and methods to build your form.
```tsx
import { Field, Form, useForm$ } from '@formisch/qwik';
import { component$ } from '@qwik.dev/core';
import * as v from 'valibot';
const LoginSchema = v.object({
email: v.pipe(v.string(), v.email()),
password: v.pipe(v.string(), v.minLength(8)),
});
export default component$(() => {
const loginForm = useForm$(() => ({
schema: LoginSchema,
}));
return ;
});
```
##### Configuration options
The `useForm$` hook accepts a configuration object with the following options:
- `schema`: Your Valibot schema that defines the form
- `initialInput`: Initial values for your form fields (optional)
- `validate`: When validation first occurs (optional, defaults to `'submit'`)
- `revalidate`: When revalidation occurs after initial validation (optional, defaults to `'input'`)
```tsx
const loginForm = useForm$(() => ({
schema: LoginSchema,
initialInput: {
email: 'user@example.com',
},
validate: 'initial',
revalidate: 'input',
}));
```
Formisch tracks two inputs for every field: the **initial input** (baseline for dirty tracking) and the **current input** (what the user is editing). In many apps, the initial input represents the server state while the current input represents the client state.
`isDirty` becomes `true` when a field's current input differs from its initial input. Use `setInput` to update the current input (client state), and use `reset` to update the initial input (baseline) when your server data changes or is refreshed.
##### Multiple forms
When a page contains multiple forms, you can create separate form stores for each one:
```tsx
import { Form, useForm$ } from '@formisch/qwik';
import { component$ } from '@qwik.dev/core';
import * as v from 'valibot';
const LoginSchema = v.object({
email: v.pipe(v.string(), v.email()),
password: v.pipe(v.string(), v.minLength(8)),
});
const RegisterSchema = v.object({
username: v.pipe(v.string(), v.minLength(3)),
email: v.pipe(v.string(), v.email()),
password: v.pipe(v.string(), v.minLength(8)),
});
export default component$(() => {
const loginForm = useForm$(() => ({ schema: LoginSchema }));
const registerForm = useForm$(() => ({ schema: RegisterSchema }));
return (
<>
);
});
```
#### Next steps
Now that you know how to create a form, continue to the add form fields guide to learn how to connect your input elements to the form using the `Field` component.
### Add form fields
To add a field to your form, you can use the `Field` component or the `useField$` hook. Both are headless and provide access to field state for building your form UI.
#### Field component
The `Field` component has two mandatory properties: `of` which accepts the form store, and `path` which specifies which field to connect. If you use TypeScript, you get full autocompletion for the path based on your schema.
##### Render prop
The `Field` component uses a `render$` prop that receives the field store as its parameter. The field store includes signals for the current value, error messages, and props to spread onto your input element.
```tsx
import { Field, Form, useForm$ } from '@formisch/qwik';
import { component$ } from '@qwik.dev/core';
import * as v from 'valibot';
const LoginSchema = v.object({
email: v.pipe(v.string(), v.email()),
password: v.pipe(v.string(), v.minLength(8)),
});
export default component$(() => {
const loginForm = useForm$(() => ({
schema: LoginSchema,
}));
return (
);
});
```
> **Important:** If you plan to set initial values with `initialInput` or programmatically control field values using methods like `setInput` or `reset`, you must make your fields controlled by setting the appropriate attributes (like `value`, `checked`, or `selected`). See the controlled fields guide to learn more.
##### Headless design
The `Field` component does not render its own UI elements. It is headless and provides only the data layer of the field. This allows you to freely define your user interface. You can use HTML elements, custom components or an external UI library.
##### Path array
The `path` property accepts an array of strings and numbers that represents the path to the field in your schema. For top-level fields, it's simply the field name wrapped in an array:
```tsx
(
)}
/>
```
For nested fields, the path reflects the structure of your schema:
```tsx
// For a schema like: v.object({ user: v.object({ email: v.string() }) })
(
)}
/>
```
##### Type safety
The API design of the `Field` component results in a fully type-safe form. For example, if you change your schema, TypeScript will immediately alert you if the path is invalid. The field state is also fully typed based on your schema, giving you autocompletion for properties like `field.input`.
#### useField$ hook
For very complex forms where you create individual components for each form field, Formisch provides the `useField$` hook. It allows you to access the field state directly within your component logic.
```tsx
import { useField$ } from '@formisch/qwik';
import type { FormStore } from '@formisch/qwik';
import { component$ } from '@qwik.dev/core';
import * as v from 'valibot';
type EmailInputProps = {
form: FormStore>;
};
export const EmailInput = component$((props) => {
const field = useField$(props.form, { path: ['email'] });
return (
{field.errors.value &&
{field.errors.value[0]}
}
);
});
```
##### When to use which
- **Use `Field` component**: When defining multiple fields in the same component. It ensures you don't accidentally access the wrong field store.
- **Use `useField$` hook**: When creating field components for single fields. It allows you to access field state in your component logic.
The `Field` component is essentially a thin wrapper around `useField$` that allows you to access the field state within JSX code.
#### Field store
The field store provides access to the following properties as signals:
- `props`: JSX props to spread onto your input element (includes event handlers, ref callback, name attribute, and `autofocus` to automatically focus fields with errors).
- `input`: A signal containing the current input value of the field (access with `.value`).
- `errors`: A signal containing an array of error messages if validation fails (access with `.value`).
- `isTouched`: A signal indicating whether the field has been touched (access with `.value`).
- `isDirty`: A signal indicating whether the current input differs from the initial input (access with `.value`).
- `isValid`: A signal indicating whether the field passes all validation rules (access with `.value`).
- `onInput`: Sets the field input value programmatically. Use this when the field cannot be connected to a native HTML element (e.g., complex custom inputs or component libraries that don't expose the underlying element).
#### Next steps
Now that you know how to add fields to your form, continue to the input components guide to learn about creating reusable input components for your forms.
### Input components
To make your code more readable, we recommend that you develop your own input components if you are not using a prebuilt UI library. There you can encapsulate logic to display error messages, for example.
> If you're already a bit more experienced, you can use the input components we developed for our playground as a starting point. You can find the code in our GitHub repository here.
#### Why input components?
Currently, your fields might look something like this:
```tsx
(
{field.errors.value &&
{field.errors.value[0]}
}
)}
/>
```
If CSS and a few more functionalities are added here, the code quickly becomes confusing. In addition, you have to rewrite the same code for almost every form field.
Our goal is to develop a `TextInput` component so that the code ends up looking like this:
```tsx
(
)}
/>
```
#### Create an input component
In the first step, you create a new file for the `TextInput` component and, if you use TypeScript, define its properties.
```tsx
import type { FieldElementProps } from '@formisch/qwik';
import { component$, type ReadonlySignal } from '@qwik.dev/core';
interface TextInputProps extends FieldElementProps {
type: 'text' | 'email' | 'tel' | 'password' | 'url' | 'date';
label?: string;
placeholder?: string;
input: ReadonlySignal;
errors: ReadonlySignal<[string, ...string[]] | null>;
required?: boolean;
}
```
##### Component function
In the next step, add the component function to the file. We can destructure the props directly.
```tsx
import type { FieldElementProps } from '@formisch/qwik';
import { component$, type ReadonlySignal } from '@qwik.dev/core';
interface TextInputProps extends FieldElementProps {
/* ... */
}
export const TextInput = component$(
({ input, label, errors, ...props }) => {
// Component JSX will go here
}
```
##### JSX code
After that, you can add the JSX code to the return statement.
```tsx
import type { FieldElementProps } from '@formisch/qwik';
import { component$, type ReadonlySignal } from '@qwik.dev/core';
interface TextInputProps extends FieldElementProps {
/* ... */
}
export const TextInput = component$(
({ input, label, errors, ...props }) => {
const { name, required } = props;
return (
{label && (
)}
{errors.value &&
{errors.value[0]}
}
);
}
);
```
##### Next steps
You can now build on this code and add CSS, for example. You can also follow the procedure to create other components such as `Checkbox`, `Slider`, `Select` and `FileInput`.
##### Final code
Below is an overview of the entire code of the `TextInput` component.
```tsx
import type { FieldElementProps } from '@formisch/qwik';
import { component$, type ReadonlySignal } from '@qwik.dev/core';
interface TextInputProps extends FieldElementProps {
type: 'text' | 'email' | 'tel' | 'password' | 'url' | 'date';
label?: string;
placeholder?: string;
input: ReadonlySignal;
errors: ReadonlySignal<[string, ...string[]] | null>;
required?: boolean;
}
export const TextInput = component$(
({ input, label, errors, ...props }) => {
const { name, required } = props;
return (
{label && (
)}
{errors.value &&
{errors.value[0]}
}
);
}
);
```
#### Using component libraries
When using component libraries that don't expose their underlying native HTML elements, you cannot spread `field.props` directly. Instead, use `field.onInput` to update the value programmatically:
```tsx
import { DatePicker } from 'some-component-library';
(
field.onInput(newDate)}
/>
)}
/>;
```
The `field.onInput` method updates the field value and triggers validation. For more details, see the controlled fields guide.
#### Next steps
Now that you know how to create reusable input components, continue to the handle submission guide to learn how to process form data when the user submits the form.
### Handle submission
Now your first form is almost ready. There is only one little thing missing and that is the data processing when the form is submitted.
#### Submit event
To process the values on submission, you need to pass a function to the `onSubmit$` property of the `Form` component. The first parameter passed to the function contains the validated form values.
```tsx
import { Field, Form, type SubmitHandler, useForm$ } from '@formisch/qwik';
import { $, component$ } from '@qwik.dev/core';
import * as v from 'valibot';
const LoginSchema = v.object({
email: v.pipe(v.string(), v.email()),
password: v.pipe(v.string(), v.minLength(8)),
});
export default component$(() => {
const loginForm = useForm$(() => ({
schema: LoginSchema,
}));
const submitForm = $>((values) => {
// Process the validated form values
console.log(values); // { email: string, password: string }
});
return (
);
});
```
The `SubmitHandler` type ensures type safety for your submission handler, automatically inferring the types of validated values from your schema. If you need access to the submit event, use `SubmitEventHandler` instead.
##### Prevent default
When the form is submitted, `event.preventDefault()` is executed by default to prevent the window from reloading so that the values can be processed directly in the browser and the state of the form is preserved.
##### Loading state
While the form is being submitted, you can use `loginForm.isSubmitting.value` to display a loading animation and disable the submit button:
```tsx
```
The form store also provides other reactive properties like `isSubmitted`, `isValidating`, `isTouched`, `isDirty`, `isValid`, and `errors` for tracking form state. Note that `errors` only contains validation errors at the root level of the form — to get all errors from all fields, use the `getAllErrors` method.
##### Async submission
The submit handler can be asynchronous, allowing you to perform API calls or other async operations:
```tsx
const submitForm = $>(async (values) => {
try {
const response = await fetch('/api/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(values),
});
if (response.ok) {
// Handle successful login
console.log('Login successful!');
} else {
// Handle error
console.error('Login failed');
}
} catch (error) {
console.error('Error during submission:', error);
}
});
```
##### Trigger submission
If you want to trigger submission programmatically from outside the form, you can use the `submit` method. It calls `requestSubmit()` on the underlying form element:
```tsx
import { submit } from '@formisch/qwik';
;
```
#### Submit without \
