# Formisch
The modular and type-safe form library for any framework.
## Get started
### Introduction
Formisch is a schema-based, headless form library for Vue. 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` composable. 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` composable or the `` component to connect your inputs.
```vue
```
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.com/) 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/vue # npm
yarn add @formisch/vue # yarn
pnpm add @formisch/vue # pnpm
bun add @formisch/vue # bun
deno add npm:@formisch/vue # deno
```
Then you can import it into any JavaScript or TypeScript file.
```ts
import { … } from '@formisch/vue';
```
### 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-vue.txt`](/llms-vue.txt) contains a table of contents with links to Vue related files
- [`llms-vue-full.txt`](/llms-vue-full.txt) contains the Markdown content of the entire Vue docs
- [`llms-vue-guides.txt`](/llms-vue-guides.txt) contains the Markdown content of the Vue guides
- [`llms-vue-api.txt`](/llms-vue-api.txt) contains the Markdown content of the Vue API reference
#### 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 composables, components and methods. To create a form you use the `useForm` composable.
#### Form composable
The `useForm` composable initializes and returns the store of your form. The store contains the state of the form and can be used with other Formisch composables, components and methods to build your form.
```vue
```
##### Configuration options
The `useForm` composable 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'`)
```ts
const loginForm = useForm({
schema: LoginSchema,
initialInput: {
email: 'user@example.com',
},
validate: 'initial',
revalidate: 'input',
});
```
##### Multiple forms
When a page contains multiple forms, you can create separate form stores for each one:
```vue
```
#### 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` composable. 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.
##### v-slot directive
As a child, you use the `v-slot` directive to access the field store, which includes the current value, error messages, and props to spread onto your input element.
```vue
```
> **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 `v-model`, `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:
```vue
```
For nested fields, the path reflects the structure of your schema:
```vue
```
##### 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 composable
For very complex forms where you create individual components for each form field, Formisch provides the `useField` composable. It allows you to access the field state directly within your component logic.
```vue
{{ 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` composable**: 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 template code.
#### Field store
The field store provides access to the following properties:
- `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`: An 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.
#### 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:
```vue
{{ 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:
```vue
```
#### 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. The `props` object from your field contains all the necessary event handlers and attributes.
```vue
```
##### Template code
After that, you can add the template code.
```vue
{{ 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.
```vue
{{ errors[0] }}
```
#### 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 `@submit` event of the `Form` component. The first parameter passed to the function contains the validated form values.
```vue
```
The `SubmitHandler` type ensures type safety for your submission handler, automatically inferring the types of validated values from your schema.
##### 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:
```vue
```
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:
```ts
const handleSubmit: 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);
}
};
```
#### Next steps
Congratulations! You've learned the core concepts of building forms with Formisch. To learn more about advanced features, check out the form methods guide to discover how to programmatically control your forms.
### Form methods
To retrieve the values of your form or to make changes to the form, Formisch provides you with several methods. These apply either to the entire form or to individual fields.
#### Reading values
To retrieve values from your form, you can use:
- `getInput`: Get the current value
of a specific field
- `getErrors`: Get error messages
for a specific field
- `getAllErrors`: Get all error
messages across the entire form
Formisch uses Vue's reactivity system internally which means that reading values with these methods is reactive. When the form state changes, any component or computation that uses these methods will automatically update to reflect the new state.
#### Setting values
To manually update form values or errors, use:
- `setInput`: Manually update the
value of a specific field
- `setErrors`: Manually set error
messages for a specific field
#### Form control
To control the form programmatically, use:
- `handleSubmit`: Create a submit
event handler that validates the form and calls your handler on success
- `reset`: Reset the form to its initial
state or update initial values
- `validate`: Manually trigger
validation for the entire form or specific fields
- `submit`: Programmatically trigger
form submission
- `focus`: Focus on a specific field
#### Array operations
For working with field arrays, Formisch provides:
- `insert`: Insert a new item into a
field array
- `remove`: Remove an item from a field
array
- `move`: Move an item to a different
position in a field array
- `swap`: Swap two items in a field array
- `replace`: Replace an item in a
field array
#### API design
All methods in Formisch follow a consistent API pattern: the first parameter is always the form store, and the second parameter (if necessary) is always a config object. This design makes the API flexible and consistent across all methods. Once you understand this pattern, you basically understand the entire API design.
Here are some examples:
```tsx
// Get the value of a field
const emailInput = getInput(loginForm, { path: ['email'] });
// Reset the form with new initial values
reset(loginForm, { initialInput: { email: '', password: '' } });
// Move an item in a field array
move(loginForm, { path: ['items'], from: 0, to: 3 });
```
#### API reference
You can find detailed documentation for each method in our API reference.
## Advanced guides
### Special inputs
As listed in our features, the library supports all native HTML form fields. This includes the HTML `` element as well as special cases of the `` element.
> In our playground you can take a look at such fields and test them out.
#### Checkbox
A simple checkbox represents a boolean and is `true` when checked or `false` otherwise.
```vue
```
However, you can also use multiple checkboxes to represent an array of strings. For this you simply have to add the `value` attribute to the HTML `` element.
```vue
```
#### Select
An HTML `` element allows you to select a string from a predefined list of options.
```vue
```
However, if you set the `multiple` attribute, multiple options can be selected making the field represent an array of strings.
```vue
```
#### File
For the HTML `` element it works similar to the HTML `` element. Without the `multiple` attribute it represents a single file and with, a list of files.
```vue
```
With the `multiple` attribute, users can select multiple files:
```vue
```
### Controlled fields
By default, all form fields are uncontrolled because that's the default behavior of the browser. For a simple login or contact form this is quite sufficient.
#### Why controlled?
As soon as your forms become more complex, for example you set initial values or change the values of a form field via `setInput`, it becomes necessary that you control your fields yourself. For example, depending on which HTML form field you use, you may need to set the `value`, `checked` or `selected` attributes.
#### Simple text inputs
For most input types including text, email, number, and date, you simply add the `v-model` directive. Vue automatically handles type conversions for you:
```vue
```
##### Vue's automatic type handling
Vue's `v-model` automatically handles different input types without special code:
**Number inputs** - Vue converts between strings and numbers automatically:
```vue
```
**Date inputs** - Vue handles the date string format automatically:
```vue
```
This works seamlessly whether your schema expects strings, numbers, or dates - Vue will handle the conversion.
#### Checkboxes
For checkboxes, you need to bind to the `checked` attribute and handle both boolean and array values:
**Single checkbox** (boolean):
```vue
```
**Multiple checkboxes** (array of strings):
```vue
```
#### Select elements
For select elements, you need to bind to the `selected` attribute:
**Single select**:
```vue
```
**Multiple select**:
```vue
```
#### File inputs
The HTML `` element is an exception because it cannot be controlled in the traditional way. However, you can control the UI around it. For inspiration, check out our `FileInput` component from the playground.
#### Next steps
Now that you understand controlled fields, you can explore more advanced topics like nested fields and field arrays to handle complex form structures.
### Nested fields
To add a little more structure to a complex form or to match the values of the form to your database, you can also nest your form fields in objects as deep as you like.
#### Schema definition
For example, in the schema below, the first and last name are grouped under the object with the key `name`.
```tsx
import * as v from 'valibot';
const ContactSchema = v.object({
name: v.object({
first: v.pipe(v.string(), v.nonEmpty()),
last: v.pipe(v.string(), v.nonEmpty()),
}),
email: v.pipe(v.string(), v.email()),
message: v.pipe(v.string(), v.nonEmpty()),
});
```
#### Path array
When creating a nested field, use an array with multiple elements for the `path` property to refer to the nested field. The array represents the path through the nested structure.
```vue
```
If you're using TypeScript, your editor will provide autocompletion for the path based on your schema structure.
#### Deep nesting
You can nest objects as deeply as needed. Simply extend the path array with additional keys:
```vue
```
#### Type safety
The path array is fully type-safe. TypeScript will validate that each element in your path corresponds to a valid key in your schema structure, providing autocompletion and compile-time errors if you reference a non-existent path.
### Field arrays
A somewhat more special case are dynamically generated form fields based on an array. Since adding, removing, swapping and moving items can be a big challenge here, the library provides the `FieldArray` component which, in combination with various methods, makes it very easy for you to create such forms.
> In our playground you can take a look at a form with a field array and test them out.
#### Create a field array
##### Schema definition
In the following example we create a field array for a todo form with the following schema:
```tsx
import * as v from 'valibot';
const TodoFormSchema = v.object({
heading: v.pipe(v.string(), v.nonEmpty()),
todos: v.pipe(
v.array(
v.object({
label: v.pipe(v.string(), v.nonEmpty()),
deadline: v.pipe(v.string(), v.nonEmpty()),
})
),
v.nonEmpty(),
v.maxLength(10)
),
});
```
##### FieldArray component
To dynamically generate the form fields for the todos, you use the `FieldArray` component in combination with Vue's `v-for` directive. The field array provides an `items` array that contains unique string identifiers which the `v-for` directive uses to detect when an item is added, moved, or removed.
```vue
```
##### Path array with index
As with nested fields, you use an array for the `path` property. The key difference is that you include the index from the `v-for` directive to specify which array item you're referencing. This ensures the paths update correctly when items are added, moved, or removed.
```vue
```
#### Use array methods
Now you can use the `insert`, `move`, `remove`, `replace`, and `swap` methods to make changes to the field array. These methods automatically take care of rearranging all the fields.
##### Insert method
Add a new item to the array:
```vue
```
The `at` option can be used to specify the index where the item should be inserted. If not provided, the item is added to the end of the array.
##### Remove method
Remove an item from the array:
```vue
```
##### Move method
Move an item from one position to another:
```vue
```
##### Swap method
Swap two items in the array:
```vue
```
##### Replace method
Replace an item with new data:
```vue
```
#### Nested field arrays
If you need to nest multiple field arrays, the path array syntax makes it straightforward. Simply extend the path with additional array indices:
```vue
```
You can nest field arrays as deeply as you like. You will also find a suitable example of this in our playground.
#### Field array validation
As with fields, you can validate field arrays using Valibot's array validation functions. For example, to limit the length of the array:
```tsx
const TodoFormSchema = v.object({
todos: v.pipe(
v.array(
v.object({
label: v.string(),
deadline: v.string(),
})
),
v.minLength(1),
v.maxLength(10)
),
});
```
The validation errors for the field array itself are available in `fieldArray.errors` and can be displayed alongside the array.
### TypeScript
Since the library is written in TypeScript and we put a lot of emphasis on the development experience, you can expect maximum TypeScript support. Types are automatically inferred from your Valibot schemas, providing type safety throughout your forms.
#### Type inference
Formisch uses Valibot's type inference to automatically derive TypeScript types from your schemas. You don't need to define separate types—they're inferred automatically.
```vue
```
##### Input and output types
Valibot schemas can have different input and output types when using transformations. Formisch provides proper typing for both.
```vue
```
##### Type-safe paths
Field paths are fully type-checked. TypeScript will provide autocompletion and catch invalid paths at compile time.
```ts
const UserSchema = v.object({
profile: v.object({
name: v.object({
first: v.string(),
last: v.string(),
}),
email: v.string(),
}),
});
const userForm = useForm({ schema: UserSchema });
// ✓ Valid paths - TypeScript provides autocompletion
// ✗ Invalid paths - TypeScript error
```
#### Type-safe props
To pass your form to another component via props, you can use the `FormStore` type along with your schema type to get full type safety.
```vue
```
#### Generic field components
You can create generic field components with proper TypeScript typing using the `FormStore` type with Valibot's `GenericSchema`.
```vue
{{ field.errors[0] }}
```
The `v.GenericSchema<{ email: string }>` type ensures that the form passed to `EmailInput` must have an `email` field of type `string`. TypeScript will catch any type mismatches at compile time.
#### Available types
Most types you need can be imported from `@formisch/vue`. You can find all available types in our API reference.
- `FormStore` - The form store type
- `FieldStore` - The field store type
- `FieldArrayStore` - The field
array store type
- `ValidPath` - Type for valid field
paths
- `ValidArrayPath` - Type for
valid array field paths
- `Schema` - Base schema type from Valibot
- `SubmitHandler` - Type for submit
handler functions
