# Formisch
The lightweight, schema-first, and fully type-safe form library for React, Solid, Vue, Svelte and more.
## Get started (guides)
### Introduction
Formisch is a schema-based, headless form library for React. 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
- Open source and fully tested with 100 % coverage
- It's fast – re-renders only if necessary
- 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/react';
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 function LoginPage() {
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, giving you native performance for any UI update. A modular methods API keeps bundles starting at just ~2.5 kB by only including the methods you import, and end-to-end type safety covers deeply nested paths and field arrays with TypeScript inference that stays fast even as forms grow.
For a side-by-side look at how Formisch compares to React Hook Form and TanStack Form, see the comparison guide.
#### Vision
My vision for Formisch is to create a framework-agnostic platform similar to Vite, but for forms — a shared core that lets the same mental model and codebase work natively across every modern UI framework.
#### 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/react # npm
yarn add @formisch/react # yarn
pnpm add @formisch/react # pnpm
bun add @formisch/react # bun
deno add npm:@formisch/react # deno
```
Then you can import it into any JavaScript or TypeScript file.
```ts
import { … } from '@formisch/react';
```
#### 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).
### Comparison
Formisch is one of several form libraries available for React. The two most common alternatives are [React Hook Form](https://react-hook-form.com) and [TanStack Form](https://tanstack.com/form/latest). This page is meant as a quick reference for picking the right tool. For a deeper explanation of the architectural differences and the reasoning behind each row of the table below, see our long-form comparison article.
#### At a glance
| | **Formisch** | React Hook Form | TanStack Form |
| ---------------------- | --------------------------------------- | ----------------------------------- | --------------------------------------- |
| Type source | Inferred from schema | Generic you declare | Inferred from `defaultValues` |
| Validation location | Defined in schema | Per-field or resolver | Per-validator config |
| Validation timing | Form-wide `validate` / `revalidate` | Form-wide `mode` option | Per-validator trigger |
| Async validation | Built-in via schema | Manual loading state | Built-in `isValidating` |
| Re-render scope | Automatic per signal | Manual via `watch` / `useFormState` | Automatic per subscription |
| Schema libraries | Valibot | Any via resolvers | Standard Schema |
| Bundle size (min+gzip) | From ~2.5 kB | ~12 kB | ~15 kB |
| Framework support | React, Preact, Solid, Svelte, Vue, Qwik | React | React, Vue, Solid, Svelte, Lit, Angular |
The table is intentionally short. It only covers the dimensions that most often drive a library choice in practice. Other differences such as devtools, ecosystem maturity, and community size are real but tend to matter less than how each library handles types, validation, and re-renders.
#### Why Formisch?
Three reasons to pick Formisch over the alternatives above:
**One schema, no second source of truth.** A single Valibot schema is everything the form needs: the runtime validator, the source of types, and the description of the form's structure — all at once. There is no separate TypeScript generic to declare, no `defaultValues` object to keep aligned with the schema, no resolver to configure. When the schema changes, every part of the form follows — at compile time and at runtime.
**The smallest bundle, by a wide margin.** Formisch starts at ~2.5 kB and grows only as you import additional methods like `focus`, `getInput`, and `reset`. That is several times smaller than the alternatives in the table above — and it stays that way because the core is intentionally small and the library is fully tree-shakable, so methods you don't import don't end up in your bundle.
**Type safety that stays fast.** Types flow from the schema through every API, including deeply nested paths and field arrays. The inference is structured to keep TypeScript editor performance from degrading as schemas grow — which matters in large codebases where heavily-generic form libraries become a friction point.
#### Which library should you use?
**React Hook Form** is a mature, well-documented choice with a large community and years of production usage. For simple to moderately complex forms, it remains a reasonable default. The tradeoffs only become visible as forms grow: types and schema drift out of sync, validation rules spread across components, and re-render scope becomes your responsibility.
**TanStack Form** is a good fit when you need fine-grained control over validation timing and built-in async validation handling without building that infrastructure yourself. It is also the natural choice if your team is already invested in the TanStack ecosystem and values a consistent mental model across data fetching, routing, and forms.
**Formisch** makes the most sense for new projects in TypeScript-heavy codebases, especially when you expect forms to grow in complexity. The schema-first design means there is a single source of truth for types, runtime validation, and form structure, so there is less to keep aligned over time. The main consideration is that Formisch currently supports only [Valibot](https://valibot.dev) as the schema library.
#### Migrating from React Hook Form
Migrating from React Hook Form to Formisch is a genuine rewrite of the form layer, not a drop-in replacement. The mental model is different: instead of starting from a component and attaching form behavior to it, you start from a schema and build the component around it. The two libraries can coexist in the same application, so you can migrate one form at a time.
For a side-by-side mapping of common React Hook Form APIs to their Formisch equivalents, see the migration section of the comparison article.
#### Next steps
If you have decided that Formisch is a good fit, install it via the installation guide and start building by defining your form.
### 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-react.txt`](/llms-react.txt) contains a table of contents with links to React related files
- [`llms-react-full.txt`](/llms-react-full.txt) contains the Markdown content of the entire React docs
- [`llms-react-guides.txt`](/llms-react-guides.txt) contains the Markdown content of the React guides
- [`llms-react-api.txt`](/llms-react-api.txt) contains the Markdown content of the React 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, `/react/guides/installation/` becomes `/react/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 (guides)
### 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/react';
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 function App() {
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/react';
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 function App() {
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.
##### Children prop
As a child, you pass a function to the `Field` component that returns JSX. The function receives the field store as its parameter, which includes the current value, error messages, and props to spread onto your input element.
```tsx
import { Field, Form, useForm } from '@formisch/react';
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 function App() {
const loginForm = useForm({
schema: LoginSchema,
});
return (
);
}
```
> **Important:** The event handlers in `field.props` read the value from the DOM as a string. Fields with a non-string schema like `v.number()` or `v.date()` therefore need to be controlled to store the value with the correct type. See the controlled fields guide to learn more.
> **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
{(field) => }
```
For nested fields, the path reflects the structure of your schema:
```tsx
// For a schema like: v.object({ user: v.object({ email: v.string() }) })
{(field) => }
```
##### 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/react';
import type { FormStore } from '@formisch/react';
import * as v from 'valibot';
type EmailInputProps = {
form: FormStore>;
};
function EmailInput(props: EmailInputProps) {
const field = useField(props.form, { path: ['email'] });
return (
{field.errors &&
{field.errors[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. They are plain values, but because Formisch wires into React's rendering, your components re-render when they change.
- `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`: The current input value of the field.
- `errors`: The current array of error messages if validation fails.
- `isTouched`: Whether the field has been touched.
- `isDirty`: Whether the current input differs from the initial input.
- `isValid`: Whether the field passes all validation rules.
- `onChange`: 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) => (
{field.errors &&
{field.errors[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
{(field) => (
)}
```
#### 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/react';
interface TextInputProps extends FieldElementProps {
type: 'text' | 'email' | 'tel' | 'password' | 'url' | 'date';
label?: string;
placeholder?: string;
input: string | undefined;
errors: [string, ...string[]] | null;
required?: boolean;
}
```
##### Component function
In the next step, add the component function to the file. We can destructure props directly and spread the remaining props.
```tsx
import type { FieldElementProps } from '@formisch/react';
interface TextInputProps extends FieldElementProps {
/* ... */
}
export function TextInput({ label, input, errors, ...props }: TextInputProps) {
// Component implementation
}
```
##### JSX code
After that, you can add the JSX code to the return statement.
```tsx
import type { FieldElementProps } from '@formisch/react';
interface TextInputProps extends FieldElementProps {
/* ... */
}
export function TextInput({ label, input, errors, ...props }: TextInputProps) {
const { name, required } = props;
return (
{label && (
)}
{errors &&
{errors[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/react';
interface TextInputProps extends FieldElementProps {
type: 'text' | 'email' | 'tel' | 'password' | 'url' | 'date';
label?: string;
placeholder?: string;
input: string | undefined;
errors: [string, ...string[]] | null;
required?: boolean;
}
export function TextInput({ label, input, errors, ...props }: TextInputProps) {
const { name, required } = props;
return (
{label && (
)}
{errors &&
{errors[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.onChange` to update the value programmatically:
```tsx
import { DatePicker } from 'some-component-library';
{(field) => (
field.onChange(newDate)}
/>
)}
;
```
The `field.onChange` 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, useForm } from '@formisch/react';
import type { SubmitHandler } from '@formisch/react';
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 function App() {
const loginForm = useForm({
schema: LoginSchema,
});
const submitForm: SubmitHandler = (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` 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: SubmitHandler = 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/react';
;
```
#### Submit without \