# Formisch

> The lightweight, schema-first and fully type-safe form library for Angular, Preact, Qwik, React, React Native, Solid, Svelte and Vue.

## 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](/playground/login/)!

#### 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 – 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`](/vue/api/useForm.md) composable. It initializes your form's store based on the provided Valibot schema and infers its types. Next, wrap your form in the [`<Form />`](/vue/api/Form.md) component. It's a thin layer around the native `<form />` element that handles form validation and submission. Then, you can access the state of a field with the [`useField`](/vue/api/useField.md) composable or the [`<Field />`](/vue/api/Field.md) component to connect your inputs.

```vue
<script setup lang="ts">
import { Field, Form, useForm } from '@formisch/vue';
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 loginForm = useForm({
  schema: LoginSchema,
});
</script>

<template>
  <Form :of="loginForm" @submit="(output, event) => console.log(output)">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <div>
        <input v-model="field.input" v-bind="field.props" type="email" />
        <div v-if="field.errors">{{ field.errors[0] }}</div>
      </div>
    </Field>
    <Field :of="loginForm" :path="['password']" v-slot="field">
      <div>
        <input v-model="field.input" v-bind="field.props" type="password" />
        <div v-if="field.errors">{{ field.errors[0] }}</div>
      </div>
    </Field>
    <button type="submit">Login</button>
  </Form>
</template>
```

In addition, Formisch offers several functions (we call them "methods") that can be used to read and manipulate the form state. These include [`focus`](/methods/api/focus.md), [`getDeepErrorEntries`](/methods/api/getDeepErrorEntries.md), [`getDeepErrors`](/methods/api/getDeepErrors.md), [`getDirtyInput`](/methods/api/getDirtyInput.md), [`getDirtyPaths`](/methods/api/getDirtyPaths.md), [`getErrors`](/methods/api/getErrors.md), [`getInput`](/methods/api/getInput.md), [`handleSubmit`](/methods/api/handleSubmit.md), [`insert`](/methods/api/insert.md), [`isDirty`](/methods/api/isDirty.md), [`isEdited`](/methods/api/isEdited.md), [`isTouched`](/methods/api/isTouched.md), [`isValid`](/methods/api/isValid.md), [`move`](/methods/api/move.md), [`pickDirty`](/methods/api/pickDirty.md), [`remove`](/methods/api/remove.md), [`replace`](/methods/api/replace.md), [`reset`](/methods/api/reset.md), [`setErrors`](/methods/api/setErrors.md), [`setInput`](/methods/api/setInput.md), [`submit`](/methods/api/submit.md), [`swap`](/methods/api/swap.md) and [`validate`](/methods/api/validate.md). 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 VeeValidate, FormKit, and TanStack Form, see the [comparison guide](/vue/guides/comparison.md).

#### Vision

My vision for Formisch is to create a framework-agnostic platform similar to [Vite](https://vite.dev/), 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](https://github.com/open-circle/formisch/issues/new). Together we can make forms even better!

#### License

This project is available free of charge and licensed under the [MIT license](https://github.com/open-circle/formisch/blob/main/LICENSE.md).

### 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.

```jsonc
{
  "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/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';
```

#### 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 --skill formisch valibot
```

You can learn more about the Valibot and Formisch agent skill [here](https://github.com/open-circle/agent-skills).

### Coding agents

Formisch is built to be consumed by AI coding agents. This page describes the agent skill, MCP server and Markdown documentation we provide so that your AI tools generate correct Vue code with Formisch.

#### Agent skill

Formisch defines form values and validation with [Valibot](https://valibot.dev/) schemas, so an agent needs two skills: our [Formisch SKILL.md](https://github.com/open-circle/agent-skills/blob/main/skills/formisch/SKILL.md) for building forms and managing form state, and the [Valibot SKILL.md](https://github.com/open-circle/agent-skills/blob/main/skills/valibot/SKILL.md) for writing the schemas. Install both with the [Agent Skills CLI](https://agentskills.io/):

```bash
npx skills add open-circle/agent-skills --skill formisch valibot
```

The Formisch skill is also published at [`/.well-known/agent-skills/formisch/SKILL.md`](/.well-known/agent-skills/formisch/SKILL.md) and listed in our [discovery index](/.well-known/agent-skills/index.json). For Valibot's MCP server and llms.txt files, see [Valibot's coding agents guide](https://valibot.dev/guides/coding-agents/).

#### MCP server

We host a [Model Context Protocol](https://modelcontextprotocol.io/) server at `https://formisch.dev/mcp` that gives coding agents first-class tools to search and read the documentation instead of crawling pages. It is free and requires no authentication.

The server provides three tools:

- `search_docs` searches the documentation and returns the most relevant pages
- `get_doc` reads a documentation page or blog post as Markdown
- `list_docs` lists all pages grouped by framework and area

Add it to Claude Code with:

```bash
claude mcp add --transport http formisch https://formisch.dev/mcp
```

Or add it to the MCP configuration of your tool:

```jsonc
{
  "mcpServers": {
    "formisch": {
      "url": "https://formisch.dev/mcp",
    },
  },
}
```

The server metadata is available at [`/.well-known/mcp/server-card.json`](/.well-known/mcp/server-card.json).

#### LLMs.txt

We provide several [LLMs.txt](https://llmstxt.org/) files. Use the one 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
- [`llms-blog.txt`](/llms-blog.txt) contains the Markdown content of all blog posts

#### Markdown for agents

Every documentation page is available as Markdown. Append `.md` to the URL of a page (e.g. `/vue/guides/installation/` becomes [`/vue/guides/installation.md`](/vue/guides/installation.md)) or request the page with an `Accept: text/markdown` header to receive its Markdown version.

### Comparison

Formisch is one of several form libraries available for Vue. The three most common alternatives are [VeeValidate](https://vee-validate.logaretm.com), [FormKit](https://formkit.com), and [TanStack Form](https://tanstack.com/form/latest). This page is meant as a quick reference for picking the right tool.

#### At a glance

|                        | **Formisch**                                                   | VeeValidate                   | FormKit                               | TanStack Form                           |
| ---------------------- | -------------------------------------------------------------- | ----------------------------- | ------------------------------------- | --------------------------------------- |
| Type source            | Inferred from schema                                           | Inferred from schema          | Declared manually                     | Inferred from `defaultValues`           |
| Validation location    | Defined in schema                                              | Validator rules or schema     | Per-input prop or form schema         | Per-validator config                    |
| Validation timing      | Form-wide `validate` / `revalidate`                            | Per field, configurable       | Per input (`validation-visibility`)   | Per-validator trigger                   |
| Async validation       | Built-in via schema                                            | Built-in                      | Built-in                              | Built-in `isValidating`                 |
| Reactivity scope       | Per Vue ref subscription                                       | Per Vue ref subscription      | Per Vue ref subscription              | Per TanStack Store subscription         |
| Schema libraries       | Valibot                                                        | Zod, Yup, Valibot, ArkType, … | Built-in rules; schemas via plugins   | Standard Schema                         |
| UI approach            | Headless                                                       | Headless                      | Component-driven (batteries included) | Headless                                |
| Bundle size (min+gzip) | From ~2.5 kB                                                   | ~12 kB                        | ~25 kB+                               | ~15 kB                                  |
| Framework support      | Angular, React, React Native, Preact, Solid, Svelte, Vue, Qwik | Vue 3 (Vue 2 via legacy)      | Vue 3                                 | 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 reactivity.

#### 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-shakeable, 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?

**VeeValidate** is the most widely used Vue form library. It is headless, composables-based, and has strong schema support through Standard Schema. Good fit when you want a flexible logic layer and are comfortable wiring your own components.

**FormKit** is component-driven and batteries-included. Inputs, layouts, accessibility, and styling come out of the box, with optional declarative form schemas. Best when you want a complete form solution with UI rather than a headless logic layer.

**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. Reactivity is fine-grained through Vue 3's composition API. The main consideration is that Formisch currently supports only [Valibot](https://valibot.dev) as the schema library.

#### Migrating to Formisch

Migrating to Formisch is not a drop-in replacement, but the libraries can coexist in the same application, so you can migrate one form at a time. The main work is consolidating validation rules into a single root Valibot schema and replacing the previous library's form and field APIs with Formisch's composables.

We provide a dedicated migration guide for each library, with a side-by-side example, step-by-step instructions, and an API mapping table: [migrate from VeeValidate](/vue/guides/migrate-from-vee-validate.md), [migrate from FormKit](/vue/guides/migrate-from-formkit.md), and [migrate from TanStack Form](/vue/guides/migrate-from-tanstack-form.md).

#### Next steps

If you have decided that Formisch is a good fit, install it via the [installation](/vue/guides/installation.md) guide and start building by [defining your form](/vue/guides/define-your-form.md).

## 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`](/vue/api/useForm.md), 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](/playground/login/).

```ts
import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
});
```

##### Field order

The order in which you define fields in your schema matters. When a form is submitted with invalid values, Formisch focuses the first field with an error. Since this follows your schema, define your fields in the same order they appear in your form, so the focus moves to the first invalid field instead of one further down the page.

#### 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](/vue/guides/create-your-form.md) guide to learn how to initialize your form with [`useForm`](/vue/api/useForm.md).

### Create your form

Formisch consists of composables, components and methods. To create a form you use the [`useForm`](/vue/api/useForm.md) composable.

#### Form composable

The [`useForm`](/vue/api/useForm.md) 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
<script setup lang="ts">
import { Form, useForm } from '@formisch/vue';
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 loginForm = useForm({
  schema: LoginSchema,
});
</script>

<template>
  <Form :of="loginForm" @submit="(output) => console.log(output)">
    <!-- Form fields will go here -->
  </Form>
</template>
```

##### Configuration options

The [`useForm`](/vue/api/useForm.md) 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)
- `emptyInput`: The empty value each field type starts at when a required field has no initial input (optional, defaults to `{ string: '' }`)
- `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',
});
```

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`](/methods/api/setInput.md) to update the current input (client state), and use [`reset`](/methods/api/reset.md) to update the initial input (baseline) when your server data changes or is refreshed.

##### Empty input

By default, a required string field starts as an empty string (`''`) instead of `undefined`, matching an empty text input. This way an empty field shows the validation message you defined for it (for example from `v.nonEmpty()`) without you setting an `initialInput` for every field.

You can configure the empty value per field type, or opt out by setting a type to `undefined`:

```ts
const loginForm = useForm({
  schema: LoginSchema,
  emptyInput: {
    string: '', // the default
    number: 0, // required numbers start at 0 instead of undefined
    boolean: false, // checkboxes start unchecked
  },
});
```

Optional and nullable fields are never affected and keep starting as `undefined`, since they accept it. The supported types are `string`, `number`, `boolean` and `date`, and the default is `{ string: '' }`.

#### Multiple forms

When a page contains multiple forms, you can create separate form stores for each one:

```vue
<script setup lang="ts">
import { Form, useForm } from '@formisch/vue';
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)),
});

const loginForm = useForm({ schema: LoginSchema });
const registerForm = useForm({ schema: RegisterSchema });
</script>

<template>
  <Form :of="loginForm" @submit="(output) => console.log(output)">
    <!-- … -->
  </Form>
  <Form :of="registerForm" @submit="(output) => console.log(output)">
    <!-- … -->
  </Form>
</template>
```

If you need a multi-step form (wizard), see the [multi-step form discussion](https://github.com/open-circle/formisch/discussions/108) for patterns and approaches.

#### Next steps

Now that you know how to create a form, continue to the [add form fields](/vue/guides/add-form-fields.md) guide to learn how to connect your input elements to the form using the [`Field`](/vue/api/Field.md) component.

### Add form fields

To add a field to your form, you can use the [`Field`](/vue/api/Field.md) component or the [`useField`](/vue/api/useField.md) composable. Both are headless and provide access to field state for building your form UI.

#### Field component

The [`Field`](/vue/api/Field.md) 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
<script setup lang="ts">
import { Field, Form, useForm } from '@formisch/vue';
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 loginForm = useForm({
  schema: LoginSchema,
});
</script>

<template>
  <Form :of="loginForm" @submit="(output) => console.log(output)">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <input v-model="field.input" v-bind="field.props" type="email" />
    </Field>
    <Field :of="loginForm" :path="['password']" v-slot="field">
      <input v-model="field.input" v-bind="field.props" type="password" />
    </Field>
    <button type="submit">Login</button>
  </Form>
</template>
```

> **Important:** If you plan to set initial values with `initialInput` or programmatically control field values using methods like [`setInput`](/methods/api/setInput.md) or [`reset`](/methods/api/reset.md), you must make your fields controlled by setting the appropriate attributes (like `v-model`, `checked`, or `selected`). See the [controlled fields](/vue/guides/controlled-fields.md) guide to learn more.

##### Headless design

The [`Field`](/vue/api/Field.md) 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
<Field :of="loginForm" :path="['email']" v-slot="field">
  <input v-model="field.input" v-bind="field.props" type="email" />
</Field>
```

For nested fields, the path reflects the structure of your schema:

```vue
<!-- For a schema like: v.object({ user: v.object({ email: v.string() }) }) -->
<Field :of="form" :path="['user', 'email']" v-slot="field">
  <input v-model="field.input" v-bind="field.props" type="email" />
</Field>
```

##### Type safety

The API design of the [`Field`](/vue/api/Field.md) 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`](/vue/api/useField.md) composable. It allows you to access the field state directly within your component logic.

```vue
<script setup lang="ts">
import { useField } from '@formisch/vue';
import type { FormStore } from '@formisch/vue';
import * as v from 'valibot';

type EmailInputProps = {
  form: FormStore<v.GenericSchema<{ email: string }>>;
};

const props = defineProps<EmailInputProps>();

const field = useField(
  () => props.form,
  () => ({ path: ['email'] })
);
</script>

<template>
  <div>
    <input v-model="field.input" v-bind="field.props" type="email" />
    <div v-if="field.errors">{{ field.errors[0] }}</div>
  </div>
</template>
```

##### 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`](/vue/api/Field.md) component is essentially a thin wrapper around [`useField`](/vue/api/useField.md) that allows you to access the field state within template code.

#### Field store

The field store provides access to the following properties:

- `path`: The path to the field within the form.
- `props`: 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.
- `isEdited`: Whether the field's value has been changed.
- `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](/vue/guides/input-components.md) 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](/playground/login/) as a starting point. You can find the code in our GitHub repository [here](https://github.com/open-circle/formisch/tree/main/playgrounds/vue/src/components).

#### Why input components?

Currently, your fields might look something like this:

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <div>
      <label :for="field.props.name">Email</label>
      <input
        v-bind="field.props"
        :id="field.props.name"
        v-model="field.input"
        type="email"
        required
      />
      <div v-if="field.errors">{{ field.errors[0] }}</div>
    </div>
  </Field>
</template>
```

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
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <TextInput
      v-model="field.input"
      :props="field.props"
      type="email"
      label="Email"
      :errors="field.errors"
      required
    />
  </Field>
</template>
```

#### 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
<script setup lang="ts">
import type { FieldElementProps } from '@formisch/vue';

interface TextInputProps {
  type: 'text' | 'email' | 'tel' | 'password' | 'url' | 'number' | 'date';
  label?: string;
  placeholder?: string;
  required?: boolean;
  errors: [string, ...string[]] | null;
  props: FieldElementProps;
}

const props = defineProps<TextInputProps>();
const model = defineModel<string | number | undefined>({ required: true });
</script>
```

##### Template code

After that, you can add the template code.

```vue
<template>
  <div>
    <label v-if="label" :for="props.props.name">
      {{ label }} <span v-if="required">*</span>
    </label>
    <input
      v-model="model"
      v-bind="props.props"
      :id="props.props.name"
      :type="type"
      :placeholder="placeholder"
      :required="required"
      :aria-invalid="!!errors"
      :aria-errormessage="`${props.props.name}-error`"
    />
    <div v-if="errors" :id="`${props.props.name}-error`">{{ errors[0] }}</div>
  </div>
</template>
```

##### 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
<script setup lang="ts">
import type { FieldElementProps } from '@formisch/vue';

interface TextInputProps {
  type: 'text' | 'email' | 'tel' | 'password' | 'url' | 'number' | 'date';
  label?: string;
  placeholder?: string;
  required?: boolean;
  errors: [string, ...string[]] | null;
  props: FieldElementProps;
}

const props = defineProps<TextInputProps>();
const model = defineModel<string | number | undefined>({ required: true });
</script>

<template>
  <div>
    <label v-if="label" :for="props.props.name">
      {{ label }} <span v-if="required">*</span>
    </label>
    <input
      v-model="model"
      v-bind="props.props"
      :id="props.props.name"
      :type="type"
      :placeholder="placeholder"
      :required="required"
      :aria-invalid="!!errors"
      :aria-errormessage="`${props.props.name}-error`"
    />
    <div v-if="errors" :id="`${props.props.name}-error`">{{ errors[0] }}</div>
  </div>
</template>
```

#### Using component libraries

Component libraries render their own components instead of plain elements, so you cannot use `v-bind="field.props"` on them. Vue treats the `ref` entry inside that object as a real template ref, which would register the component instance rather than a DOM element. Bind the entries individually and set the value through `v-model`:

```vue
<template>
  <Field :of="form" :path="['date']" v-slot="field">
    <DatePicker
      :ref="(instance) => field.props.ref(instance?.$el ?? instance)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      v-model="field.input"
      @focus="field.props.onFocus"
      @blur="field.props.onBlur"
    />
  </Field>
</template>
```

Assigning `field.input` updates the field value and triggers validation, while the focus handler is what marks the field as touched. Unwrapping `$el` only helps when the component's root is the focusable element; if it wraps its control in a container, reach for the library's own input ref instead, or accept that [`focus`](/methods/api/focus.md) cannot target that field. For more details, see the [controlled fields](/vue/guides/controlled-fields.md) guide.

For ready-made wiring recipes, check out our integration guides:

- [shadcn-vue](/vue/guides/shadcn-vue.md)
- [Ark UI](/vue/guides/ark-ui.md)
- [Reka UI](/vue/guides/reka-ui.md)
- [PrimeVue](/vue/guides/primevue.md)

#### Next steps

Now that you know how to create reusable input components, continue to the [handle submission](/vue/guides/handle-submission.md) guide to learn how to process form data when the user submits the form.

### Handle submission

Your first form is almost ready. The remaining step is processing its data 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`](/vue/api/Form.md) component. The first parameter passed to the function contains the validated form values.

```vue
<script setup lang="ts">
import { Field, Form, useForm } from '@formisch/vue';
import type { SubmitHandler } from '@formisch/vue';
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 loginForm = useForm({
  schema: LoginSchema,
});

const submitForm: SubmitHandler<typeof LoginSchema> = (values) => {
  // Process the validated form values
  console.log(values); // { email: string, password: string }
};
</script>

<template>
  <Form :of="loginForm" @submit="submitForm">
    <!-- Form fields will go here -->
  </Form>
</template>
```

The [`SubmitHandler`](/core/api/SubmitHandler.md) 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`](/core/api/SubmitEventHandler.md) 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:

```vue
<button type="submit" :disabled="loginForm.isSubmitting">
  {{ loginForm.isSubmitting ? 'Submitting...' : 'Login' }}
</button>
```

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 [`getDeepErrors`](/methods/api/getDeepErrors.md) method.

##### Async submission

The submit handler can be asynchronous, allowing you to perform API calls or other async operations:

```ts
const submitForm: SubmitHandler<typeof LoginSchema> = 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`](/methods/api/submit.md) method. It calls `requestSubmit()` on the underlying form element:

```vue
<script setup lang="ts">
import { submit } from '@formisch/vue';
</script>

<template>
  <button type="button" @click="submit(loginForm)">Submit from outside</button>
</template>
```

#### Submit without \<form /\>

In some cases, you may not be able to wrap your fields in a `<form>` element — for example, when your form is rendered inside another form, since nesting `<form>` elements is invalid HTML. In these situations, you can use the [`handleSubmit`](/methods/api/handleSubmit.md) method directly to submit the form programmatically without the [`Form`](/vue/api/Form.md) component.

The returned function accepts no arguments and can be called from anywhere — for example, from a button's `@click` handler:

```vue
<script setup lang="ts">
import { Field, handleSubmit, useForm } from '@formisch/vue';
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 loginForm = useForm({
  schema: LoginSchema,
});

const submitForm = handleSubmit(loginForm, (values) => {
  // Process the validated form values
  console.log(values);
});
</script>

<template>
  <div>
    <!-- Form fields without a <Form /> wrapper -->
    <button type="button" @click="submitForm">Login</button>
  </div>
</template>
```

#### 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](/vue/guides/form-methods.md) 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`](/methods/api/getInput.md): Get the current value
  of a specific field
- [`getErrors`](/methods/api/getErrors.md): Get error messages
  for a specific field
- [`getDeepError`](/methods/api/getDeepError.md): Get the first
  error message within a field or the form
- [`getDeepErrors`](/methods/api/getDeepErrors.md): Get all error
  messages across the entire form
- [`getDeepErrorEntry`](/methods/api/getDeepErrorEntry.md): Get
  the error messages of the first erroring field paired with its path
- [`getDeepErrorEntries`](/methods/api/getDeepErrorEntries.md):
  Get all error messages paired with the path of the field they belong to

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.

#### Field state

To check the state of a single field or of the entire form, use:

- [`isTouched`](/methods/api/isTouched.md): Whether the field or
  form has been touched
- [`isEdited`](/methods/api/isEdited.md): Whether the field or
  form has been edited
- [`isDirty`](/methods/api/isDirty.md): Whether the field or form
  differs from its initial input
- [`isValid`](/methods/api/isValid.md): Whether the field or form
  has no validation errors

Each of these takes an optional `path` to scope the check to a single field. Without it, they walk the entire form.

#### Dirty state

To work with the dirty state of your form, Formisch provides three methods:

- [`getDirtyInput`](/methods/api/getDirtyInput.md): Get the dirty
  parts of the form input
- [`getDirtyPaths`](/methods/api/getDirtyPaths.md): Get the paths
  of dirty fields
- [`pickDirty`](/methods/api/pickDirty.md): Filter an
  externally-supplied value down to its dirty parts using the form's dirty mask

See the [dirty fields](/vue/guides/dirty-fields.md) guide for when to reach for each.

#### Setting values

To manually update form values or errors, use:

- [`setInput`](/methods/api/setInput.md): Manually update the
  value of a specific field
- [`setErrors`](/methods/api/setErrors.md): Manually set error
  messages for a specific field

> If you need to update the form because the initial data has changed (e.g., remote data was refreshed), use [`reset`](/methods/api/reset.md) with a new `initialInput` instead of `setInput`. The `reset` method properly reinitializes the form state, while `setInput` only changes the current input values without updating the initial state.

#### Form control

To control the form programmatically, use:

- [`handleSubmit`](/methods/api/handleSubmit.md): Create a submit
  event handler that validates the form and calls your handler on success
- [`reset`](/methods/api/reset.md): Reset the form to its initial
  state or update initial values
- [`validate`](/methods/api/validate.md): Manually trigger
  validation of the entire form
- [`submit`](/methods/api/submit.md): Programmatically trigger
  form submission
- [`focus`](/methods/api/focus.md): Focus on a specific field

#### Array operations

For working with field arrays, Formisch provides:

- [`insert`](/methods/api/insert.md): Insert a new item into a
  field array
- [`remove`](/methods/api/remove.md): Remove an item from a field
  array
- [`move`](/methods/api/move.md): Move an item to a different
  position in a field array
- [`swap`](/methods/api/swap.md): Swap two items in a field array
- [`replace`](/methods/api/replace.md): 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:

```ts
// 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](/vue/api/).

## Advanced guides

### Validation

Formisch validates your form against your Valibot schema — the same one that defines its types. This guide explains how validation runs under the hood, how the `validate` and `revalidate` config control its timing, how to display errors only when they are helpful, and how to react to asynchronous validation with `isValidating`.

#### How validation works

Whenever validation is triggered, Formisch parses the **entire form** against your schema in a single pass. It then distributes the resulting issues to the individual fields: every field with an issue receives its error messages, and every field without one is cleared. A field is valid when it has no errors.

> Validation always runs against the whole schema, even when a single field triggers it. This keeps cross-field rules (like a `password` and `confirmPassword` that must match) correct without any extra wiring. The result is still stored per field, so each `<input />` only re-renders when its own errors change.

Because Formisch parses with Valibot's asynchronous API, schemas with async checks (for example, a server-side uniqueness check) work out of the box. While such a check is in flight, the form's `isValidating` state is `true` (see [below](#validating-state)).

#### When validation runs

Two config options control the timing of validation:

- `validate`: when a field is validated for the **first** time. Defaults to `'submit'`.
- `revalidate`: when a field is validated **again**, once it already has an error or the form has been submitted. Defaults to `'input'`.

Both accept the following modes:

- `'initial'`: immediately, when the form is created (only valid for `validate`, not `revalidate`).
- `'touch'`: when the field is first focused.
- `'input'`: on every keystroke.
- `'change'`: on the field's change event.
- `'blur'`: when the field loses focus.
- `'submit'`: only when the form is submitted.

```ts
const loginForm = useForm({
  schema: LoginSchema,
  validate: 'blur',
  revalidate: 'input',
});
```

The split between `validate` and `revalidate` is what makes good defaults possible. With the default `validate: 'submit'` and `revalidate: 'input'`, a field stays quiet until the user submits, and only then does it start correcting itself live as the user fixes it. The configuration above (`validate: 'blur'`) is a gentler variant: a field is first checked when the user leaves it, then re-checked on every keystroke once it has an error.

#### Showing errors at the right time

`validate` and `revalidate` control **when validation runs** — but not **when errors are shown**. After a validation pass, every invalid field has its `errors` populated, and it is up to you to decide which ones to render.

Showing every error the moment it appears can overwhelm the user, while showing them only after submit forces them to scroll back and fix fields they have already filled out. A balanced approach is to reveal a field's error once the user has actually changed it, and to reveal all remaining errors after the first submit attempt.

Each field exposes several state flags to drive this decision:

- `isTouched`: the field has been focused or changed.
- `isEdited`: the field's value has been changed (but not merely focused), and stays `true` even if the value is changed back to its initial value.
- `isDirty`: the field's current value differs from its initial value.

The form additionally exposes `isSubmitted`, which becomes `true` after the first submit attempt. Combining `isEdited` with `isSubmitted` gives the balanced behavior described above:

```vue
<script setup lang="ts">
import { Field, Form, useForm } from '@formisch/vue';
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 loginForm = useForm({
  schema: LoginSchema,
  validate: 'change',
});
</script>

<template>
  <Form :of="loginForm" @submit="(output) => console.log(output)">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <input v-model="field.input" v-bind="field.props" type="email" />
      <div v-if="(field.isEdited || loginForm.isSubmitted) && field.errors">
        {{ field.errors[0] }}
      </div>
    </Field>
    <button type="submit">Login</button>
  </Form>
</template>
```

`isEdited` is the right flag for this. `isTouched` would reveal the error as soon as the user tabs through a field without changing it, and `isDirty` would hide the error again if the user clears an invalid value back to its initial state. `isEdited` avoids both: it turns on only after a real change and stays on. Pair it with `validate: 'input'` (or `'change'`) so the error appears as soon as the field becomes invalid, and with `isSubmitted` so that the errors of all fields — including the ones the user never touched — become visible after a submit attempt.

##### Reuse the guard across fields

Writing this guard at every field gets repetitive. The common fix is to move it into a small reusable component, either on its own or folded into the `TextInput` from the [input components](/vue/guides/input-components.md) guide, so the `isEdited || isSubmitted` logic lives in exactly one place:

```vue
<script setup lang="ts">
interface FieldErrorProps {
  errors: [string, ...string[]] | null;
  isEdited: boolean;
  isSubmitted: boolean;
}

defineProps<FieldErrorProps>();
</script>

<template>
  <div v-if="errors && (isEdited || isSubmitted)">{{ errors[0] }}</div>
</template>
```

Each field then stays focused on its input:

```vue
<Field :of="loginForm" :path="['email']" v-slot="field">
  <input v-model="field.input" v-bind="field.props" type="email" />
  <FieldError
    :errors="field.errors"
    :is-edited="field.isEdited"
    :is-submitted="loginForm.isSubmitted"
  />
</Field>
```

#### Validating state

When your schema contains asynchronous checks, validation does not resolve instantly. The form's `isValidating` state is `true` while any validation is in flight, which you can use to show a loading indicator or to disable the submit button until validation settles.

```vue
<script setup lang="ts">
import { Form, useForm } from '@formisch/vue';
import * as v from 'valibot';
import { isUsernameAvailable } from '~/api';

const SignUpSchema = v.objectAsync({
  username: v.pipeAsync(
    v.string(),
    v.nonEmpty(),
    v.checkAsync(isUsernameAvailable, 'Username is already taken.')
  ),
});

const signUpForm = useForm({
  schema: SignUpSchema,
  validate: 'blur',
});
</script>

<template>
  <Form :of="signUpForm" @submit="(output) => console.log(output)">
    <!-- fields -->
    <button type="submit" :disabled="signUpForm.isValidating">
      {{ signUpForm.isValidating ? 'Checking...' : 'Sign up' }}
    </button>
  </Form>
</template>
```

`isValidating` and `isSubmitting` overlap but are not the same. `isValidating` is `true` whenever validation runs — triggered by a field event or as part of a submit. `isSubmitting` is `true` for the entire submission, which covers both validating the form and running your submit handler. So during a submit both are `true` while the form validates, and once validation passes only `isSubmitting` stays `true` while your handler runs.

#### Further reading

To process your form's values once they pass validation, see the [handle submission](/vue/guides/handle-submission.md) guide. For working with the fields a user has changed, see the [dirty fields](/vue/guides/dirty-fields.md) guide.

### Special inputs

As listed in our features, the library supports all native HTML form fields. This includes the HTML `<select />` element as well as special cases of the `<input />` element.

> In our [playground](/playground/special/) 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
<template>
  <Field :of="form" :path="['cookies']" v-slot="field">
    <label>
      <input type="checkbox" v-bind="field.props" v-model="field.input" />
      Yes, I want cookies
    </label>
  </Field>
</template>
```

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 `<input />` element.

```vue
<template>
  <Field :of="form" :path="['fruits']" v-slot="field">
    <label
      v-for="fruit in [
        { label: 'Bananas', value: 'bananas' },
        { label: 'Apples', value: 'apples' },
        { label: 'Grapes', value: 'grapes' },
      ]"
      :key="fruit.value"
    >
      <input
        type="checkbox"
        :value="fruit.value"
        v-bind="field.props"
        v-model="field.input"
      />
      {{ fruit.label }}
    </label>
  </Field>
</template>
```

#### Radio

A group of radio buttons, while similar to an array of checkboxes, will only allow you to select one of the options based on which button is checked.

```vue
<template>
  <Field :of="form" :path="['color']" v-slot="field">
    <label
      v-for="color in [
        { label: 'Red', value: 'red' },
        { label: 'Green', value: 'green' },
        { label: 'Blue', value: 'blue' },
      ]"
      :key="color.value"
    >
      <input
        type="radio"
        :value="color.value"
        v-bind="field.props"
        v-model="field.input"
      />
      {{ color.label }}
    </label>
  </Field>
</template>
```

#### Select

An HTML `<select />` element allows you to select a string from a predefined list of options.

```vue
<template>
  <Field :of="form" :path="['framework']" v-slot="field">
    <select v-bind="field.props" v-model="field.input">
      <option
        v-for="option in [
          { label: 'Preact', value: 'preact' },
          { label: 'Solid', value: 'solid' },
          { label: 'Qwik', value: 'qwik' },
        ]"
        :key="option.value"
        :value="option.value"
      >
        {{ option.label }}
      </option>
    </select>
  </Field>
</template>
```

However, if you set the `multiple` attribute, multiple options can be selected making the field represent an array of strings.

```vue
<template>
  <Field :of="form" :path="['frameworks']" v-slot="field">
    <select multiple v-bind="field.props" v-model="field.input">
      <option
        v-for="option in [
          { label: 'Preact', value: 'preact' },
          { label: 'Solid', value: 'solid' },
          { label: 'Qwik', value: 'qwik' },
        ]"
        :key="option.value"
        :value="option.value"
      >
        {{ option.label }}
      </option>
    </select>
  </Field>
</template>
```

#### File

An HTML `<input type="file" />` works similarly to an HTML `<select />` element. Without the `multiple` attribute, it represents a single file; with `multiple`, it represents a list of files. Since Vue does not allow `v-model` on file inputs, capture the selection with an `@input` handler and assign it to `field.input`:

```vue
<template>
  <Field :of="form" :path="['avatar']" v-slot="field">
    <input
      v-bind="field.props"
      type="file"
      accept="image/*"
      @input="field.input = ($event.target as HTMLInputElement).files?.[0]"
    />
  </Field>
</template>
```

With the `multiple` attribute, users can select multiple files:

```vue
<template>
  <Field :of="form" :path="['documents']" v-slot="field">
    <input
      v-bind="field.props"
      type="file"
      multiple
      @input="
        field.input = Array.from(($event.target as HTMLInputElement).files ?? [])
      "
    />
  </Field>
</template>
```

### 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`](/methods/api/setInput.md), 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 a text input you simply add the `v-model` directive:

```vue
<template>
  <Field :of="loginForm" :path="['firstName']" v-slot="field">
    <input v-model="field.input" v-bind="field.props" type="text" />
  </Field>
</template>
```

#### Numbers and dates

In Vue you don't wire up an input handler — `v-model` reads and writes the value through the `field.input` setter. That makes numbers and dates mostly automatic.

##### Number inputs

For `<input type="number" />`, the `.number` modifier converts the value to a real number that matches a `v.number()` schema. Vue applies it automatically for number inputs, but you can also add it explicitly:

```vue
<template>
  <Field :of="form" :path="['age']" v-slot="field">
    <input v-model.number="field.input" v-bind="field.props" type="number" />
  </Field>
</template>
```

##### Date inputs

An `<input type="date" />` exposes its value as a `yyyy-mm-dd` string, which `v-model` stores as-is. This pairs directly with a `v.string()` schema:

```vue
<template>
  <Field :of="form" :path="['birthday']" v-slot="field">
    <input v-model="field.input" v-bind="field.props" type="date" />
  </Field>
</template>
```

If your schema expects a real `Date` (`v.date()`), Vue has no modifier for this, so convert in both directions yourself:

```vue
<script setup lang="ts">
function parseDate(event: Event) {
  return (event.target as HTMLInputElement).valueAsDate ?? undefined;
}
</script>

<template>
  <Field :of="form" :path="['birthday']" v-slot="field">
    <input
      v-bind="field.props"
      type="date"
      :value="field.input?.toISOString().split('T', 1)[0] ?? ''"
      @input="field.input = parseDate($event)"
    />
  </Field>
</template>
```

#### Checkboxes

For checkboxes, you bind the value with `v-model`, which handles both boolean and array values automatically:

**Single checkbox** (boolean):

```vue
<template>
  <Field :of="form" :path="['acceptTerms']" v-slot="field">
    <input type="checkbox" v-bind="field.props" v-model="field.input" />
  </Field>
</template>
```

**Multiple checkboxes** (array of strings):

```vue
<template>
  <Field :of="form" :path="['interests']" v-slot="field">
    <label v-for="option in options" :key="option.value">
      <input
        type="checkbox"
        :value="option.value"
        v-bind="field.props"
        v-model="field.input"
      />
      {{ option.label }}
    </label>
  </Field>
</template>
```

#### Select elements

For select elements, you control the value with `v-model`:

**Single select**:

```vue
<template>
  <Field :of="form" :path="['country']" v-slot="field">
    <select v-bind="field.props" v-model="field.input">
      <option
        v-for="option in options"
        :key="option.value"
        :value="option.value"
      >
        {{ option.label }}
      </option>
    </select>
  </Field>
</template>
```

**Multiple select**:

```vue
<template>
  <Field :of="form" :path="['languages']" v-slot="field">
    <select multiple v-bind="field.props" v-model="field.input">
      <option
        v-for="option in options"
        :key="option.value"
        :value="option.value"
      >
        {{ option.label }}
      </option>
    </select>
  </Field>
</template>
```

#### File inputs

The HTML `<input type="file" />` 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`](https://github.com/open-circle/formisch/blob/main/playgrounds/vue/src/components/FileInput.vue) component from the [playground](/playground/special/).

#### Custom inputs and component libraries

Component libraries don't expose their underlying native element, so `v-bind="field.props"` does not work on them. Vue treats the `ref` entry inside that object as a real template ref, which would register the component instance instead of a DOM element. Bind the entries individually and let `v-model` write the value:

```vue
<template>
  <Field :of="form" :path="['date']" v-slot="field">
    <DatePicker
      :ref="(instance) => field.props.ref(instance?.$el ?? instance)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      v-model="field.input"
      @focus="field.props.onFocus"
      @blur="field.props.onBlur"
    />
  </Field>
</template>
```

This is useful for:

- **Component libraries** that wrap native elements without exposing them
- **Complex custom inputs** like date pickers, rich text editors, or color pickers

Assigning `field.input` updates the field value and triggers validation, just like a native input would. Registering the element keeps [`focus`](/methods/api/focus.md) working, and the focus handler is what marks the field as touched. Unwrapping `$el` only helps when the component's root is the focusable element; if it wraps its control in a container, reach for the library's own input ref instead.

For ready-made wiring recipes, check out our integration guides:

- [shadcn-vue](/vue/guides/shadcn-vue.md)
- [Ark UI](/vue/guides/ark-ui.md)
- [Reka UI](/vue/guides/reka-ui.md)
- [PrimeVue](/vue/guides/primevue.md)

#### Next steps

Now that you understand controlled fields, you can explore more advanced topics like [nested fields](/vue/guides/nested-fields.md) and [field arrays](/vue/guides/field-arrays.md) 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`.

```ts
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
<template>
  <Field :of="contactForm" :path="['name', 'first']" v-slot="field">
    <input v-bind="field.props" v-model="field.input" type="text" />
  </Field>
</template>
```

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
<script setup lang="ts">
import * as v from 'valibot';

const ProfileSchema = v.object({
  user: v.object({
    address: v.object({
      street: v.string(),
      city: v.string(),
      country: v.string(),
    }),
  }),
});
</script>

<template>
  <!-- Access deeply nested field -->
  <Field :of="profileForm" :path="['user', 'address', 'city']" v-slot="field">
    <input v-bind="field.props" v-model="field.input" type="text" />
  </Field>
</template>
```

#### 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.

### Dirty fields

When a user edits a form, Formisch tracks which fields have changed since they were initialized. The library exposes three methods for working with that dirty state: [`getDirtyInput`](/methods/api/getDirtyInput.md), [`getDirtyPaths`](/methods/api/getDirtyPaths.md), and [`pickDirty`](/methods/api/pickDirty.md). This guide explains what each one is for, when to reach for it, and why `pickDirty` exists alongside the others.

#### What "dirty" means

A field is dirty when its current input differs from its start input. The form starts clean. As the user types, only the fields they touch flip to dirty. Resetting a field (or resetting the form with a new `initialInput`) clears the dirty flag.

> The dirty flag is per-field. Editing a deeply nested value does not flip its ancestors' flags. The dirty-extraction methods walk the tree internally to find dirty descendants, which is why all three methods do the same kind of work under the hood.

#### The three methods

##### `getDirtyInput`

Returns the dirty subtree of the form's input. Use it when you want to ship the values the user typed — typically for a PATCH endpoint that accepts the same shape as your form input.

```ts
import { getDirtyInput, type SubmitHandler, useForm } from '@formisch/vue';
import * as v from 'valibot';

const UserSchema = v.object({
  name: v.pipe(v.string(), v.nonEmpty()),
  email: v.pipe(v.string(), v.email()),
});

const props = defineProps<{ user: User }>();

const profileForm = useForm({
  schema: UserSchema,
  initialInput: props.user,
});

const onSubmit: SubmitHandler<typeof UserSchema> = async () => {
  const dirty = getDirtyInput(profileForm);
  if (dirty) {
    await api.patchUser(props.user.id, dirty);
  }
};
```

If only `email` was edited, `dirty` is `{ email: 'new@example.com' }`. If nothing was edited, it is `undefined`.

Because dirty state is bound to the form input, `getDirtyInput` always returns the raw user input. Schema transformations such as `v.trim()` or `v.toNumber()` are not applied to the returned values. When you need the validated and transformed output instead, reach for `pickDirty` (see [below](#why-pickdirty-exists)).

##### `getDirtyPaths`

Returns a list of paths to dirty fields. Use it for logging, telemetry, or driving a custom walker over the form's dirty state.

```ts
import { getDirtyPaths } from '@formisch/vue';

const dirtyPaths = getDirtyPaths(profileForm);
// e.g. [['email'], ['user', 'name']]
```

Arrays are atomic: only the array's own path is returned, never the paths of individual items.

##### `pickDirty`

Filters a user-supplied value down to its dirty parts using the form's dirty mask. Use it when you have a separately-derived value — most commonly the validated and transformed output from a submit handler — and you want only its dirty parts.

```ts
import { pickDirty, type SubmitHandler } from '@formisch/vue';

const onSubmit: SubmitHandler<typeof UserSchema> = async (output) => {
  const dirty = pickDirty(profileForm, { from: output });
  if (dirty) {
    await api.update(dirty);
  }
};
```

#### Why `pickDirty` exists

Dirty state is tracked against the form **input** — the raw values the user typed. But Valibot schemas can transform that input into a different output shape before it reaches your submit handler:

```ts
import * as v from 'valibot';

const Schema = v.object({
  name: v.pipe(v.string(), v.trim()),
  age: v.pipe(v.string(), v.toNumber()),
});
```

After validation, `output.name` has whitespace trimmed and `output.age` is a number. [`getDirtyInput`](/methods/api/getDirtyInput.md) would give you the raw strings, because the dirty state is bound to the form input — not to the validated output.

[`pickDirty(form, { from: output })`](/methods/api/pickDirty.md) is the bridge: it walks the form's dirty tree as a structural mask and reads the corresponding values from the output you supply. The result preserves the transformed types.

```ts
import { pickDirty, type SubmitHandler } from '@formisch/vue';

const onSubmit: SubmitHandler<typeof Schema> = async (output) => {
  // output.age is a number — pickDirty preserves that.
  const dirty = pickDirty(form, { from: output });
  if (dirty) {
    await api.update(dirty);
  }
};
```

If the schema reshapes the output entirely — for example, by combining several input fields into a single output value — `pickDirty` returns `undefined` because the shape no longer aligns with the form's input shape.

#### Atomic arrays

All three methods treat arrays as atomic. When any descendant of an array is dirty, the full array is returned (or its own path, for `getDirtyPaths`). The methods never produce sparse arrays.

Sparse arrays don't round-trip safely. Serializers compact them, `JSON.stringify` writes `null` for holes, and indices lose positional meaning. Returning the full current array preserves order and lets the server treat the array as a complete replacement.

This differs from objects, where clean keys are omitted. Objects model keyed dictionaries; arrays model ordered sequences.

#### Common patterns

The snippets below assume `form` is your form store (the result of [`useForm`](/vue/api/useForm.md)).

##### Skip submission when nothing changed

The form's `isDirty` flag is the cheapest way to ask "is anything dirty?" — it short-circuits on the first dirty field it finds and doesn't allocate. Use it when all you need is the yes/no answer. If you actually consume the output of `getDirtyInput`, `getDirtyPaths`, or `pickDirty`, call that method directly — its return value already signals "nothing dirty", so checking `form.isDirty` first would just walk the tree twice.

```ts
import type { SubmitHandler } from '@formisch/vue';

const onSubmit: SubmitHandler<typeof Schema> = async (output) => {
  if (!form.isDirty) {
    return;
  }
  await api.update(output);
};
```

##### Send only the dirty raw input

```ts
import { getDirtyInput } from '@formisch/vue';

const dirty = getDirtyInput(form);
if (dirty) {
  await api.patch(dirty);
}
```

##### Send only the dirty validated output

```ts
import { pickDirty, type SubmitHandler } from '@formisch/vue';

const onSubmit: SubmitHandler<typeof Schema> = async (output) => {
  const dirty = pickDirty(form, { from: output });
  if (dirty) {
    await api.update(dirty);
  }
};
```

#### Performance

All three methods walk the form's field tree and call `getFieldBool` recursively to skip clean subtrees. Cost is effectively linear in field count for typical balanced forms (shallow and wide) and degrades toward `O(N²)` for deeply nested trees with few siblings at each level.

Call these methods from submit or blur handlers — not from tight reactive loops on every keystroke. For very large or deeply nested forms (thousands of fields), profile before binding them to high-frequency events.

### Field arrays

Dynamically generating form fields from an array introduces additional challenges when items are added, removed, swapped, or moved. Formisch provides the [`FieldArray`](/vue/api/FieldArray.md) component, which works with its array methods to make these forms straightforward.

> In our [playground](/playground/todos/) you can take a look at a form with a field array and test it out.

#### Create a field array

##### Schema definition

In the following example we create a field array for a todo form with the following schema:

```ts
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`](/vue/api/FieldArray.md) 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
<script setup lang="ts">
import { Field, FieldArray, Form, useForm } from '@formisch/vue';
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)
  ),
});

const todoForm = useForm({
  schema: TodoFormSchema,
  initialInput: {
    heading: '',
    todos: [{ label: '', deadline: '' }],
  },
});
</script>

<template>
  <Form :of="todoForm" @submit="(output, event) => console.log(output)">
    <Field :of="todoForm" :path="['heading']" v-slot="field">
      <input v-bind="field.props" v-model="field.input" type="text" />
      <div v-if="field.errors">{{ field.errors[0] }}</div>
    </Field>

    <FieldArray :of="todoForm" :path="['todos']" v-slot="fieldArray">
      <div>
        <div v-for="(item, index) in fieldArray.items" :key="item">
          <Field
            :of="todoForm"
            :path="['todos', index, 'label']"
            v-slot="field"
          >
            <input v-bind="field.props" v-model="field.input" type="text" />
            <div v-if="field.errors">{{ field.errors[0] }}</div>
          </Field>

          <Field
            :of="todoForm"
            :path="['todos', index, 'deadline']"
            v-slot="field"
          >
            <input v-bind="field.props" v-model="field.input" type="date" />
            <div v-if="field.errors">{{ field.errors[0] }}</div>
          </Field>
        </div>
        <div v-if="fieldArray.errors">{{ fieldArray.errors[0] }}</div>
      </div>
    </FieldArray>

    <button type="submit">Submit</button>
  </Form>
</template>
```

##### Path array with index

As with [nested fields](/vue/guides/nested-fields.md), 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
<template>
  <Field :of="todoForm" :path="['todos', index, 'label']" v-slot="field">
    <input v-bind="field.props" v-model="field.input" type="text" />
  </Field>
</template>
```

#### Use array methods

Now you can use the [`insert`](/methods/api/insert.md), [`move`](/methods/api/move.md), [`remove`](/methods/api/remove.md), [`replace`](/methods/api/replace.md), and [`swap`](/methods/api/swap.md) 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
<script setup lang="ts">
import { insert } from '@formisch/vue';
</script>

<template>
  <button
    type="button"
    @click="
      insert(todoForm, {
        path: ['todos'],
        initialInput: { label: '', deadline: '' },
      })
    "
  >
    Add Todo
  </button>
</template>
```

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
<script setup lang="ts">
import { remove } from '@formisch/vue';
</script>

<template>
  <button
    type="button"
    @click="remove(todoForm, { path: ['todos'], at: index })"
  >
    Delete
  </button>
</template>
```

##### Move method

Move an item from one position to another:

```vue
<script setup lang="ts">
import { move } from '@formisch/vue';
</script>

<template>
  <button
    type="button"
    @click="
      move(todoForm, {
        path: ['todos'],
        from: 0,
        to: fieldArray.items.length - 1,
      })
    "
  >
    Move first to end
  </button>
</template>
```

##### Swap method

Swap two items in the array:

```vue
<script setup lang="ts">
import { swap } from '@formisch/vue';
</script>

<template>
  <button
    type="button"
    @click="swap(todoForm, { path: ['todos'], at: 0, and: 1 })"
  >
    Swap first two
  </button>
</template>
```

##### Replace method

Replace an item with new data:

```vue
<script setup lang="ts">
import { replace } from '@formisch/vue';
</script>

<template>
  <button
    type="button"
    @click="
      replace(todoForm, {
        path: ['todos'],
        at: 0,
        initialInput: {
          label: 'New task',
          deadline: new Date().toISOString().split('T')[0],
        },
      })
    "
  >
    Replace first
  </button>
</template>
```

#### 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
<script setup lang="ts">
import * as v from 'valibot';

const NestedSchema = v.object({
  categories: v.array(
    v.object({
      name: v.string(),
      items: v.array(
        v.object({
          title: v.string(),
        })
      ),
    })
  ),
});
</script>

<template>
  <FieldArray :of="form" :path="['categories']" v-slot="categoryArray">
    <div
      v-for="(categoryItem, categoryIndex) in categoryArray.items"
      :key="categoryItem"
    >
      <Field
        :of="form"
        :path="['categories', categoryIndex, 'name']"
        v-slot="field"
      >
        <input v-bind="field.props" v-model="field.input" />
      </Field>

      <FieldArray
        :of="form"
        :path="['categories', categoryIndex, 'items']"
        v-slot="itemArray"
      >
        <div v-for="(item, itemIndex) in itemArray.items" :key="item">
          <Field
            :of="form"
            :path="['categories', categoryIndex, 'items', itemIndex, 'title']"
            v-slot="field"
          >
            <input v-bind="field.props" v-model="field.input" />
          </Field>
        </div>
      </FieldArray>
    </div>
  </FieldArray>
</template>
```

You can nest field arrays as deeply as you like. You will also find a suitable example of this in our [playground](/playground/nested/).

#### 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:

```ts
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](/vue/guides/define-your-form.md), 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
<script setup lang="ts">
import { Field, Form, useForm } from '@formisch/vue';
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 loginForm = useForm({
  schema: LoginSchema,
});

// TypeScript knows the form structure from the schema
// loginForm is of type FormStore<typeof LoginSchema>
</script>

<template>
  <Form
    :of="loginForm"
    @submit="
      (output) => {
        // output is fully typed based on LoginSchema
        console.log(output.email); // ✓ Type-safe
        console.log(output.username); // ✗ TypeScript error
      }
    "
  >
    <!-- Form fields -->
  </Form>
</template>
```

##### Input and output types

Valibot schemas can have different input and output types when using transformations. Formisch provides proper typing for both.

```vue
<script setup lang="ts">
import { Field, Form, useForm } from '@formisch/vue';
import * as v from 'valibot';

const ProfileSchema = v.object({
  age: v.pipe(
    v.string(), // Input type: string (from HTML input)
    v.transform((input) => Number(input)), // Output type: number
    v.number()
  ),
  birthDate: v.pipe(
    v.string(), // Input type: string (ISO date string)
    v.transform((input) => new Date(input)), // Output type: Date
    v.date()
  ),
});

const profileForm = useForm({
  schema: ProfileSchema,
});
</script>

<template>
  <Form
    :of="profileForm"
    @submit="
      (output) => {
        // output is: { age: number; birthDate: Date }
        console.log(output.age); // number
        console.log(output.birthDate); // Date
      }
    "
  >
    <Field :of="profileForm" :path="['age']" v-slot="field">
      <!-- field.input is string -->
      <input v-bind="field.props" v-model="field.input" type="text" />
    </Field>

    <Field :of="profileForm" :path="['birthDate']" v-slot="field">
      <!-- field.input is string -->
      <input v-bind="field.props" v-model="field.input" type="date" />
    </Field>

    <button type="submit">Submit</button>
  </Form>
</template>
```

##### 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
// <Field :of="userForm" :path="['profile', 'name', 'first']" v-slot="field" />
// <Field :of="userForm" :path="['profile', 'email']" v-slot="field" />

// ✗ Invalid paths - TypeScript error
// <Field :of="userForm" :path="['profile', 'age']" v-slot="field" />
// <Field :of="userForm" :path="['username']" v-slot="field" />
```

#### Type-safe props

To pass your form to another component via props, you can use the [`FormStore`](/vue/api/FormStore.md) type along with your schema type to get full type safety.

```vue
<script setup lang="ts">
import { useForm } from '@formisch/vue';
import * as v from 'valibot';
import FormContent from './FormContent.vue';

const LoginSchema = v.object({
  email: v.pipe(v.string(), v.email()),
  password: v.pipe(v.string(), v.minLength(8)),
});

const loginForm = useForm({
  schema: LoginSchema,
});
</script>

<template>
  <FormContent :of="loginForm" />
</template>

<!-- In another file: FormContent.vue -->
<script setup lang="ts">
import { Form, type FormStore } from '@formisch/vue';
import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(v.string(), v.email()),
  password: v.pipe(v.string(), v.minLength(8)),
});

type FormContentProps = {
  of: FormStore<typeof LoginSchema>;
};

const props = defineProps<FormContentProps>();
</script>

<template>
  <Form :of="props.of" @submit="(output, event) => console.log(output)">
    <!-- Form fields -->
  </Form>
</template>
```

#### Generic field components

You can create generic field components with proper TypeScript typing using the [`FormStore`](/vue/api/FormStore.md) type with Valibot's `GenericSchema`.

```vue
<script setup lang="ts">
import { useField } from '@formisch/vue';
import type { FormStore } from '@formisch/vue';
import * as v from 'valibot';

interface EmailInputProps {
  of: FormStore<v.GenericSchema<{ email: string }>>;
}

const props = defineProps<EmailInputProps>();

const field = useField(
  () => props.of,
  () => ({ path: ['email'] })
);
</script>

<template>
  <div>
    <label>
      Email
      <input v-bind="field.props" v-model="field.input" type="email" />
    </label>
    <div v-if="field.errors">{{ field.errors[0] }}</div>
  </div>
</template>
```

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](/vue/api/).

- [`FormStore`](/vue/api/FormStore.md) - The form store type
- [`FieldStore`](/vue/api/FieldStore.md) - The field store type
- [`FieldArrayStore`](/vue/api/FieldArrayStore.md) - The field
  array store type
- [`ValidPath`](/core/api/ValidPath.md) - Type for valid field
  paths
- [`ValidArrayPath`](/core/api/ValidArrayPath.md) - Type for
  valid array field paths
- [`FormSchema`](/core/api/FormSchema.md) - Form schema type
  required at the root
- [`Schema`](/core/api/Schema.md) - Base schema type from Valibot
- [`SubmitHandler`](/core/api/SubmitHandler.md) - Type for submit
  handlers without the event
- [`SubmitEventHandler`](/core/api/SubmitEventHandler.md) - Type
  for submit handlers with the event

### Architecture

You don't need to read this guide to use Formisch. It's here for people who want to understand why the bundle stays small, why updates are fine-grained, and how the same library can support Vue, Angular, SolidJS, React, React Native, Svelte, Preact and Qwik without forking the codebase. Each of those properties falls out of a few deliberate architectural choices.

#### Three packages, three responsibilities

Formisch is structured as three packages, each with a clear role:

- [`@formisch/core`](https://github.com/open-circle/formisch/tree/main/packages/core) is the framework-agnostic foundation. It contains the form and field store types, the recursive store builder that mirrors your Valibot schema, and the validation orchestration.
- [`@formisch/methods`](https://github.com/open-circle/formisch/tree/main/packages/methods) exposes the form operations as standalone, tree-shakeable functions: [`setInput`](/methods/api/setInput.md), [`validate`](/methods/api/validate.md), [`reset`](/methods/api/reset.md), [`insert`](/methods/api/insert.md), [`move`](/methods/api/move.md), [`focus`](/methods/api/focus.md) and so on. Each method lives in its own file and only imports the core helpers it actually needs.
- [`@formisch/vue`](https://github.com/open-circle/formisch/tree/main/frameworks/vue) is the thin user-facing layer. It provides the [`useForm`](/vue/api/useForm.md), [`useField`](/vue/api/useField.md) and [`useFieldArray`](/vue/api/useFieldArray.md) composables, the [`<Form />`](/vue/api/Form.md), [`<Field />`](/vue/api/Field.md) and [`<FieldArray />`](/vue/api/FieldArray.md) components, and re-exports every method from `@formisch/methods` so you only import from a single package.

```
@formisch/vue
  ├─ useForm, <Form />, <Field />, …             (Vue-specific reactive layer)
  └─ re-exports @formisch/methods/vue            (focus, reset, validate, …)
         └─ @formisch/core/vue                   (createFormStore, types, signals)
                  └─ framework adapter           (createSignal, batch, untrack, createId)
```

The modular architecture is what makes Formisch tree-shakeable. The core stays small, and every additional capability (`setInput`, `validate`, `reset`, `insert`, `move`, `focus` and the rest) is exported as its own function. A form that only imports `useForm`, `<Form />` and `<Field />` ships nothing else, even though `@formisch/vue` re-exports every method.

#### One core, one adapter per framework

The core package is framework-agnostic, but it still needs _some_ reactivity primitive to build on. Formisch handles this by providing a subpath export for every supported framework (`@formisch/core/vue`, `@formisch/core/solid`, `@formisch/core/react`, …), all built from the same source. The only file that differs between them [is a small adapter](https://github.com/open-circle/formisch/blob/main/packages/core/src/framework/index.ts) that exports four functions: `createSignal`, `batch`, `untrack` and `createId`.

The swap happens at build time, not at runtime. A small [rolldown plugin](https://github.com/open-circle/formisch/blob/main/packages/core/tsdown.config.ts) sits in front of import resolution: whenever the bundler resolves an import of `./framework/index.ts`, the plugin looks for a sibling `./framework/index.vue.ts` (or `.solid.ts`, `.react.ts`, …) and, if it exists, redirects the import there. The build runs once per framework, and each run produces a self-contained bundle with the framework-specific adapter inlined.

Vue's own `shallowRef` already implements the `.value` getter/setter shape Formisch's core relies on, so [the Vue adapter](https://github.com/open-circle/formisch/blob/main/packages/core/src/framework/index.vue.ts) is essentially a direct re-export:

```ts
export { shallowRef as createSignal } from 'vue';
```

For frameworks that don't have a native signal primitive (like React), the adapter implements a small pub/sub system from scratch that exposes the same `Signal<T>` shape. Every other file in `@formisch/core` only ever imports `createSignal`, `batch`, `untrack` and `createId`, never a framework directly. That's why the same [`createFormStore`](https://github.com/open-circle/formisch/blob/main/packages/core/src/form/createFormStore/createFormStore.ts) code path can power every framework binding without a single conditional.

This is what makes Formisch different from most framework-agnostic libraries. The usual approach is to ship a runtime abstraction (a custom store, an observer protocol, a subscription layer) that lives in the bundle and has to be bridged into each framework. Formisch ships nothing like that. Where the framework has native signals, Formisch uses them directly; where it doesn't, the adapter is just enough pub/sub to drive re-renders. Either way, there is no extra layer between your form state and the framework's reactivity, and your bundle pays no overhead for portability. Form state lives in real Vue `shallowRef` instances, fully integrated with Vue's reactivity system and dependency tracking.

That Formisch is framework-agnostic is not a trade-off you make. It's a benefit you get. A bug surfaced by a Svelte user is a bug fixed for Vue, Solid, React and everyone else. An improvement to the recursive store builder, the validation orchestration or any individual method lands across every binding at once. There is one library to maintain, not one per framework, and every community pulls the rest forward.

#### State lives in signals

Every piece of reactive state in Formisch is a [`Signal<T>`](https://github.com/open-circle/formisch/blob/main/packages/core/src/types/signal/signal.ts) with the same minimal interface:

```ts
interface Signal<T> {
  get value(): T;
  set value(nextValue: T): void;
}
```

Reads track, writes notify. There is no central store object that gets diffed and no equality check on the consumer side. Each field carries its own signals for `errors`, `isTouched`, `isEdited`, `isDirty`, plus an `input` signal for value fields and a `children` collection for arrays and objects. When you call `setInput(form, { path: ['email'], input: 'a@b.c' })`, only the `input` signal of that one field is written, so only the components that read that one signal (typically a single `<input />`) re-render.

This is the source of the fine-grained reactivity. The shape of the store is pre-allocated at form creation, matching the shape of your Valibot schema, so methods never have to look up paths in a generic object. They walk a typed tree of stores and update individual signals.

#### What happens when you call `useForm`

When you call [`useForm`](/vue/api/useForm.md), three layers cooperate to produce the form store you receive.

```vue
<script setup lang="ts">
import { useForm } from '@formisch/vue';
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 loginForm = useForm({ schema: LoginSchema });
</script>
```

First, the [Vue wrapper](https://github.com/open-circle/formisch/blob/main/frameworks/vue/src/composables/useForm/useForm.ts) hands the configuration to the core function [`createFormStore`](https://github.com/open-circle/formisch/blob/main/packages/core/src/form/createFormStore/createFormStore.ts), together with a parse closure that captures your schema:

```ts
const internalFormStore = createFormStore(config, (input) =>
  v.safeParseAsync(config.schema, input)
);
```

Next, `createFormStore` calls [`initializeFieldStore`](https://github.com/open-circle/formisch/blob/main/packages/core/src/field/initializeFieldStore/initializeFieldStore.ts), which walks your Valibot schema recursively and builds the internal store hierarchy:

- A `v.object(...)` becomes an `InternalObjectStore` with a `children` record keyed by field name.
- A `v.array(...)` or `v.tuple(...)` becomes an `InternalArrayStore` with a `children` list and its own `initialInput`, `startInput` and `input` signals so it can track structural changes.
- A leaf like `v.string()` or `v.number()` becomes an `InternalValueStore` with an `input` signal that holds the current field value.
- Wrapper schemas such as `v.optional`, `v.nullable`, `v.nonNullable` and `v.lazy` are unwrapped and recursed into.
- `v.union`, `v.variant` and `v.intersect` initialize every option into the same store, which is what lets you address discriminated fields with a single field path.

At every level, the same four signals are created: `errors`, `isTouched`, `isEdited` and `isDirty`. Once the field tree is built, three more signals are added to the form root: `isSubmitting`, `isSubmitted` and `isValidating`.

Finally, the Vue wrapper builds the public form store you actually receive. It's a small reactive object that sits on top of the internal store: form-level signals are exposed through getters that read `internalFormStore.isSubmitting.value` and friends, while derived state like `isTouched`, `isEdited`, `isDirty` and `isValid` is wrapped in `computed` so it recomputes lazily as the underlying field signals change:

```ts
const isTouched = computed(() =>
  getFieldBool(internalFormStore, 'isTouched')
);
const isDirty = computed(() => getFieldBool(internalFormStore, 'isDirty'));
const isValid = computed(() => !getFieldBool(internalFormStore, 'errors'));

return {
  [INTERNAL]: internalFormStore,
  get isSubmitting() {
    return internalFormStore.isSubmitting.value;
  },
  get isTouched() {
    return isTouched.value;
  },
  // …
};
```

The internal store is tucked away behind the [`INTERNAL`](https://github.com/open-circle/formisch/blob/main/packages/core/src/values.ts) symbol. Methods like `setInput(form, …)` reach in via `form[INTERNAL]` to mutate signals, while your code only sees the public form store. This separation is what keeps the public API small and stable even as the internal shape evolves.

#### Why this design pays off

Bundle size is the obvious payoff. The others are why the design is worth talking about:

- **Small bundle size.** Because methods are individual modules re-exported from [`@formisch/vue`](https://github.com/open-circle/formisch/tree/main/frameworks/vue), a form that uses only [`useForm`](/vue/api/useForm.md) and [`<Field />`](/vue/api/Field.md) never pulls in [`validate`](/methods/api/validate.md), [`reset`](/methods/api/reset.md), [`insert`](/methods/api/insert.md) or the other operations. Tree-shaking gets to do real work.
- **Fine-grained reactivity.** The store shape is pre-allocated at form creation, with one signal per piece of state. Methods write `.value` directly and Vue's reactivity system handles propagation. Updating one field does not invalidate the rest.
- **Framework portability.** The entire library is parameterized over a four-function adapter. Adding a new framework means writing a small adapter that maps `createSignal`, `batch`, `untrack` and `createId` onto its primitives.
- **Type safety.** Your Valibot schema is the single source of truth. It drives both runtime parsing and the inferred TypeScript types for paths, inputs and outputs, so there is no second declaration to keep in sync.

#### Further reading

To see how these design choices stack up against alternatives, head to the [comparison](/vue/guides/comparison.md) guide. For a closer look at how Valibot's inference flows into your editor, see [TypeScript](/vue/guides/typescript.md). And if you want to read the recursive walker, the adapter implementations, or how individual methods are written, the full source is on [GitHub](https://github.com/open-circle/formisch).

## Migration guides

### Migrate from VeeValidate

This guide walks you through migrating a form from [VeeValidate](https://vee-validate.logaretm.com) to Formisch. It explains the mental-model differences, shows the same form implemented in both libraries, and maps VeeValidate's APIs, options, and state fields to their Formisch counterparts.

Migrating is a rewrite of your form layer, not a drop-in replacement. That said, the conceptual gap is small: both libraries are headless, composables-based, and schema-friendly. The main work is consolidating your validation into a single root Valibot schema and replacing VeeValidate's `useForm` and `defineField` with Formisch's composables and components.

Both libraries can coexist in the same application, so you can migrate one form at a time instead of doing everything in a single step. Since both libraries export a composable named `useForm`, the import path determines which one a component uses.

#### Key differences

The biggest shift is that Formisch is strictly schema-first. In VeeValidate, validation can come from several places: validator functions, globally registered rules, or a schema from Yup, Zod, or Valibot passed as `validationSchema` (usually wrapped in `toTypedSchema` for type inference). The form's shape is implied by whatever fields you register. In Formisch, a single Valibot schema is the one source of truth for the form's structure, its TypeScript types, and its validation rules. There is no resolver or wrapper to configure: you pass the schema to [`useForm`](/vue/api/useForm.md) and every path, input value, and submit handler is typed from it.

Validation also runs differently:

- **Location**: VeeValidate attaches rules per field (or resolves them from a schema per field). Formisch always parses the entire form against the schema in a single pass and distributes the resulting issues to the individual fields, so cross-field rules work without extra wiring.
- **Timing**: VeeValidate configures triggers per field or globally via `configure()` with flags like `validateOnBlur`, `validateOnChange`, and `validateOnModelUpdate`. Formisch controls timing form-wide with two options on `useForm`: `validate` (first validation, defaults to `'submit'`) and `revalidate` (subsequent validations, defaults to `'input'`).
- **Field addressing**: VeeValidate identifies fields by string paths like `'members[0].email'`. Formisch uses path arrays like `['members', 0, 'email']` that are fully type-checked against your schema.
- **Form state**: VeeValidate spreads state across the values returned by `useForm` (`values`, `errors`, `meta`, `isSubmitting`, …) plus helper composables like `useIsFormDirty`. Formisch returns one form store with flat reactive properties such as `isDirty`, `isValid`, and `isSubmitting`.

Reactivity is comparable: both libraries build on Vue's reactivity system, so components only re-render when the state they read changes. The trade-offs to be aware of are that Formisch currently supports only Valibot as the schema library, while its bundle size starts at about 2.5 kB compared to VeeValidate's roughly 12 kB. See the [comparison](/vue/guides/comparison.md) guide for a broader overview.

#### Side-by-side example

The following login form has two validated fields and an async submit handler. The VeeValidate version uses the composition API with a Zod schema, which is one of the most common setups. The Formisch version implements the exact same behavior.

##### VeeValidate

```vue
<script setup lang="ts">
import { toTypedSchema } from '@vee-validate/zod';
import { useForm } from 'vee-validate';
import { z } from 'zod';

const validationSchema = toTypedSchema(
  z.object({
    email: z
      .string()
      .min(1, 'Please enter your email.')
      .email('The email address is badly formatted.'),
    password: z
      .string()
      .min(1, 'Please enter your password.')
      .min(8, 'Your password must have 8 characters or more.'),
  })
);

const { defineField, errors, handleSubmit, isSubmitting } = useForm({
  validationSchema,
});

const [email, emailProps] = defineField('email');
const [password, passwordProps] = defineField('password');

const onSubmit = handleSubmit(async (values) => {
  await fetch('/api/login', {
    method: 'POST',
    body: JSON.stringify(values),
  });
});
</script>

<template>
  <form @submit="onSubmit">
    <div>
      <input v-model="email" v-bind="emailProps" type="email" />
      <div v-if="errors.email">{{ errors.email }}</div>
    </div>
    <div>
      <input v-model="password" v-bind="passwordProps" type="password" />
      <div v-if="errors.password">{{ errors.password }}</div>
    </div>
    <button type="submit" :disabled="isSubmitting">Login</button>
  </form>
</template>
```

##### Formisch

```vue
<script setup lang="ts">
import { Field, Form, useForm } from '@formisch/vue';
import type { SubmitHandler } from '@formisch/vue';
import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
});

const loginForm = useForm({
  schema: LoginSchema,
});

const submitForm: SubmitHandler<typeof LoginSchema> = async (values) => {
  await fetch('/api/login', {
    method: 'POST',
    body: JSON.stringify(values),
  });
};
</script>

<template>
  <Form :of="loginForm" @submit="submitForm">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <div>
        <input v-model="field.input" v-bind="field.props" type="email" />
        <div v-if="field.errors">{{ field.errors[0] }}</div>
      </div>
    </Field>
    <Field :of="loginForm" :path="['password']" v-slot="field">
      <div>
        <input v-model="field.input" v-bind="field.props" type="password" />
        <div v-if="field.errors">{{ field.errors[0] }}</div>
      </div>
    </Field>
    <button type="submit" :disabled="loginForm.isSubmitting">Login</button>
  </Form>
</template>
```

Instead of destructuring `useForm` and defining a model tuple per field, you keep the single `loginForm` store and connect each input through the [`Field`](/vue/api/Field.md) component. Errors live on the field store as an array, and the submit handler receives values that are already validated and typed by the schema.

#### Migration steps

##### Install Formisch

Add Formisch and Valibot to your project. Keep `vee-validate` installed until the last form is migrated, then remove it together with its schema adapter packages like `@vee-validate/zod`.

```bash
npm install @formisch/vue valibot
```

##### Move validation into a Valibot schema

Formisch validates exclusively against a Valibot schema. If you used Zod or Yup with VeeValidate, translate the schema; the structure usually maps one to one. If you already used Valibot through `@vee-validate/valibot`, you can reuse your schema unchanged and simply drop the `toTypedSchema` wrapper.

```ts
import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
});
```

If some of your validation lives in validator functions or globally registered rules instead of a schema, consolidate it into the schema now. Custom logic translates to `v.check()`, and async rules (for example a server-side uniqueness check) translate to `v.checkAsync()` with `v.objectAsync()` and `v.pipeAsync()`. Define the fields in the same order they appear in your form, since Formisch focuses the first invalid field on submit based on the schema order. See the [define your form](/vue/guides/define-your-form.md) guide for details.

##### Replace the form setup

Replace VeeValidate's `useForm` with Formisch's [`useForm`](/vue/api/useForm.md) composable. Instead of destructuring individual helpers, you keep the returned form store and pass it to Formisch's components and methods. The `initialValues` option becomes `initialInput`.

```ts
// VeeValidate
const { defineField, errors, handleSubmit } = useForm({
  validationSchema,
  initialValues: { email: 'jane@example.com' },
});

// Formisch
const loginForm = useForm({
  schema: LoginSchema,
  initialInput: { email: 'jane@example.com' },
});
```

##### Replace field bindings

Each `defineField` tuple (or `useField` call, or `<Field name="…">` component) becomes a [`Field`](/vue/api/Field.md) component with a type-safe path array. The `v-slot` directive exposes the field store with `input`, `props`, `errors`, and state flags.

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <input v-model="field.input" v-bind="field.props" type="email" />
    <div v-if="field.errors">{{ field.errors[0] }}</div>
  </Field>
</template>
```

Note that errors move with the field: instead of looking up `errors.email` on the form, you read `field.errors` inside the field's slot. This also replaces VeeValidate's `<ErrorMessage />` component. For dedicated field components, use the [`useField`](/vue/api/useField.md) composable as described in the [add form fields](/vue/guides/add-form-fields.md) guide.

##### Update submission handling

VeeValidate wraps your handler with `handleSubmit` and binds the result to a native `<form>` element. In Formisch, you wrap your fields in the [`Form`](/vue/api/Form.md) component and pass your handler to its `@submit` event. The handler only runs when the schema parses successfully and receives the fully typed output.

```vue
<script setup lang="ts">
import type { SubmitHandler } from '@formisch/vue';

const submitForm: SubmitHandler<typeof LoginSchema> = async (values) => {
  console.log(values); // { email: string, password: string }
};
</script>

<template>
  <Form :of="loginForm" @submit="submitForm">
    <!-- fields -->
  </Form>
</template>
```

If you cannot render a `<form>` element, for example inside another form, use the [`handleSubmit`](/methods/api/handleSubmit.md) method instead, as shown in the [handle submission](/vue/guides/handle-submission.md) guide.

#### API mapping

| VeeValidate                        | Formisch                                                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `useForm({ validationSchema })`    | [`useForm`](/vue/api/useForm.md) with `schema`                                                                  |
| `initialValues`                    | `initialInput`                                                                                                                 |
| `configure({ validateOnBlur, … })` | `validate` / `revalidate` config of [`useForm`](/vue/api/useForm.md)                                            |
| `defineField('email')`             | [`Field`](/vue/api/Field.md) component with `:path="['email']"`                                                 |
| `useField('email')`                | [`useField`](/vue/api/useField.md) composable                                                                   |
| `<Field name="email" />`           | [`Field`](/vue/api/Field.md) component                                                                          |
| `<ErrorMessage name="email" />`    | `field.errors` inside the [`Field`](/vue/api/Field.md) slot                                                     |
| `handleSubmit(onSuccess)`          | `@submit` of [`Form`](/vue/api/Form.md) or [`handleSubmit`](/methods/api/handleSubmit.md)        |
| `values`                           | `field.input` or [`getInput`](/methods/api/getInput.md)                                                         |
| `errors.email`                     | `field.errors` or [`getErrors`](/methods/api/getErrors.md)                                                      |
| `meta.dirty` / `meta.touched`      | `form.isDirty` / `form.isTouched`                                                                                              |
| `meta.valid`                       | `form.isValid`                                                                                                                 |
| `meta.pending`                     | `form.isValidating`                                                                                                            |
| `isSubmitting`                     | `form.isSubmitting`                                                                                                            |
| `submitCount`                      | `form.isSubmitted`                                                                                                             |
| `setFieldValue` / `setValues`      | [`setInput`](/methods/api/setInput.md)                                                                          |
| `setFieldError` / `setErrors`      | [`setErrors`](/methods/api/setErrors.md)                                                                        |
| `resetForm` / `resetField`         | [`reset`](/methods/api/reset.md)                                                                                |
| `validate` / `validateField`       | [`validate`](/methods/api/validate.md)                                                                          |
| `useFieldArray('list')`            | [`FieldArray`](/vue/api/FieldArray.md) component or [`useFieldArray`](/vue/api/useFieldArray.md) |
| `push` / `prepend` / `insert`      | [`insert`](/methods/api/insert.md)                                                                              |
| `remove`                           | [`remove`](/methods/api/remove.md)                                                                              |
| `swap`                             | [`swap`](/methods/api/swap.md)                                                                                  |
| `move`                             | [`move`](/methods/api/move.md)                                                                                  |
| `update`                           | [`replace`](/methods/api/replace.md)                                                                            |

A few entries deserve a note. `submitCount` has no direct equivalent: Formisch tracks the boolean `isSubmitted`, which is `true` after the first submit attempt. The touched flag behaves slightly differently: Formisch marks a field as touched when it receives focus or its input is set, while VeeValidate marks it on blur, so ordinary touched-based logic usually reacts on focus instead of waiting for blur. Formisch's `setInput` therefore also marks the field as touched and edited, whereas VeeValidate's `setFieldValue` does not mark it as touched. Similarly, `validateField` has no per-field counterpart, because Formisch's [`validate`](/methods/api/validate.md) always parses the whole form and distributes the resulting issues to the fields. VeeValidate's `replace(items)`, which swaps out the entire array, maps to calling [`setInput`](/methods/api/setInput.md) with the array's path. Globally registered rules via `defineRule` and the `@vee-validate/rules` package have no equivalent, since all validation lives in the Valibot schema. The same applies to `toTypedSchema`: it is simply no longer needed, because types are inferred from the schema directly. Helper composables like `useIsFormDirty` or `useFormValues` are also unnecessary, as the form store itself is reactive and can be passed around freely.

#### Common patterns

##### Form state

In VeeValidate, aggregated form state lives on the `meta` computed ref and separate refs like `isSubmitting`, or is accessed through helper composables. In Formisch, everything is a flat reactive property on the form store, so you read it directly in your template or component logic.

```vue
<template>
  <button
    type="submit"
    :disabled="!loginForm.isDirty || loginForm.isSubmitting"
  >
    {{ loginForm.isSubmitting ? 'Submitting...' : 'Login' }}
  </button>
</template>
```

The available properties are `isSubmitting`, `isSubmitted`, `isValidating`, `isTouched`, `isEdited`, `isDirty`, `isValid`, and `errors`. The same flags exist per field on the field store.

##### Validation timing

VeeValidate validates each field aggressively by default (on model updates, change, and blur) and lets you tune this per field, for example with `validateOnModelUpdate: false` on `defineField`, or globally via `configure()`. Formisch replaces this per-field event configuration with two form-wide options:

```ts
const loginForm = useForm({
  schema: LoginSchema,
  validate: 'blur', // first validation per field, defaults to 'submit'
  revalidate: 'input', // subsequent validations, defaults to 'input'
});
```

With the defaults, a field stays quiet until the form is submitted and then corrects itself on every keystroke. Unlike VeeValidate, Formisch also decouples running validation from showing errors: after a validation pass you decide which errors to render, typically guarded by `field.isEdited || form.isSubmitted`. The [validation](/vue/guides/validation.md) guide covers this pattern in depth.

##### Field arrays

VeeValidate's `useFieldArray` returns a `fields` ref whose entries carry a `key` for the `v-for` directive, plus bound methods like `push` and `remove`. Formisch provides the [`FieldArray`](/vue/api/FieldArray.md) component, whose store exposes an `items` array of unique string identifiers to use as keys, and standalone array methods that take the form store and a path.

```vue
<script setup lang="ts">
import { Field, FieldArray, insert, remove } from '@formisch/vue';
</script>

<template>
  <FieldArray :of="todoForm" :path="['todos']" v-slot="fieldArray">
    <div v-for="(item, index) in fieldArray.items" :key="item">
      <Field :of="todoForm" :path="['todos', index, 'label']" v-slot="field">
        <input v-model="field.input" v-bind="field.props" type="text" />
      </Field>
      <button
        type="button"
        @click="remove(todoForm, { path: ['todos'], at: index })"
      >
        Delete
      </button>
    </div>
    <button
      type="button"
      @click="
        insert(todoForm, { path: ['todos'], initialInput: { label: '' } })
      "
    >
      Add todo
    </button>
  </FieldArray>
</template>
```

Rules on the array itself, like VeeValidate's `.min(1)` on a Yup array, move into the schema with `v.nonEmpty()` or `v.minLength()` on `v.array()`, and their errors appear on `fieldArray.errors`. See the [field arrays](/vue/guides/field-arrays.md) guide for the complete picture, including `move`, `swap`, and `replace`.

##### Reset

VeeValidate's `resetForm()` restores initial values, and `resetForm({ values })` establishes new ones. The Formisch equivalent is the [`reset`](/methods/api/reset.md) method, which also accepts a new `initialInput` as the new baseline for dirty tracking, for example after refreshed server data.

```ts
import { reset } from '@formisch/vue';

// Reset the form to its initial state
reset(loginForm);

// Reset with new initial values
reset(loginForm, { initialInput: { email: 'jane@example.com', password: '' } });
```

Note that resetting to programmatically set values requires controlled fields, so make sure your inputs use `v-model` as shown in the [controlled fields](/vue/guides/controlled-fields.md) guide.

##### Special inputs

In VeeValidate, checkboxes and radio buttons need extra configuration such as `type: 'checkbox'` and `checkedValue` on `useField`. With Formisch, you spread `field.props` onto the native element and add `v-model`, and Vue's `v-model` semantics handle single checkboxes, checkbox groups, radio buttons, and selects without further setup:

```vue
<template>
  <Field :of="form" :path="['cookies']" v-slot="field">
    <label>
      <input type="checkbox" v-bind="field.props" v-model="field.input" />
      Yes, I want cookies
    </label>
  </Field>
</template>
```

File inputs are the exception: Vue does not allow `v-model` on them, and spreading `field.props` alone does not capture the selected file. Add an `input` handler that writes the file to `field.input` yourself:

```vue
<template>
  <Field :of="form" :path="['document']" v-slot="field">
    <input
      v-bind="field.props"
      type="file"
      @input="field.input = ($event.target as HTMLInputElement).files?.[0]"
    />
  </Field>
</template>
```

The [special inputs](/vue/guides/special-inputs.md) guide shows the full set of supported input types.

#### Next steps

You now have everything you need to migrate your forms one at a time. To deepen your understanding of the Formisch APIs used in this guide, work through the [add form fields](/vue/guides/add-form-fields.md) and [handle submission](/vue/guides/handle-submission.md) guides, build reusable [input components](/vue/guides/input-components.md), and explore the [form methods](/vue/guides/form-methods.md) guide for programmatic control of your forms.

### Migrate from FormKit

This guide walks you through migrating your Vue forms from [FormKit](https://formkit.com) (`@formkit/vue`) to Formisch. It covers the differences in mental model, shows the same form in both libraries side by side, and maps FormKit's APIs to their Formisch equivalents.

Migrating is a rewrite of your form layer, not a drop-in replacement. FormKit is component-driven and renders your inputs for you, while Formisch is headless and only provides the data layer. The migration therefore replaces both the form logic and the input markup that FormKit generated for you.

The good news: both libraries can coexist in the same application. Formisch does not require an app-level plugin, so you can leave FormKit's plugin registered in `main.ts` and migrate one form at a time. Once the last FormKit form is gone, remove the plugin and the dependency.

#### Key differences

FormKit is a batteries-included form framework. A single globally registered `<FormKit>` component renders the entire input scaffolding, including the label, help text, validation messages, and styling. The form's structure emerges at runtime from the `name` props of the inputs nested inside `<FormKit type="form">`, validation rules are co-located with each input as string props like `validation="required|email"`, and TypeScript types for the submitted data are declared manually (or derived via the optional Zod plugin).

Formisch flips this around with a schema-first approach. A single Valibot schema is the form: it defines the structure, the TypeScript types, and all validation rules at once. The `useForm` composable turns the schema into a reactive form store, and headless components like `Field` connect your own markup to it via type-safe path arrays. When the schema changes, every path and every inferred type follows at compile time.

The main differences at a glance:

- **UI ownership**: FormKit renders inputs, labels, and messages for you. Formisch renders nothing; you write the markup (or your own reusable [input components](/vue/guides/input-components.md)) and get full control over it.
- **Source of truth**: In FormKit, structure lives in the template, validation lives on each input, and types live in your TypeScript code. In Formisch, all three live in one Valibot schema.
- **Validation location and timing**: FormKit validates each input against its `validation` prop and controls message display per input via `validation-visibility`. Formisch validates the whole form against the schema and controls timing form-wide via the `validate` and `revalidate` config. When errors are shown is up to your markup.
- **Reactivity**: FormKit keeps state in its own framework-agnostic core node tree that you access through `getNode`, node contexts, or slot props. Formisch stores state directly in Vue's reactivity system, so you read `form.isSubmitting` or `field.errors` like any other reactive value.
- **Bundle size**: FormKit starts at roughly 25 kB (min+gzip). Formisch starts at about 2.5 kB and only grows with the methods you import, since it is fully tree-shakeable.

#### Side-by-side example

The following login form has two required fields with validation messages and an async submit handler, implemented once with each library.

##### FormKit

```vue
<script setup lang="ts">
// The <FormKit> component is registered globally via
// app.use(plugin, defaultConfig) in main.ts
const handleSubmit = async (data: { email: string; password: string }) => {
  console.log(data);
};
</script>

<template>
  <FormKit type="form" submit-label="Login" @submit="handleSubmit">
    <FormKit
      type="email"
      name="email"
      label="Email"
      validation="required|email"
      :validation-messages="{
        required: 'Please enter your email.',
        email: 'The email address is badly formatted.',
      }"
    />
    <FormKit
      type="password"
      name="password"
      label="Password"
      validation="required|length:8"
      :validation-messages="{
        required: 'Please enter your password.',
        length: 'Your password must have 8 characters or more.',
      }"
    />
  </FormKit>
</template>
```

##### Formisch

```vue
<script setup lang="ts">
import { Field, Form, useForm } from '@formisch/vue';
import type { SubmitHandler } from '@formisch/vue';
import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
});

const loginForm = useForm({
  schema: LoginSchema,
});

const handleSubmit: SubmitHandler<typeof LoginSchema> = async (values) => {
  console.log(values); // { email: string, password: string }
};
</script>

<template>
  <Form :of="loginForm" @submit="handleSubmit">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <input v-bind="field.props" v-model="field.input" type="email" />
      <div v-if="field.errors">{{ field.errors[0] }}</div>
    </Field>
    <Field :of="loginForm" :path="['password']" v-slot="field">
      <input v-bind="field.props" v-model="field.input" type="password" />
      <div v-if="field.errors">{{ field.errors[0] }}</div>
    </Field>
    <button type="submit" :disabled="loginForm.isSubmitting">Login</button>
  </Form>
</template>
```

The Formisch version renders plain HTML instead of FormKit's prebuilt scaffolding, so the label, help text, and error markup that FormKit generated is now yours to write. In a real app you would move it into a reusable `TextInput` component, as shown in the [input components](/vue/guides/input-components.md) guide. In return, the submit handler receives values that are validated and fully typed by the schema, without a manually declared type.

#### Migration steps

##### Install Formisch

Install Formisch and Valibot alongside FormKit. See the [installation](/vue/guides/installation.md) guide for details.

```bash
npm install @formisch/vue valibot
```

Since Formisch requires no `app.use(...)` call, nothing changes in `main.ts` yet. Keep FormKit's plugin registered until the last FormKit form is migrated.

##### Move validation into a Valibot schema

Collect the `validation` and `:validation-messages` props of each input in the form and translate them into one Valibot schema. The nesting of `name` props (including `type="group"` wrappers) becomes the nesting of the object schema, and each validation rule becomes a Valibot action with its message as the first argument.

```ts
import * as v from 'valibot';

const LoginSchema = v.object({
  // FormKit: validation="required|email"
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
});
```

Common rule mappings: `required` becomes `v.nonEmpty(...)` for strings, `email` becomes `v.email(...)`, `length:8` becomes `v.minLength(8, ...)`, `between:1,10` becomes `v.minValue(1, ...)` and `v.maxValue(10, ...)`, and custom rules become `v.check(...)` or `v.checkAsync(...)`. Define the fields in the same order they appear in your form, since Formisch focuses the first invalid field on submit based on the schema order. See the [define your form](/vue/guides/define-your-form.md) guide for more details.

##### Replace the form setup

Replace `<FormKit type="form">` with the [`useForm`](/vue/api/useForm.md) composable and the [`Form`](/vue/api/Form.md) component. If your FormKit form was prefilled via the `:value` prop or `v-model`, pass that data as `initialInput` instead.

```vue
<script setup lang="ts">
import { Form, useForm } from '@formisch/vue';

const loginForm = useForm({
  schema: LoginSchema,
  initialInput: { email: 'jane@example.com' },
});
</script>

<template>
  <Form :of="loginForm" @submit="handleSubmit">
    <!-- Fields will go here -->
    <button type="submit">Login</button>
  </Form>
</template>
```

Note that FormKit automatically renders a submit button at the bottom of every form. Formisch does not, so add your own `<button type="submit">`.

##### Replace field bindings

Each `<FormKit>` input becomes a [`Field`](/vue/api/Field.md) component wrapping your own markup. The `name` prop becomes a type-safe `path` array, and nested `type="group"` structures become longer paths like `['address', 'street']`. The `v-slot` directive exposes the field store with `props` to spread onto the element, `input` for `v-model`, and `errors` for display.

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <label :for="field.props.name">Email</label>
    <input
      v-bind="field.props"
      :id="field.props.name"
      v-model="field.input"
      type="email"
    />
    <div v-if="field.errors">{{ field.errors[0] }}</div>
  </Field>
</template>
```

For field components that encapsulate a single field, the [`useField`](/vue/api/useField.md) composable provides the same field store in the script block. See the [add form fields](/vue/guides/add-form-fields.md) guide for both approaches.

##### Update submission handling

FormKit's `@submit` handler receives the collected form data and the form's core node, which is also used to set backend errors via `node.setErrors(...)`. In Formisch, the `@submit` handler on the `Form` component receives the schema-validated output, typed by [`SubmitHandler`](/core/api/SubmitHandler.md), and backend errors are set with the [`setErrors`](/methods/api/setErrors.md) method.

```ts
import { setErrors } from '@formisch/vue';
import type { SubmitHandler } from '@formisch/vue';

const handleSubmit: SubmitHandler<typeof LoginSchema> = async (values) => {
  const response = await login(values);
  if (!response.ok) {
    setErrors(loginForm, {
      path: ['email'],
      errors: ['This email is not registered.'],
    });
  }
};
```

Leaving out the `path` sets form-level errors, which you can display via `loginForm.errors`.

#### API mapping

| FormKit                              | Formisch                                                                                                                                                        |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin` + `defaultConfig`           | Not needed, just import from `@formisch/vue`                                                                                                                    |
| `<FormKit type="form">`              | [`useForm`](/vue/api/useForm.md) + [`Form`](/vue/api/Form.md)                                                                     |
| `<FormKit name="…" />`               | [`Field`](/vue/api/Field.md) component or [`useField`](/vue/api/useField.md) composable                                           |
| `<FormKit type="group">`             | Nested object schema + path arrays                                                                                                                              |
| `validation` prop                    | Valibot schema passed to `useForm`                                                                                                                              |
| `:validation-messages` prop          | Messages in the schema actions                                                                                                                                  |
| `validation-visibility` prop         | `validate` / `revalidate` config + your markup                                                                                                                  |
| `:value` / `v-model` on the form     | `initialInput` config                                                                                                                                           |
| `@submit`                            | `@submit` on [`Form`](/vue/api/Form.md)                                                                                                          |
| `state.valid`                        | `form.isValid` / `field.isValid`                                                                                                                                |
| `state.dirty`                        | `form.isEdited` / `field.isEdited` by default (see below)                                                                                                       |
| `state.loading`                      | `form.isSubmitting`                                                                                                                                             |
| `state.submitted`                    | `form.isSubmitted`                                                                                                                                              |
| `node.setErrors()`                   | [`setErrors`](/methods/api/setErrors.md)                                                                                                         |
| `reset()`                            | [`reset`](/methods/api/reset.md)                                                                                                                 |
| `submitForm()`                       | [`submit`](/methods/api/submit.md)                                                                                                               |
| `getNode()` + `node.value`           | [`getInput`](/methods/api/getInput.md)                                                                                                           |
| `<FormKit type="repeater">` / `list` | [`FieldArray`](/vue/api/FieldArray.md) + [`insert`](/methods/api/insert.md), [`remove`](/methods/api/remove.md), … |
| `<FormKitSchema>`                    | No equivalent                                                                                                                                                   |
| `@formkit/zod` plugin                | Built in, the Valibot schema is the form definition                                                                                                             |

A few entries have no direct equivalent. `<FormKitSchema>` generates entire forms from JSON, which has no counterpart in a headless library; with Formisch you write the template yourself. The same applies to FormKit's rendered UI scaffolding, themes, and icons: in Formisch you own the markup, so labels, help text, and message rendering move into your own [input components](/vue/guides/input-components.md). And where FormKit configures validation display per input, Formisch configures validation timing once per form and leaves error display to your template.

FormKit's default `dirty-behavior="touched"` stays `true` after any mutation, so it maps to Formisch's `isEdited`. If you configured `dirty-behavior="compare"`, use Formisch's `isDirty` instead; both compare the current input with its initial value and turn off when they match again.

#### Common patterns

##### Form state

In FormKit, form state lives on the core node and is accessed through the form's slot props or via `getNode('id').context.state`:

```vue
<template>
  <FormKit
    type="form"
    :actions="false"
    @submit="handleSubmit"
    v-slot="{ state }"
  >
    <!-- Fields -->
    <FormKit type="submit" label="Login" :disabled="!state.valid" />
  </FormKit>
</template>
```

In Formisch, the form store returned by `useForm` is reactive, so you read state directly in script or template. The form store exposes `isSubmitting`, `isSubmitted`, `isValidating`, `isTouched`, `isEdited`, `isDirty`, `isValid`, and `errors`, and each field store offers per-field `isTouched`, `isEdited`, `isDirty`, and `isValid` counterparts.

```vue
<template>
  <Form :of="loginForm" @submit="handleSubmit">
    <!-- Fields -->
    <button type="submit" :disabled="loginForm.isSubmitting">
      {{ loginForm.isSubmitting ? 'Submitting...' : 'Login' }}
    </button>
  </Form>
</template>
```

##### Validation timing

FormKit validates continuously and uses `validation-visibility` (with values like `blur`, `live`, `dirty`, and `submit`) to decide per input when messages appear. Formisch splits this into two parts. The `validate` and `revalidate` config control when validation runs for the whole form:

```ts
const loginForm = useForm({
  schema: LoginSchema,
  validate: 'blur', // First validation on blur (default: 'submit')
  revalidate: 'input', // Revalidation on every keystroke (default: 'input')
});
```

When errors are displayed is decided in your markup. To approximate FormKit's default behavior of revealing messages once a field was interacted with, guard the error output with field state:

```vue
<Field :of="loginForm" :path="['email']" v-slot="field">
  <input v-bind="field.props" v-model="field.input" type="email" />
  <div v-if="(field.isEdited || loginForm.isSubmitted) && field.errors">
    {{ field.errors[0] }}
  </div>
</Field>
```

See the [validation](/vue/guides/validation.md) guide for the full picture, including async validation with `isValidating`.

##### Field arrays

FormKit handles repeating groups with the `repeater` input (a free Pro input from `@formkit/pro` that must be registered separately) or a dynamic `list`, and the repeater brings its own UI for adding, removing, and shifting items:

```vue
<template>
  <FormKit type="form" @submit="saveTeam">
    <FormKit type="repeater" name="members" label="Team members">
      <FormKit type="text" name="name" label="Name" validation="required" />
    </FormKit>
  </FormKit>
</template>
```

In Formisch, the array is part of the schema, the [`FieldArray`](/vue/api/FieldArray.md) component provides stable `items` keys for `v-for`, and methods like [`insert`](/methods/api/insert.md) and [`remove`](/methods/api/remove.md) mutate the array:

```vue
<script setup lang="ts">
import {
  Field,
  FieldArray,
  Form,
  insert,
  remove,
  useForm,
} from '@formisch/vue';
import * as v from 'valibot';

const TeamSchema = v.object({
  members: v.array(
    v.object({
      name: v.pipe(v.string(), v.nonEmpty('Please enter a name.')),
    })
  ),
});

const teamForm = useForm({
  schema: TeamSchema,
  initialInput: { members: [{ name: '' }] },
});
</script>

<template>
  <Form :of="teamForm" @submit="(output) => console.log(output)">
    <FieldArray :of="teamForm" :path="['members']" v-slot="fieldArray">
      <div v-for="(item, index) in fieldArray.items" :key="item">
        <Field :of="teamForm" :path="['members', index, 'name']" v-slot="field">
          <input v-bind="field.props" v-model="field.input" type="text" />
          <div v-if="field.errors">{{ field.errors[0] }}</div>
        </Field>
        <button
          type="button"
          @click="remove(teamForm, { path: ['members'], at: index })"
        >
          Remove
        </button>
      </div>
    </FieldArray>
    <button
      type="button"
      @click="
        insert(teamForm, { path: ['members'], initialInput: { name: '' } })
      "
    >
      Add member
    </button>
    <button type="submit">Save</button>
  </Form>
</template>
```

The [`move`](/methods/api/move.md), [`swap`](/methods/api/swap.md), and [`replace`](/methods/api/replace.md) methods cover reordering. See the [field arrays](/vue/guides/field-arrays.md) guide for nested arrays and array-level validation.

##### Reset

FormKit resets a form through its `id` with the `reset` helper, for example `reset('login-form')` imported from `@formkit/core`. In Formisch, the [`reset`](/methods/api/reset.md) method takes the form store directly:

```vue
<script setup lang="ts">
import { reset } from '@formisch/vue';
</script>

<template>
  <button type="button" @click="reset(loginForm)">Reset</button>
</template>
```

Like FormKit's optional second argument to `reset`, Formisch accepts new initial values. Calling `reset(loginForm, { initialInput: ... })` updates the baseline that dirty tracking compares against, which is the right tool when refreshed server data should become the new initial state.

##### Special inputs

FormKit ships dedicated input types like `select`, `checkbox`, and `radio` that render their options from a prop:

```vue
<template>
  <FormKit
    type="select"
    name="framework"
    label="Framework"
    :options="{ vue: 'Vue', react: 'React' }"
  />
</template>
```

Formisch works with the native HTML elements instead. You render the options yourself and bind the field with `v-bind` and `v-model`:

```vue
<template>
  <Field :of="form" :path="['framework']" v-slot="field">
    <select v-bind="field.props" v-model="field.input">
      <option
        v-for="option in [
          { label: 'Vue', value: 'vue' },
          { label: 'React', value: 'react' },
        ]"
        :key="option.value"
        :value="option.value"
      >
        {{ option.label }}
      </option>
    </select>
  </Field>
</template>
```

Checkboxes, radio groups, and multi-selects follow the same pattern. File inputs are the exception: Vue does not allow `v-model` on them, so instead add an `input` handler that writes the selected file to `field.input` yourself. The [special inputs](/vue/guides/special-inputs.md) guide covers each of them, including checkbox groups that represent an array of strings.

#### Next steps

With your first form migrated, work through the main concepts to deepen your understanding: [define your form](/vue/guides/define-your-form.md), [add form fields](/vue/guides/add-form-fields.md), and [handle submission](/vue/guides/handle-submission.md). To rebuild the input scaffolding that FormKit provided, follow the [input components](/vue/guides/input-components.md) guide, and for programmatic control over your forms, explore the [form methods](/vue/guides/form-methods.md) guide.

### Migrate from TanStack Form

If your Vue forms are built with [TanStack Form](https://tanstack.com/form/latest) and you are considering a switch, this guide is for you. It explains how the two libraries differ, shows the same form implemented in both, and maps each TanStack Form API to its Formisch equivalent.

Migration is a rewrite of the form layer, not a drop-in replacement. Both libraries are headless and type-safe, but they build on different foundations, so the form setup, field bindings, and validation configuration change, while the components and markup around your forms usually stay the same.

The good news is that both libraries can coexist in the same application without conflict. You can install Formisch next to `@tanstack/vue-form` and migrate one form at a time instead of all at once. Since both libraries export a composable named `useForm`, the import path determines which one a component uses.

#### Key differences

TanStack Form infers your form's types from a `defaultValues` object and attaches validation separately through `validators` objects, either on the form or on individual fields. Each validator is bound to its own trigger such as `onChange`, `onBlur`, or `onSubmit`, with async variants and debouncing available per validator. Reactivity comes from TanStack Store: you subscribe to state explicitly with `form.useStore` selectors or the `form.Subscribe` component.

Formisch is schema-first. A single Valibot schema passed to the [`useForm`](/vue/api/useForm.md) composable is the source of types, validation rules, and form structure all at once. There is no `defaultValues` object to keep aligned with your types and no validator configuration scattered across fields. Validation always parses the entire form against the schema in one pass, and its timing is controlled form-wide with the `validate` and `revalidate` config.

In practice, the migration comes down to these shifts:

- **Source of truth**: `defaultValues` plus per-field validators become one Valibot schema.
- **Validation timing**: per-validator triggers become the form-wide `validate` and `revalidate` config.
- **Field addressing**: string names like `` `people[${i}].name` `` become path arrays like `['people', i, 'name']`.
- **Field binding**: manual `:value`, `@input`, and `@blur` wiring becomes `v-bind="field.props"` with `v-model`.
- **Reactivity**: explicit `form.useStore` and `form.Subscribe` subscriptions become direct property access on the reactive form store, powered by Vue's reactivity system.

If you already use TanStack Form's Standard Schema support with a Valibot schema, the mental gap is smaller than it looks. The difference is that in TanStack Form the schema is one of several possible validation sources, while in Formisch the schema is the form definition itself.

#### Side-by-side example

The following login form has two validated fields, displays error messages, and disables the submit button while the form is submitting. Both versions implement the same behavior.

##### TanStack Form

```vue
<script setup lang="ts">
import { useForm } from '@tanstack/vue-form';

const form = useForm({
  defaultValues: {
    email: '',
    password: '',
  },
  onSubmit: async ({ value }) => {
    console.log(value);
  },
});
</script>

<template>
  <form @submit.prevent.stop="form.handleSubmit">
    <form.Field
      name="email"
      :validators="{
        onBlur: ({ value }) =>
          !value
            ? 'Please enter your email.'
            : !value.includes('@')
              ? 'The email address is badly formatted.'
              : undefined,
      }"
    >
      <template v-slot="{ field }">
        <input
          type="email"
          :name="field.name"
          :value="field.state.value"
          @blur="field.handleBlur"
          @input="
            (e) => field.handleChange((e.target as HTMLInputElement).value)
          "
        />
        <div v-if="field.state.meta.errors.length">
          {{ field.state.meta.errors[0] }}
        </div>
      </template>
    </form.Field>
    <form.Field
      name="password"
      :validators="{
        onBlur: ({ value }) =>
          !value
            ? 'Please enter your password.'
            : value.length < 8
              ? 'Your password must have 8 characters or more.'
              : undefined,
      }"
    >
      <template v-slot="{ field }">
        <input
          type="password"
          :name="field.name"
          :value="field.state.value"
          @blur="field.handleBlur"
          @input="
            (e) => field.handleChange((e.target as HTMLInputElement).value)
          "
        />
        <div v-if="field.state.meta.errors.length">
          {{ field.state.meta.errors[0] }}
        </div>
      </template>
    </form.Field>
    <form.Subscribe>
      <template v-slot="{ canSubmit, isSubmitting }">
        <button type="submit" :disabled="!canSubmit">
          {{ isSubmitting ? 'Logging in...' : 'Login' }}
        </button>
      </template>
    </form.Subscribe>
  </form>
</template>
```

##### Formisch

```vue
<script setup lang="ts">
import { Field, Form, useForm } from '@formisch/vue';
import type { SubmitHandler } from '@formisch/vue';
import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
});

const loginForm = useForm({
  schema: LoginSchema,
  validate: 'blur',
});

const submitForm: SubmitHandler<typeof LoginSchema> = async (output) => {
  console.log(output);
};
</script>

<template>
  <Form :of="loginForm" @submit="submitForm">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <input v-bind="field.props" v-model="field.input" type="email" />
      <div v-if="field.errors">{{ field.errors[0] }}</div>
    </Field>
    <Field :of="loginForm" :path="['password']" v-slot="field">
      <input v-bind="field.props" v-model="field.input" type="password" />
      <div v-if="field.errors">{{ field.errors[0] }}</div>
    </Field>
    <button type="submit" :disabled="loginForm.isSubmitting">
      {{ loginForm.isSubmitting ? 'Logging in...' : 'Login' }}
    </button>
  </Form>
</template>
```

Note how the validation rules moved from the individual `form.Field` components into the schema, and how the manual event wiring collapsed into `v-bind="field.props"` with `v-model`. The `validate: 'blur'` config replaces the per-field `onBlur` triggers, so errors still first appear when a field loses focus.

#### Migration steps

##### Install Formisch

Add Formisch and Valibot alongside your existing setup. Both libraries can run in the same app during the migration.

```bash
npm install @formisch/vue valibot
```

See the [installation](/vue/guides/installation.md) guide for other package managers and TypeScript requirements.

##### Move validation into a Valibot schema

Collect the validation rules from your `validators` objects and express them as a single Valibot schema. Each field-level validator function typically becomes one or two pipe actions with the same error messages.

```ts
import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
});
```

If you already pass a Valibot schema to TanStack Form's `validators` option via Standard Schema, you can reuse it as is. Define the fields in the same order they appear in your form, since Formisch focuses the first invalid field on submit based on the schema order. See the [define your form](/vue/guides/define-your-form.md) guide for details on schema design.

##### Replace the form setup

Replace `useForm` from `@tanstack/vue-form` with the [`useForm`](/vue/api/useForm.md) composable from `@formisch/vue`. The schema replaces `defaultValues` entirely: types are inferred from it, and required string fields automatically start as empty strings. If you need prefilled values, pass a partial `initialInput`.

```ts
import { useForm } from '@formisch/vue';

const loginForm = useForm({
  schema: LoginSchema,
  initialInput: {
    email: 'user@example.com',
  },
});
```

Without further config, Formisch validates on submit. If your TanStack Form validators ran on blur or change, add the matching `validate` config, such as `validate: 'blur'` for the login form above, to preserve the timing (see the [validation timing](#validation-timing) section below).

The `onSubmit` option has no counterpart here. Submission moves to the template, as shown below. See the [create your form](/vue/guides/create-your-form.md) guide for all configuration options.

##### Replace field bindings

Replace each `form.Field` component with the [`Field`](/vue/api/Field.md) component. Instead of a string `name`, it takes the form store via `of` and a `path` array that is type-checked against your schema. The manual `:value`, `@input`, and `@blur` wiring is replaced by spreading `field.props` and binding `v-model` to `field.input`.

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <input v-bind="field.props" v-model="field.input" type="email" />
    <div v-if="field.errors">{{ field.errors[0] }}</div>
  </Field>
</template>
```

Error output changes from `field.state.meta.errors` to `field.errors`, which is either `null` or a non-empty array of strings. For single-field components, the [`useField`](/vue/api/useField.md) composable is the counterpart to TanStack Form's `useField`. See the [add form fields](/vue/guides/add-form-fields.md) guide for both approaches.

##### Update submission handling

Replace the native `<form>` element and its `@submit.prevent.stop="form.handleSubmit"` wiring with the [`Form`](/vue/api/Form.md) component, and move the logic from the `onSubmit` option into a handler passed to its `@submit` event. The handler only runs after successful validation and receives the fully typed, validated output. Calling `event.preventDefault()` is taken care of for you.

```vue
<script setup lang="ts">
import type { SubmitHandler } from '@formisch/vue';

const submitForm: SubmitHandler<typeof LoginSchema> = async (output) => {
  await login(output);
};
</script>

<template>
  <Form :of="loginForm" @submit="submitForm">
    <!-- Fields and submit button -->
  </Form>
</template>
```

Also remove the `form.Subscribe` wrapper around the submit button. The form store is reactive, so the button reads `loginForm.isSubmitting` directly, as shown in the side-by-side example and covered in the [form state](#form-state) section below.

See the [handle submission](/vue/guides/handle-submission.md) guide for async submission and programmatic submits.

#### API mapping

| TanStack Form                              | Formisch                                                                                                           |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `useForm({ defaultValues, onSubmit })`     | [`useForm({ schema })`](/vue/api/useForm.md)                                                        |
| `defaultValues`                            | `initialInput` (optional and partial)                                                                              |
| `onSubmit` option                          | `@submit` on the [`Form`](/vue/api/Form.md) component                                               |
| `form.handleSubmit`                        | [`submit`](/methods/api/submit.md) or [`handleSubmit`](/methods/api/handleSubmit.md) |
| `form.Field` with `name` string            | [`Field`](/vue/api/Field.md) with `path` array                                                      |
| `form.Field` with `mode="array"`           | [`FieldArray`](/vue/api/FieldArray.md)                                                              |
| `useField`                                 | [`useField`](/vue/api/useField.md)                                                                  |
| `field.state.value` + `field.handleChange` | `v-model="field.input"`                                                                                            |
| `field.handleBlur`                         | Included in `v-bind="field.props"`                                                                                 |
| `field.state.meta.errors`                  | `field.errors`                                                                                                     |
| `field.state.meta.isTouched`               | `field.isTouched`                                                                                                  |
| `field.state.meta.isDirty`                 | `field.isEdited`                                                                                                   |
| `field.state.meta.isDefaultValue`          | `!field.isDirty`                                                                                                   |
| `validators` with `onChange`, `onBlur`, …  | Valibot schema plus `validate` and `revalidate` config                                                             |
| `validators` with `onChangeAsync`          | Async schema with `v.pipeAsync` and `v.checkAsync`                                                                 |
| `form.useStore` and `form.Subscribe`       | Direct reactive property access, e.g. `loginForm.isValid`                                                          |
| `form.state.isSubmitting`                  | `form.isSubmitting`                                                                                                |
| `form.state.canSubmit`                     | No direct equivalent (see below)                                                                                   |
| `form.reset(values)`                       | [`reset(form, { initialInput })`](/methods/api/reset.md)                                            |
| `form.resetField(name)`                    | [`reset(form, { path })`](/methods/api/reset.md)                                                    |
| `form.setFieldValue(name, value)`          | [`setInput(form, { path, input })`](/methods/api/setInput.md)                                       |
| `form.getFieldValue(name)`                 | [`getInput(form, { path })`](/methods/api/getInput.md)                                              |
| `form.validateAllFields(cause)`            | [`validate(form)`](/methods/api/validate.md)                                                        |
| `field.pushValue(value)`                   | [`insert(form, { path, initialInput })`](/methods/api/insert.md)                                    |
| `field.removeValue(index)`                 | [`remove(form, { path, at })`](/methods/api/remove.md)                                              |
| `form.moveFieldValues(name, from, to)`     | [`move(form, { path, from, to })`](/methods/api/move.md)                                            |
| `form.swapFieldValues(name, i1, i2)`       | [`swap(form, { path, at, and })`](/methods/api/swap.md)                                             |
| `form.replaceFieldValue(name, i, value)`   | [`replace(form, { path, at, initialInput })`](/methods/api/replace.md)                              |

A few entries deserve extra context:

- **`canSubmit`**: Formisch has no combined flag. Forms stay submittable, validation runs on submit, blocks the handler when invalid, and automatically focuses the first field with an error. To prevent double submits, disable the button with `form.isSubmitting`. If you want a validity-based flag instead, `form.isValid` reflects the result of the last validation run, but with the default `validate: 'submit'` timing it stays `true` until the first submit, so combine it with `validate: 'initial'` for TanStack-like behavior.
- **`form.useStore` and `form.Subscribe`**: Formisch needs neither. The form store is reactive through Vue's reactivity system, so reading `form.isDirty` in a template or computed property subscribes automatically, and only what you read triggers updates.
- **`field.state.meta.errorMap`**: There is no per-trigger error map. Since validation always parses the whole schema, each field holds a single `errors` array.
- **Dirty semantics**: TanStack Form's `isDirty` stays `true` once a field was changed, even if the value is reverted. That matches Formisch's `isEdited`. Formisch's `isDirty` compares the current input against the initial input, matching the inverse of TanStack Form's `isDefaultValue`.
- **`listeners`**: For side effects on field changes, use Vue's `watch` with a reactive read, for example `watch(() => getInput(form, { path: ['country'] }), callback)`. Reading values with Formisch methods is reactive.

#### Common patterns

##### Form state

In TanStack Form, you subscribe to form state through selectors or the `form.Subscribe` component to keep re-renders scoped:

```vue
<template>
  <form.Subscribe>
    <template v-slot="{ isSubmitting }">
      <button type="submit" :disabled="isSubmitting">Submit</button>
    </template>
  </form.Subscribe>
</template>
```

In Formisch, the form store itself is reactive. Read `isSubmitting`, `isSubmitted`, `isValidating`, `isTouched`, `isEdited`, `isDirty`, `isValid`, and `errors` directly wherever you need them:

```vue
<template>
  <p v-if="loginForm.isDirty">You have unsaved changes.</p>
  <button type="submit" :disabled="loginForm.isSubmitting">Submit</button>
</template>
```

Note that `form.errors` only contains errors at the root level of the form. To collect the errors of all fields, use the [`getDeepErrors`](/methods/api/getDeepErrors.md) method.

##### Validation timing

TanStack Form binds timing to each validator: an `onBlur` validator runs on blur, an `onChange` validator on every change, and so on. Formisch configures timing once for the whole form:

```ts
const loginForm = useForm({
  schema: LoginSchema,
  validate: 'blur', // first validation of a field on blur
  revalidate: 'input', // revalidate on every keystroke afterwards
});
```

`validate` controls when a field is first validated (`'initial'`, `'touch'`, `'input'`, `'change'`, `'blur'`, or `'submit'`), and `revalidate` controls when it is validated again once it has an error or the form has been submitted. The defaults are `'submit'` and `'input'`.

Async validators like `onChangeAsync` move into the schema itself. Use `v.pipeAsync` with `v.checkAsync` for checks like username availability, and use the form's `isValidating` state, the counterpart to TanStack Form's `isValidating`, to indicate progress. The [validation](/vue/guides/validation.md) guide covers this in depth, including how to reveal errors only at the right moment.

##### Field arrays

In TanStack Form, you mark a field as an array with `mode="array"`, address items with interpolated name strings, and mutate the array through methods on the field:

```vue
<template>
  <form.Field name="people" mode="array">
    <template v-slot="{ field }">
      <div v-for="(_, i) of field.state.value" :key="i">
        <form.Field :name="`people[${i}].name`">
          <template v-slot="{ field: subField }">
            <input
              :value="subField.state.value"
              @input="
                (e) =>
                  subField.handleChange((e.target as HTMLInputElement).value)
              "
            />
          </template>
        </form.Field>
        <button type="button" @click="field.removeValue(i)">Remove</button>
      </div>
      <button type="button" @click="field.pushValue({ name: '' })">Add</button>
    </template>
  </form.Field>
</template>
```

In Formisch, the [`FieldArray`](/vue/api/FieldArray.md) component provides an `items` array of unique string identifiers to use as `v-for` keys, which keeps Vue's rendering correct when items are added, moved, or removed. Array mutations go through standalone methods:

```vue
<script setup lang="ts">
import { Field, FieldArray, insert, remove, useForm } from '@formisch/vue';
import * as v from 'valibot';

const PeopleSchema = v.object({
  people: v.array(v.object({ name: v.pipe(v.string(), v.nonEmpty()) })),
});

const peopleForm = useForm({ schema: PeopleSchema });
</script>

<template>
  <FieldArray :of="peopleForm" :path="['people']" v-slot="fieldArray">
    <div v-for="(item, index) in fieldArray.items" :key="item">
      <Field :of="peopleForm" :path="['people', index, 'name']" v-slot="field">
        <input v-bind="field.props" v-model="field.input" type="text" />
      </Field>
      <button
        type="button"
        @click="remove(peopleForm, { path: ['people'], at: index })"
      >
        Remove
      </button>
    </div>
    <button
      type="button"
      @click="
        insert(peopleForm, { path: ['people'], initialInput: { name: '' } })
      "
    >
      Add
    </button>
  </FieldArray>
</template>
```

The [`move`](/methods/api/move.md), [`swap`](/methods/api/swap.md), and [`replace`](/methods/api/replace.md) methods cover the remaining array operations. See the [field arrays](/vue/guides/field-arrays.md) guide for validation of the array itself and nested arrays.

##### Reset

TanStack Form resets through methods on the form instance:

```ts
form.reset(); // back to defaultValues
form.resetField('email'); // reset a single field
```

Formisch provides a standalone [`reset`](/methods/api/reset.md) method that can also establish a new baseline, which is useful when refreshed server data should become the new initial state:

```ts
import { reset } from '@formisch/vue';

// Reset the entire form to its initial input
reset(loginForm);

// Reset a single field
reset(loginForm, { path: ['email'] });

// Reset with a new baseline, e.g. after refreshing server data
reset(loginForm, { initialInput: { email: 'new@example.com' } });
```

Because resetting changes values programmatically, your inputs must be controlled with `v-model` as shown throughout this guide. See the [controlled fields](/vue/guides/controlled-fields.md) guide for details.

##### Special inputs

In TanStack Form, checkboxes, selects, and number inputs require manual wiring because `field.handleChange` receives whatever you extract from the event:

```vue
<input
  type="checkbox"
  :checked="field.state.value"
  @change="(e) => field.handleChange((e.target as HTMLInputElement).checked)"
  @blur="field.handleBlur"
/>
```

In Formisch, the combination of `v-bind="field.props"` and `v-model="field.input"` covers native input types without extra code:

```vue
<template>
  <Field :of="form" :path="['cookies']" v-slot="field">
    <label>
      <input type="checkbox" v-bind="field.props" v-model="field.input" />
      Yes, I want cookies
    </label>
  </Field>
</template>
```

The [special inputs](/vue/guides/special-inputs.md) guide covers checkboxes, checkbox groups, radio buttons, selects, and file inputs.

#### Next steps

With your first form migrated, work through the [define your form](/vue/guides/define-your-form.md) and [add form fields](/vue/guides/add-form-fields.md) guides to deepen your understanding of the schema-first approach. The [validation](/vue/guides/validation.md) guide explains how to fine-tune validation timing and error display, the [form methods](/vue/guides/form-methods.md) guide gives an overview of all available methods, and the [input components](/vue/guides/input-components.md) guide shows how to wrap the field bindings from this guide into reusable components.

## Integration guides

### shadcn-vue

[shadcn-vue](https://shadcn-vue.com) generates accessible components into your own project, where you can adapt them to your needs. This guide targets shadcn-vue v2 with its Reka UI v2 based components. No adapter package is needed: the input components behave like native elements, while the composite components take their value through `v-model` and the remaining field props individually.

#### Installation

Install Formisch and Valibot, then initialize shadcn-vue and add the components used below:

```bash
npm install @formisch/vue valibot
npx shadcn-vue@latest init
npx shadcn-vue@latest add button input textarea label checkbox select radio-group slider
```

If your `tsconfig.json` sets both `baseUrl` and `paths`, drop `baseUrl` and keep `paths` alone, since recent TypeScript versions report the combination as deprecated.

#### Wiring patterns

Choose the wiring from what the generated component renders:

- `Input` and `Textarea` keep the native element as their root and pass attributes through, so `v-model` plus the individual props reaches it directly.
- `Checkbox`, `Select`, `RadioGroup` and `Slider` wrap Reka UI primitives, so bind their value through `v-model` and forward the remaining props individually.

Note that `field.input` is a getter and setter rather than a method. Assigning it is what stores a value and runs validation, so `v-model` and an explicit `@update:model-value` handler are equivalent. Do not destructure the slot: write `v-slot="field"` rather than `v-slot="{ input }"`, because destructuring copies the value out of the accessor and assignments would go nowhere.

##### Spreading field.props

Never spread `field.props` onto a component. Vue treats the `ref` entry inside a `v-bind` object as a real template ref, so the spread would hand Formisch the component instance, and `focus` would fail on an object that has no `focus` method. Bind the entries individually and unwrap the root element for the reference:

```ts
function elementRef(register: (element: Element | null) => void) {
  return (instance: Element | ComponentPublicInstance | null) =>
    register(
      instance && '$el' in instance
        ? ((instance as ComponentPublicInstance).$el as Element | null)
        : (instance as Element | null)
    );
}
```

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <Input
      id="login-email"
      type="email"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      v-model="field.input"
      @focus="field.props.onFocus"
      @change="field.props.onChange"
      @blur="field.props.onBlur"
    />
  </Field>
</template>
```

##### Controlled components

The composite components are thin wrappers that forward both attributes and the element reference, so the same shape applies. Because each of them renders the focusable element as its root, unwrapping `$el` is enough for [`focus`](/methods/api/focus.md) and submit-time error focusing to reach the control:

```vue
<template>
  <Field :of="loginForm" :path="['rememberMe']" v-slot="field">
    <Checkbox
      id="login-remember-me"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      :model-value="field.input ?? false"
      @update:model-value="
        (value) => (field.input = value === 'indeterminate' ? false : value)
      "
      @focus="field.props.onFocus"
      @blur="field.props.onBlur"
    />
    <Label for="login-remember-me">Remember me</Label>
  </Field>
</template>
```

Forwarding `@focus` matters, because assigning `field.input` updates the value but only the focus handler marks the field as touched.

Assigning `field.input` runs input-mode validation, so a form configured with `validate: 'change'` does not validate these controls until submit. Use `validate: 'input'` if you want them validated as the value changes.

#### Displaying errors

Formisch exposes errors as `[string, ...string[]] | null`. Render the message yourself, give it a stable id and point the control at it while errors exist. `aria-invalid` also switches the generated components to their destructive styling:

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <Input
      id="login-email"
      :ref="elementRef(field.props.ref)"
      v-model="field.input"
      :aria-invalid="!!field.errors"
      aria-errormessage="login-email-error"
    />
    <p
      v-if="field.errors"
      id="login-email-error"
      class="text-destructive text-sm"
    >
      {{ field.errors[0] }}
    </p>
  </Field>
</template>
```

Use page-unique ids rather than the field name, because `field.props.name` is the JSON encoded path, such as `["email"]`.

By default, Formisch validates on submit and revalidates on input. The [validation guide](/vue/guides/validation.md) explains how to change that timing.

#### Login form example

This complete example combines two inputs, a controlled checkbox and accessible errors:

```vue
<script setup lang="ts">
import { Button } from '@/components/ui/button';
import { Checkbox } from '@/components/ui/checkbox';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Field, Form, type SubmitHandler, useForm } from '@formisch/vue';
import * as v from 'valibot';
import type { ComponentPublicInstance } from 'vue';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
  rememberMe: v.optional(v.boolean(), false),
});

const loginForm = useForm({
  schema: LoginSchema,
  initialInput: { email: '', password: '', rememberMe: false },
});

const handleSubmit: SubmitHandler<typeof LoginSchema> = (output) => {
  console.log(output);
};

// shadcn-vue components are wrappers, so the ref callback receives a component
// instance instead of a DOM node. Formisch calls `.focus()` on whatever it is
// given, so unwrap the root element before registering it.
function elementRef(register: (element: Element | null) => void) {
  return (instance: Element | ComponentPublicInstance | null) =>
    register(
      instance && '$el' in instance
        ? ((instance as ComponentPublicInstance).$el as Element | null)
        : (instance as Element | null)
    );
}
</script>

<template>
  <Form :of="loginForm" class="flex flex-col gap-4" @submit="handleSubmit">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <div class="flex flex-col gap-1">
        <Label for="login-email">Email</Label>
        <Input
          id="login-email"
          type="email"
          :ref="elementRef(field.props.ref)"
          :name="field.props.name"
          :autofocus="field.props.autofocus"
          v-model="field.input"
          :aria-invalid="!!field.errors"
          aria-errormessage="login-email-error"
          @focus="field.props.onFocus"
          @change="field.props.onChange"
          @blur="field.props.onBlur"
        />
        <p
          v-if="field.errors"
          id="login-email-error"
          class="text-destructive text-sm"
        >
          {{ field.errors[0] }}
        </p>
      </div>
    </Field>

    <Field :of="loginForm" :path="['password']" v-slot="field">
      <div class="flex flex-col gap-1">
        <Label for="login-password">Password</Label>
        <Input
          id="login-password"
          type="password"
          :ref="elementRef(field.props.ref)"
          :name="field.props.name"
          :autofocus="field.props.autofocus"
          v-model="field.input"
          :aria-invalid="!!field.errors"
          aria-errormessage="login-password-error"
          @focus="field.props.onFocus"
          @change="field.props.onChange"
          @blur="field.props.onBlur"
        />
        <p
          v-if="field.errors"
          id="login-password-error"
          class="text-destructive text-sm"
        >
          {{ field.errors[0] }}
        </p>
      </div>
    </Field>

    <Field :of="loginForm" :path="['rememberMe']" v-slot="field">
      <div class="flex items-center gap-2">
        <Checkbox
          id="login-remember-me"
          :ref="elementRef(field.props.ref)"
          :name="field.props.name"
          :autofocus="field.props.autofocus"
          :model-value="field.input ?? false"
          :aria-invalid="!!field.errors"
          @update:model-value="
            (value) => (field.input = value === 'indeterminate' ? false : value)
          "
          @focus="field.props.onFocus"
          @blur="field.props.onBlur"
        />
        <Label for="login-remember-me">Remember me</Label>
      </div>
    </Field>

    <Button type="submit" :disabled="loginForm.isSubmitting">Login</Button>
  </Form>
</template>
```

The initial input keeps every control defined from its first render. The inputs use `v-model` with the individual props, while the checkbox normalizes the indeterminate value before storing it.

#### Component reference

The following snippets assume a form store named `form`, initialized values that match the schema, and the `elementRef` helper from above.

##### Text input

`Input` keeps the native element as its root, so attributes and the reference reach it directly:

```vue
<template>
  <Field :of="form" :path="['email']" v-slot="field">
    <Label for="profile-email">Email</Label>
    <Input
      id="profile-email"
      type="email"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      v-model="field.input"
      :aria-invalid="!!field.errors"
      aria-errormessage="profile-email-error"
      @focus="field.props.onFocus"
      @change="field.props.onChange"
      @blur="field.props.onBlur"
    />
  </Field>
</template>
```

`Textarea` works the same way.

##### Checkbox

The component reports `boolean | 'indeterminate'`, so normalize the value before storing it:

```vue
<template>
  <Field :of="form" :path="['newsletter']" v-slot="field">
    <Checkbox
      id="settings-newsletter"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      :model-value="field.input ?? false"
      :aria-invalid="!!field.errors"
      @update:model-value="
        (value) => (field.input = value === 'indeterminate' ? false : value)
      "
      @focus="field.props.onFocus"
      @blur="field.props.onBlur"
    />
    <Label for="settings-newsletter">Newsletter</Label>
  </Field>
</template>
```

##### Select

Put the element reference and the lifecycle handlers on the trigger, which is the focusable part. Unlike Reka UI's primitive, the generated component drops the value type parameter, so narrow the payload to the schema union:

```vue
<template>
  <Field :of="form" :path="['framework']" v-slot="field">
    <Label id="project-framework-label" for="project-framework"
      >Framework</Label
    >
    <Select
      :name="field.props.name"
      :model-value="field.input"
      @update:model-value="(value) => (field.input = value as typeof field.input)"
    >
      <SelectTrigger
        id="project-framework"
        :ref="elementRef(field.props.ref)"
        :autofocus="field.props.autofocus"
        aria-labelledby="project-framework-label project-framework"
        :aria-invalid="!!field.errors"
        aria-errormessage="project-framework-error"
        @focus="field.props.onFocus"
        @blur="field.props.onBlur"
      >
        <SelectValue placeholder="Select a framework" />
      </SelectTrigger>
      <SelectContent>
        <SelectItem
          v-for="framework in frameworks"
          :key="framework.value"
          :value="framework.value"
        >
          {{ framework.label }}
        </SelectItem>
      </SelectContent>
    </Select>
  </Field>
</template>
```

##### Radio group

Register every item. Formisch keeps a list of registered elements, so each radio registers itself just like a native radio group:

```vue
<template>
  <Field :of="form" :path="['plan']" v-slot="field">
    <span id="plan-label" class="text-sm font-medium">Plan</span>
    <RadioGroup
      :name="field.props.name"
      :model-value="field.input"
      aria-labelledby="plan-label"
      :aria-invalid="!!field.errors"
      aria-errormessage="plan-error"
      @update:model-value="(value) => (field.input = value as 'hobby' | 'pro')"
    >
      <div
        v-for="plan in plans"
        :key="plan.value"
        class="flex items-center gap-2"
      >
        <RadioGroupItem
          :id="`plan-${plan.value}`"
          :ref="elementRef(field.props.ref)"
          :value="plan.value"
          :autofocus="field.props.autofocus"
          @focus="field.props.onFocus"
          @blur="field.props.onBlur"
        />
        <Label :for="`plan-${plan.value}`">{{ plan.label }}</Label>
      </div>
    </RadioGroup>
  </Field>
</template>
```

##### Slider

The generated `Slider` renders its thumbs internally without a slot, so attributes placed on it land on the track container rather than on the element that carries the `slider` role. Since the component lives in your project, add a `thumbProps` passthrough to `src/components/ui/slider/Slider.vue`. Extend its existing `defineProps` and keep the new prop out of what is forwarded to the root:

```ts
// Add `VNodeRef` to the existing `vue` type import
const props = defineProps<
  SliderRootProps & {
    class?: HTMLAttributes['class'];
    thumbProps?: HTMLAttributes & { autofocus?: boolean; ref?: VNodeRef };
  }
>();

const delegatedProps = reactiveOmit(props, 'class', 'thumbProps');
```

Then spread it onto the thumb in the same file:

```vue
<template>
  <SliderThumb
    v-for="(_, key) in modelValue"
    :key="key"
    data-slot="slider-thumb"
    v-bind="props.thumbProps"
  />
</template>
```

With that in place, the field wiring reads naturally. The value is an array, so wrap the number and unwrap it in the handler:

```vue
<template>
  <Field :of="form" :path="['volume']" v-slot="field">
    <Label for="settings-volume">Volume</Label>
    <Slider
      :name="field.props.name"
      :model-value="[field.input ?? 0]"
      :min="0"
      :max="100"
      :step="1"
      :thumb-props="{
        id: 'settings-volume',
        ref: elementRef(field.props.ref),
        autofocus: field.props.autofocus,
        'aria-label': 'Volume',
        'aria-invalid': !!field.errors,
        'aria-errormessage': 'settings-volume-error',
        onFocus: field.props.onFocus,
        onBlur: field.props.onBlur,
      }"
      @update:model-value="(value) => (field.input = value?.[0])"
    />
  </Field>
</template>
```

#### Library-specific notes

shadcn-vue also generates a `form` component, but it is built on VeeValidate and Zod. You do not need it with Formisch: use Formisch's [`Form`](/vue/api/Form.md) and [`Field`](/vue/api/Field.md) together with `Label` and your own error paragraph.

Because shadcn-vue builds on Reka UI, the wiring in our [Reka UI guide](/vue/guides/reka-ui.md) applies to the primitives underneath. The difference is that you own the generated source, so a missing prop can be forwarded rather than worked around.

`field.props.autofocus` is a snapshot taken when the field mounts, not a reactive value. Formisch moves focus to the first invalid field after a failed submit on its own.

#### Next steps

Read the [input components](/vue/guides/input-components.md) guide to package repeated wiring into reusable controls, the [controlled fields](/vue/guides/controlled-fields.md) guide for the underlying pattern, and the [validation](/vue/guides/validation.md) guide for validation timing.

### Ark UI

[Ark UI](https://ark-ui.com) is a headless component library built on state machines, available for Vue among other frameworks. This guide targets Ark UI v5 for Vue. No adapter package is needed, and Ark handles more of the accessibility wiring than most libraries: inside its `Field`, the label association, `aria-invalid` and the error message reference are derived for you.

#### Installation

Install Formisch, Valibot and Ark UI:

```bash
npm install @formisch/vue valibot @ark-ui/vue
```

Ark UI ships unstyled, so every example below leaves styling to you.

#### Wiring patterns

Every Ark UI part is a Vue component rather than a plain element, so there is only one pattern here: bind the field entries individually. Never use `v-bind="field.props"`, not even on a text input. Vue treats the `ref` entry inside that object as a real template ref, so the spread would hand Formisch the component instance, and `focus` would fail on an object that has no `focus` method.

Because the parts are components, the element reference always needs unwrapping. Every Ark part exposes its real DOM node as `$el`, so one small helper covers all of them:

```ts
function elementRef(register: (element: Element | null) => void) {
  return (instance: Element | ComponentPublicInstance | null) =>
    register(
      instance && '$el' in instance
        ? ((instance as ComponentPublicInstance).$el as Element | null)
        : (instance as Element | null)
    );
}
```

Note also that `field.input` is a getter and setter rather than a method. Assigning it is what stores a value and runs validation. Do not destructure the slot: write `v-slot="field"` rather than `v-slot="{ input }"`, because destructuring copies the value out of the accessor and assignments would go nowhere.

##### Text fields

`Field.Input` wraps a native input, so it accepts `v-model` and forwards the lifecycle handlers to the element. Since Formisch and Ark UI both export a `Field`, the Ark one is imported as `ArkField`:

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <ArkField.Root id="login-email" :invalid="!!field.errors">
      <ArkField.Label>Email</ArkField.Label>
      <ArkField.Input
        :ref="elementRef(field.props.ref)"
        v-model="field.input"
        :name="field.props.name"
        :autofocus="field.props.autofocus"
        type="email"
        @focus="field.props.onFocus"
        @change="field.props.onChange"
        @blur="field.props.onBlur"
      />
      <ArkField.ErrorText>{{ field.errors?.[0] }}</ArkField.ErrorText>
    </ArkField.Root>
  </Field>
</template>
```

The component accepts `modelValue` rather than `value`, so `v-model` is the way to bind it. Set the `id` on `ArkField.Root` rather than on the input, because Ark derives the control id and the label's `for` from it.

##### Controlled components

A composite component owns its value, so bind `modelValue` and handle the change event, then forward the lifecycle props to its hidden native part. Registering that part is what keeps [`focus`](/methods/api/focus.md) and submit-time error focusing working:

```vue
<template>
  <Field :of="loginForm" :path="['rememberMe']" v-slot="field">
    <Checkbox.Root
      :ids="{ hiddenInput: 'login-remember-me' }"
      :name="field.props.name"
      :checked="field.input ?? false"
      :invalid="!!field.errors"
      @checked-change="(details) => (field.input = details.checked === true)"
    >
      <Checkbox.HiddenInput
        :ref="elementRef(field.props.ref)"
        :autofocus="field.props.autofocus"
        @focus="field.props.onFocus"
        @blur="field.props.onBlur"
      />
      <Checkbox.Control>
        <Checkbox.Indicator>✓</Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label>Remember me</Checkbox.Label>
    </Checkbox.Root>
  </Field>
</template>
```

`Checkbox.HiddenInput` is not optional: without it the checkbox does not react to clicks at all. Ark exposes its events as kebab-case emits, so the handler is `@checked-change` rather than a callback prop, and its payload can be `'indeterminate'`, which is normalized above.

Prefer these explicit handlers over `v-model` on a composite root. Vue rejects `v-model` outright on the array based `Select.Root` and `Slider.Root`, and while it compiles on `Checkbox.Root` and `RadioGroup.Root`, it does not typecheck the write direction, so an indeterminate state or a `null` selection would flow into your field unchecked.

Every Ark root also accepts an `ids` object, which is the supported way to give a hidden part a stable id. Setting `id` directly on a hidden part instead leaves the generated label pointing at the old value.

Assigning `field.input` runs input-mode validation, so a form configured with `validate: 'change'` does not validate these controls until submit. Use `validate: 'input'` if you want them validated as the value changes.

#### Displaying errors

Formisch exposes errors as `[string, ...string[]] | null`. Inside `ArkField.Root`, pass `invalid` and render the message in `ArkField.ErrorText`. Ark adds `aria-invalid` and wires the error reference for you, and the text only renders while the field is invalid:

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <ArkField.Root
      id="login-email"
      :ids="{ errorText: 'login-email-error' }"
      :invalid="!!field.errors"
    >
      <ArkField.Label>Email</ArkField.Label>
      <ArkField.Input
        :ref="elementRef(field.props.ref)"
        v-model="field.input"
      />
      <ArkField.ErrorText>{{ field.errors?.[0] }}</ArkField.ErrorText>
    </ArkField.Root>
  </Field>
</template>
```

Only `Field` has an error part. `Select`, `RadioGroup` and `Slider` have none, so render the message yourself and point the visible control at it with `aria-errormessage`. Use page-unique ids rather than the field name, because `field.props.name` is the JSON encoded path, such as `["email"]`.

By default, Formisch validates on submit and revalidates on input. The [validation guide](/vue/guides/validation.md) explains how to change that timing.

#### Login form example

This complete example combines two text fields, a controlled checkbox and accessible errors:

```vue
<script setup lang="ts">
import { Checkbox } from '@ark-ui/vue/checkbox';
import { Field as ArkField } from '@ark-ui/vue/field';
import { Field, Form, type SubmitHandler, useForm } from '@formisch/vue';
import * as v from 'valibot';
import type { ComponentPublicInstance } from 'vue';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
  rememberMe: v.optional(v.boolean(), false),
});

const loginForm = useForm({
  schema: LoginSchema,
  initialInput: { email: '', password: '', rememberMe: false },
});

const handleSubmit: SubmitHandler<typeof LoginSchema> = (output) => {
  console.log(output);
};

// Every Ark UI part is a Vue component, so the ref callback receives a
// component instance. Formisch calls `.focus()` on whatever it gets, so
// unwrap the root DOM element before registering it.
function elementRef(register: (element: Element | null) => void) {
  return (instance: Element | ComponentPublicInstance | null) =>
    register(
      instance && '$el' in instance
        ? ((instance as ComponentPublicInstance).$el as Element | null)
        : (instance as Element | null)
    );
}
</script>

<template>
  <Form :of="loginForm" @submit="handleSubmit">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <ArkField.Root
        id="login-email"
        :ids="{ errorText: 'login-email-error' }"
        :invalid="!!field.errors"
      >
        <ArkField.Label>Email</ArkField.Label>
        <ArkField.Input
          :ref="elementRef(field.props.ref)"
          v-model="field.input"
          :name="field.props.name"
          :autofocus="field.props.autofocus"
          type="email"
          autocomplete="email"
          placeholder="jane@example.com"
          @focus="field.props.onFocus"
          @change="field.props.onChange"
          @blur="field.props.onBlur"
        />
        <ArkField.ErrorText>{{ field.errors?.[0] }}</ArkField.ErrorText>
      </ArkField.Root>
    </Field>

    <Field :of="loginForm" :path="['password']" v-slot="field">
      <ArkField.Root
        id="login-password"
        :ids="{ errorText: 'login-password-error' }"
        :invalid="!!field.errors"
      >
        <ArkField.Label>Password</ArkField.Label>
        <ArkField.Input
          :ref="elementRef(field.props.ref)"
          v-model="field.input"
          :name="field.props.name"
          :autofocus="field.props.autofocus"
          type="password"
          autocomplete="current-password"
          @focus="field.props.onFocus"
          @change="field.props.onChange"
          @blur="field.props.onBlur"
        />
        <ArkField.ErrorText>{{ field.errors?.[0] }}</ArkField.ErrorText>
      </ArkField.Root>
    </Field>

    <Field :of="loginForm" :path="['rememberMe']" v-slot="field">
      <Checkbox.Root
        :ids="{ hiddenInput: 'login-remember-me' }"
        :name="field.props.name"
        :checked="field.input ?? false"
        :invalid="!!field.errors"
        @checked-change="(details) => (field.input = details.checked === true)"
      >
        <Checkbox.HiddenInput
          :ref="elementRef(field.props.ref)"
          :autofocus="field.props.autofocus"
          @focus="field.props.onFocus"
          @blur="field.props.onBlur"
        />
        <Checkbox.Control>
          <Checkbox.Indicator>✓</Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Label>Remember me</Checkbox.Label>
      </Checkbox.Root>
    </Field>

    <button type="submit" :disabled="loginForm.isSubmitting">Login</button>
  </Form>
</template>
```

The initial input keeps every control defined from its first render. Since `Field.Input` wraps a real native element, `@change` is worth forwarding there. On the composite controls it has nothing to fire on, so it stays unwired.

#### Component reference

The following snippets assume a form store named `form`, initialized values that match the schema, and the `elementRef` helper from above.

##### Text input

```vue
<template>
  <Field :of="form" :path="['email']" v-slot="field">
    <ArkField.Root
      id="profile-email"
      :ids="{ errorText: 'profile-email-error' }"
      :invalid="!!field.errors"
    >
      <ArkField.Label>Email</ArkField.Label>
      <ArkField.Input
        :ref="elementRef(field.props.ref)"
        v-model="field.input"
        :name="field.props.name"
        :autofocus="field.props.autofocus"
        type="email"
        @focus="field.props.onFocus"
        @change="field.props.onChange"
        @blur="field.props.onBlur"
      />
      <ArkField.ErrorText>{{ field.errors?.[0] }}</ArkField.ErrorText>
    </ArkField.Root>
  </Field>
</template>
```

Swap `ArkField.Input` for `ArkField.Textarea` to get a multiline field with the same wiring.

##### Checkbox

```vue
<template>
  <Field :of="form" :path="['newsletter']" v-slot="field">
    <Checkbox.Root
      :ids="{ hiddenInput: 'settings-newsletter' }"
      :name="field.props.name"
      :checked="field.input ?? false"
      :invalid="!!field.errors"
      @checked-change="(details) => (field.input = details.checked === true)"
    >
      <Checkbox.HiddenInput
        :ref="elementRef(field.props.ref)"
        :autofocus="field.props.autofocus"
        @focus="field.props.onFocus"
        @blur="field.props.onBlur"
      />
      <Checkbox.Control>
        <Checkbox.Indicator>✓</Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label>Newsletter</Checkbox.Label>
    </Checkbox.Root>
  </Field>
</template>
```

##### Select

Ark's select is array based even for a single selection, so wrap the value and unwrap the payload, narrowing it to the schema union. Items come from a collection, and since Ark UI for Vue exports no portal component, Vue's own `Teleport` positions the popup:

```ts
const frameworkCollection = createListCollection({
  items: [
    { label: 'Angular', value: 'angular' },
    { label: 'React', value: 'react' },
    { label: 'Solid', value: 'solid' },
    { label: 'Vue', value: 'vue' },
  ],
});
```

```vue
<template>
  <Field :of="form" :path="['framework']" v-slot="field">
    <Select.Root
      :ids="{
        trigger: 'project-framework',
        hiddenSelect: 'project-framework-select',
      }"
      :collection="frameworkCollection"
      :name="field.props.name"
      :model-value="field.input ? [field.input] : []"
      :invalid="!!field.errors"
      @value-change="
        (details) => (field.input = details.value[0] as typeof field.input)
      "
    >
      <Select.Label>Framework</Select.Label>
      <Select.Control>
        <Select.Trigger
          :autofocus="field.props.autofocus"
          aria-errormessage="project-framework-error"
          @focus="field.props.onFocus"
          @blur="field.props.onBlur"
        >
          <Select.ValueText placeholder="Select a framework" />
          <Select.Indicator>▾</Select.Indicator>
        </Select.Trigger>
      </Select.Control>
      <Select.HiddenSelect :ref="elementRef(field.props.ref)" />
      <span v-if="field.errors" id="project-framework-error">
        {{ field.errors[0] }}
      </span>
      <Teleport to="body">
        <Select.Positioner>
          <Select.Content>
            <Select.Item
              v-for="item in frameworkCollection.items"
              :key="item.value"
              :item="item"
            >
              <Select.ItemText>{{ item.label }}</Select.ItemText>
            </Select.Item>
          </Select.Content>
        </Select.Positioner>
      </Teleport>
    </Select.Root>
  </Field>
</template>
```

Put the focus handlers on the trigger rather than on the hidden select, because that is the element a keyboard user lands on. `focus` still works, since Ark forwards focus from the hidden select to the visible trigger.

##### Radio group

Register every item's hidden input. Formisch keeps a list of registered elements, so each radio registers itself just like a native radio group. Put `autofocus` on the first item only, otherwise every radio competes for focus:

```vue
<template>
  <Field :of="form" :path="['plan']" v-slot="field">
    <RadioGroup.Root
      :ids="{ itemHiddenInput: (value) => `plan-${value}` }"
      :name="field.props.name"
      :model-value="field.input ?? null"
      :invalid="!!field.errors"
      aria-errormessage="plan-error"
      @value-change="(details) => (field.input = details.value as 'hobby' | 'pro')"
    >
      <RadioGroup.Label>Plan</RadioGroup.Label>
      <RadioGroup.Item
        v-for="(plan, index) in plans"
        :key="plan.value"
        :value="plan.value"
      >
        <RadioGroup.ItemHiddenInput
          :ref="elementRef(field.props.ref)"
          :autofocus="index === 0 && field.props.autofocus"
          :aria-invalid="field.errors ? true : undefined"
          @focus="field.props.onFocus"
          @blur="field.props.onBlur"
        />
        <RadioGroup.ItemControl />
        <RadioGroup.ItemText>{{ plan.label }}</RadioGroup.ItemText>
      </RadioGroup.Item>
      <span v-if="field.errors" id="plan-error">{{ field.errors[0] }}</span>
    </RadioGroup.Root>
  </Field>
</template>
```

##### Slider

Ark's slider is array based like its select, and it uses `min` and `max` rather than `minValue` and `maxValue`. One `Slider.Thumb` renders exactly one thumb, and `Slider.Label` names it for you:

```vue
<template>
  <Field :of="form" :path="['volume']" v-slot="field">
    <Slider.Root
      :ids="{ thumb: () => 'settings-volume-thumb' }"
      :name="field.props.name"
      :min="0"
      :max="100"
      :step="1"
      :model-value="[field.input ?? 50]"
      :invalid="!!field.errors"
      @value-change="(details) => (field.input = details.value[0])"
    >
      <Slider.Label>Volume</Slider.Label>
      <Slider.ValueText />
      <Slider.Control>
        <Slider.Track>
          <Slider.Range />
        </Slider.Track>
        <Slider.Thumb
          :index="0"
          :autofocus="field.props.autofocus"
          aria-errormessage="settings-volume-error"
          @focus="field.props.onFocus"
          @blur="field.props.onBlur"
        >
          <Slider.HiddenInput :ref="elementRef(field.props.ref)" />
        </Slider.Thumb>
      </Slider.Control>
      <span v-if="field.errors" id="settings-volume-error">
        {{ field.errors[0] }}
      </span>
    </Slider.Root>
  </Field>
</template>
```

`Slider.HiddenInput` renders with the `hidden` attribute, which makes it unfocusable, so `focus` cannot move focus to this field. Keyboard users still reach the thumb normally, and validation, `isTouched` and blur validation are unaffected.

#### Library-specific notes

`field.props.autofocus` is a snapshot taken when the field mounts, not a reactive value. Formisch moves focus to the first invalid field after a failed submit on its own.

Ark UI is also available for other frameworks. The part names and the `ids` and `invalid` props are identical there, so this wiring ports with only the framework API changing. See our [React](/react/guides/ark-ui.md), [Solid](/solid/guides/ark-ui.md) and [Svelte](/svelte/guides/ark-ui.md) guides.

If you prefer a library where native elements stay plain elements, our [Reka UI guide](/vue/guides/reka-ui.md) covers that style, at the cost of writing the accessibility attributes yourself.

#### Next steps

Read the [input components](/vue/guides/input-components.md) guide to package repeated wiring into reusable controls, the [controlled fields](/vue/guides/controlled-fields.md) guide for the underlying pattern, and the [validation](/vue/guides/validation.md) guide for validation timing.

### Reka UI

[Reka UI](https://reka-ui.com) is a collection of headless, accessible primitives for Vue. This guide targets Reka UI v2. No adapter package is needed: native elements take the `field.props` spread together with `v-model`, while a primitive receives its value through `v-model` and the remaining props individually.

#### Installation

Install Formisch, Valibot and Reka UI:

```bash
npm install @formisch/vue valibot reka-ui
```

Reka UI ships primitives only, so text inputs, textareas and buttons stay native elements that you style yourself.

#### Wiring patterns

Choose the wiring from what you are rendering:

- On a native element, spread `field.props` and bind the value with `v-model="field.input"`.
- On a component, bind the props individually and normalize the element reference, because a spread would register the component instance instead of a DOM node.

Note that `field.input` is a getter and setter rather than a method. Assigning it is what stores a value and runs validation, so `v-model` and an explicit `@update:model-value` handler are equivalent. Do not destructure the slot: write `v-slot="field"` rather than `v-slot="{ input }"`, because destructuring copies the value out of the accessor and assignments would go nowhere.

##### Spreading field.props

A native input takes both bindings at once. They cannot collide: `v-model` listens for the `input` event, while the spread installs its handler on `change`:

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <input
      v-bind="field.props"
      id="login-email"
      v-model="field.input"
      type="email"
    />
  </Field>
</template>
```

##### Controlled components

Do not spread `field.props` onto a component. Vue treats the `ref` entry inside a `v-bind` object as a real template ref, so the spread would hand Formisch the component instance, and `focus` would fail on an object that has no `focus` method. Bind the entries individually and unwrap the root element for the reference:

```ts
function elementRef(register: (element: Element | null) => void) {
  return (instance: Element | ComponentPublicInstance | null) =>
    register(
      instance && '$el' in instance
        ? ((instance as ComponentPublicInstance).$el as Element | null)
        : (instance as Element | null)
    );
}
```

```vue
<template>
  <Field :of="loginForm" :path="['rememberMe']" v-slot="field">
    <CheckboxRoot
      id="login-remember-me"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      :model-value="field.input ?? false"
      @update:model-value="
        (value) => (field.input = value === 'indeterminate' ? false : value)
      "
      @focus="field.props.onFocus"
      @blur="field.props.onBlur"
    >
      <CheckboxIndicator>✓</CheckboxIndicator>
    </CheckboxRoot>
    <label for="login-remember-me">Remember me</label>
  </Field>
</template>
```

Reka UI renders each of these primitives with the focusable element as its root, so unwrapping `$el` is enough for [`focus`](/methods/api/focus.md) and submit-time error focusing to reach the control. Forwarding `@focus` matters too, because assigning `field.input` updates the value but only the focus handler marks the field as touched.

#### Displaying errors

Formisch exposes errors as `[string, ...string[]] | null`. Reka UI has no error primitive, so render the message yourself, give it a stable id and point the control at it while errors exist:

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <input
      v-bind="field.props"
      id="login-email"
      v-model="field.input"
      :aria-invalid="!!field.errors"
      aria-errormessage="login-email-error"
    />
    <div v-if="field.errors" id="login-email-error">{{ field.errors[0] }}</div>
  </Field>
</template>
```

Use page-unique ids rather than the field name. `field.props.name` is the JSON encoded path, such as `["email"]`, which is meant for form submission and not for `for` and `id` attributes.

By default, Formisch validates on submit and revalidates on input. The [validation guide](/vue/guides/validation.md) explains how to change that timing.

#### Login form example

This complete example combines native inputs, a controlled checkbox and accessible errors:

```vue
<script setup lang="ts">
import { Field, Form, type SubmitHandler, useForm } from '@formisch/vue';
import { CheckboxIndicator, CheckboxRoot } from 'reka-ui';
import * as v from 'valibot';
import type { ComponentPublicInstance } from 'vue';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
  rememberMe: v.optional(v.boolean(), false),
});

const loginForm = useForm({
  schema: LoginSchema,
  initialInput: { email: '', password: '', rememberMe: false },
});

const handleSubmit: SubmitHandler<typeof LoginSchema> = (output) => {
  console.log(output);
};

// Reka UI renders composite controls as components, so the ref callback
// receives a component instance. Formisch calls `.focus()` on whatever it
// gets, so unwrap the root DOM element before registering it.
function elementRef(register: (element: Element | null) => void) {
  return (instance: Element | ComponentPublicInstance | null) =>
    register(
      instance && '$el' in instance
        ? ((instance as ComponentPublicInstance).$el as Element | null)
        : (instance as Element | null)
    );
}
</script>

<template>
  <Form :of="loginForm" @submit="handleSubmit">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <div>
        <label for="login-email">Email</label>
        <input
          v-bind="field.props"
          id="login-email"
          v-model="field.input"
          type="email"
          :aria-invalid="!!field.errors"
          aria-errormessage="login-email-error"
        />
        <div v-if="field.errors" id="login-email-error">
          {{ field.errors[0] }}
        </div>
      </div>
    </Field>

    <Field :of="loginForm" :path="['password']" v-slot="field">
      <div>
        <label for="login-password">Password</label>
        <input
          v-bind="field.props"
          id="login-password"
          v-model="field.input"
          type="password"
          :aria-invalid="!!field.errors"
          aria-errormessage="login-password-error"
        />
        <div v-if="field.errors" id="login-password-error">
          {{ field.errors[0] }}
        </div>
      </div>
    </Field>

    <Field :of="loginForm" :path="['rememberMe']" v-slot="field">
      <div>
        <CheckboxRoot
          id="login-remember-me"
          :ref="elementRef(field.props.ref)"
          :name="field.props.name"
          :autofocus="field.props.autofocus"
          :model-value="field.input ?? false"
          :aria-invalid="!!field.errors"
          @update:model-value="
            (value) => (field.input = value === 'indeterminate' ? false : value)
          "
          @focus="field.props.onFocus"
          @blur="field.props.onBlur"
        >
          <CheckboxIndicator>✓</CheckboxIndicator>
        </CheckboxRoot>
        <label for="login-remember-me">Remember me</label>
      </div>
    </Field>

    <button type="submit" :disabled="loginForm.isSubmitting">Login</button>
  </Form>
</template>
```

The initial input keeps every control defined from its first render. The two inputs use the spread with `v-model`, while the checkbox binds its props individually and normalizes the element reference.

#### Component reference

The following snippets assume a form store named `form`, initialized values that match the schema, and the `elementRef` helper from above.

##### Text input

Native elements take the whole spread:

```vue
<template>
  <Field :of="form" :path="['email']" v-slot="field">
    <label for="profile-email">Email</label>
    <input
      v-bind="field.props"
      id="profile-email"
      v-model="field.input"
      type="email"
      :aria-invalid="!!field.errors"
      aria-errormessage="profile-email-error"
    />
    <div v-if="field.errors" id="profile-email-error">
      {{ field.errors[0] }}
    </div>
  </Field>
</template>
```

A `<textarea>` works the same way. For a `v.number()` field, `v-model` on `<input type="number" />` already stores a number, so the `.number` modifier is unnecessary.

##### Checkbox

`CheckboxRoot` reports `boolean | 'indeterminate'`, so normalize the value before storing it:

```vue
<template>
  <Field :of="form" :path="['newsletter']" v-slot="field">
    <CheckboxRoot
      id="settings-newsletter"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      :model-value="field.input ?? false"
      :aria-invalid="!!field.errors"
      @update:model-value="
        (value) => (field.input = value === 'indeterminate' ? false : value)
      "
      @focus="field.props.onFocus"
      @blur="field.props.onBlur"
    >
      <CheckboxIndicator>✓</CheckboxIndicator>
    </CheckboxRoot>
    <label for="settings-newsletter">Newsletter</label>
  </Field>
</template>
```

The primitive renders a button, which a `<label>` cannot name on its own. Reka UI solves this for you: given an `id`, it derives the accessible name from the matching label element.

##### Select

`SelectRoot` infers its value type from `modelValue`, so no cast is needed. Put the element reference and the lifecycle handlers on the trigger, which is the focusable part:

```vue
<template>
  <Field :of="form" :path="['framework']" v-slot="field">
    <label id="project-framework-label" for="project-framework"
      >Framework</label
    >
    <SelectRoot
      :name="field.props.name"
      :model-value="field.input"
      @update:model-value="(value) => (field.input = value)"
    >
      <SelectTrigger
        id="project-framework"
        :ref="elementRef(field.props.ref)"
        :autofocus="field.props.autofocus"
        aria-labelledby="project-framework-label project-framework"
        :aria-invalid="!!field.errors"
        aria-errormessage="project-framework-error"
        @focus="field.props.onFocus"
        @blur="field.props.onBlur"
      >
        <SelectValue placeholder="Select a framework" />
      </SelectTrigger>
      <SelectPortal>
        <SelectContent position="popper" :side-offset="4">
          <SelectViewport>
            <SelectItem
              v-for="framework in frameworks"
              :key="framework.value"
              :value="framework.value"
            >
              <SelectItemText>{{ framework.label }}</SelectItemText>
            </SelectItem>
          </SelectViewport>
        </SelectContent>
      </SelectPortal>
    </SelectRoot>
  </Field>
</template>
```

`SelectContent` renders in a portal, so give it a background and a stacking context, otherwise the options are unclickable.

##### Radio group

Register every item. Formisch keeps a list of registered elements, so each radio registers itself just like a native radio group. Unlike the select, the group's payload includes `null`, so narrow it to the schema union:

```vue
<template>
  <Field :of="form" :path="['plan']" v-slot="field">
    <span id="plan-label">Plan</span>
    <RadioGroupRoot
      :name="field.props.name"
      :model-value="field.input"
      aria-labelledby="plan-label"
      :aria-invalid="!!field.errors"
      aria-errormessage="plan-error"
      @update:model-value="(value) => (field.input = value as 'hobby' | 'pro')"
    >
      <div v-for="plan in plans" :key="plan.value">
        <RadioGroupItem
          :id="`plan-${plan.value}`"
          :ref="elementRef(field.props.ref)"
          :value="plan.value"
          :autofocus="field.props.autofocus"
          @focus="field.props.onFocus"
          @blur="field.props.onBlur"
        >
          <RadioGroupIndicator />
        </RadioGroupItem>
        <label :for="`plan-${plan.value}`">{{ plan.label }}</label>
      </div>
    </RadioGroupRoot>
  </Field>
</template>
```

##### Slider

`SliderRoot` works with an array of values, so wrap the number for the single thumb and unwrap it in the handler. One `SliderThumb` renders exactly one `slider` role, and Reka UI does not derive a name for it, so set `aria-label` yourself:

```vue
<template>
  <Field :of="form" :path="['volume']" v-slot="field">
    <label id="settings-volume-label">Volume</label>
    <SliderRoot
      :name="field.props.name"
      :model-value="[field.input ?? 0]"
      :min="0"
      :max="100"
      :step="1"
      @update:model-value="(value) => (field.input = value?.[0])"
    >
      <SliderTrack>
        <SliderRange />
      </SliderTrack>
      <SliderThumb
        id="settings-volume"
        :ref="elementRef(field.props.ref)"
        :autofocus="field.props.autofocus"
        aria-label="Volume"
        :aria-invalid="!!field.errors"
        aria-errormessage="settings-volume-error"
        @focus="field.props.onFocus"
        @blur="field.props.onBlur"
      />
    </SliderRoot>
  </Field>
</template>
```

#### Library-specific notes

Passing `name` makes Reka UI render a hidden native control so the value takes part in a native form submission. Formisch submits from its own store, so these extra nodes are harmless.

`field.props.onChange` only triggers change-mode validation and never writes a value. Under the default settings it never fires, so the primitives above leave it unwired. Assigning `field.input` runs input-mode validation, so a form configured with `validate: 'change'` does not validate these controls until submit; use `validate: 'input'` if you want them validated as the value changes.

`field.props.autofocus` is a snapshot taken when the field mounts, not a reactive value. Formisch moves focus to the first invalid field after a failed submit on its own.

#### Next steps

Read the [input components](/vue/guides/input-components.md) guide to package repeated wiring into reusable controls, the [controlled fields](/vue/guides/controlled-fields.md) guide for the underlying pattern, and the [validation](/vue/guides/validation.md) guide for validation timing.

### PrimeVue

[PrimeVue](https://primevue.org) is a full featured component library for Vue with a large set of styled form controls. This guide targets PrimeVue v5. No adapter package is needed: every component binds its value with `v-model`, and the remaining field props are bound individually, sometimes through the component's pass through API.

#### Installation

Install Formisch, Valibot and PrimeVue, then register a theme as described in the [PrimeVue setup guide](https://primevue.org/vite):

```bash
npm install @formisch/vue valibot primevue @primeuix/themes
```

#### Wiring patterns

Choose the wiring from where the component keeps its focusable element:

- `InputText` and `Textarea` render the native element as their root, so `v-model` plus the individual props reaches it directly.
- `Checkbox`, `RadioButton`, `Select`, `Slider` and `Password` wrap their control in a styled element, so the element reference has to reach the inner control and some props travel through `pt`.

Note that `field.input` is a getter and setter rather than a method. Assigning it is what stores a value and runs validation, so `v-model` and an explicit `@update:model-value` handler are equivalent. Do not destructure the slot: write `v-slot="field"` rather than `v-slot="{ input }"`, because destructuring copies the value out of the accessor and assignments would go nowhere.

##### Spreading field.props

Never spread `field.props` onto a PrimeVue component. Vue treats the `ref` entry inside a `v-bind` object as a real template ref, so the spread would hand Formisch the component instance, and `focus` would fail on an object that has no `focus` method. Bind the entries individually instead:

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <InputText
      id="login-email"
      type="email"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      v-model="field.input"
      :invalid="!!field.errors"
      @focus="field.props.onFocus"
      @change="field.props.onChange"
      @blur="field.props.onBlur"
    />
  </Field>
</template>
```

##### Controlled components

Because most PrimeVue components wrap their control, the reference helper looks for the focusable element inside the root. Registering the real control is what keeps [`focus`](/methods/api/focus.md) and submit-time error focusing working:

```ts
const FOCUSABLE = 'input, select, textarea, [tabindex]';

function elementRef(register: (element: Element | null) => void) {
  return (instance: Element | ComponentPublicInstance | null) => {
    const root = (
      instance && '$el' in instance ? instance.$el : instance
    ) as HTMLElement | null;
    register(
      root?.matches(FOCUSABLE) ? root : (root?.querySelector(FOCUSABLE) ?? root)
    );
  };
}
```

```vue
<template>
  <Field :of="loginForm" :path="['rememberMe']" v-slot="field">
    <Checkbox
      input-id="login-remember-me"
      binary
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :model-value="field.input ?? false"
      :invalid="!!field.errors"
      :pt="{ input: { autofocus: field.props.autofocus } }"
      @update:model-value="(value) => (field.input = value as boolean)"
      @focus="field.props.onFocus"
      @change="field.props.onChange"
      @blur="field.props.onBlur"
    />
    <label for="login-remember-me">Remember me</label>
  </Field>
</template>
```

Two PrimeVue conventions show up here. `inputId` puts an id on the real control so a `<label for>` can reach it, while a plain `id` would land on the wrapper. The `pt` object is spread onto an internal element, so it carries any attribute or listener you need to place there. Forwarding `@focus` matters as well, because assigning `field.input` updates the value but only the focus handler marks the field as touched.

Assigning `field.input` runs input-mode validation, so a form configured with `validate: 'change'` does not validate these controls until submit. Use `validate: 'input'` if you want them validated as the value changes.

#### Displaying errors

Formisch exposes errors as `[string, ...string[]] | null`. Prefer PrimeVue's own `invalid` prop over setting `aria-invalid` yourself, since the component writes `aria-invalid` onto the inner control and omits it while the field is valid:

```vue
<template>
  <Field :of="loginForm" :path="['email']" v-slot="field">
    <InputText
      id="login-email"
      :ref="elementRef(field.props.ref)"
      v-model="field.input"
      :invalid="!!field.errors"
      aria-errormessage="login-email-error"
    />
    <small v-if="field.errors" id="login-email-error">{{
      field.errors[0]
    }}</small>
  </Field>
</template>
```

For a wrapped control, route `aria-errormessage` through `pt` so it lands on the element that carries the role. Use page-unique ids rather than the field name, because `field.props.name` is the JSON encoded path, such as `["email"]`.

By default, Formisch validates on submit and revalidates on input. The [validation guide](/vue/guides/validation.md) explains how to change that timing.

#### Login form example

This complete example combines text inputs, a controlled checkbox and accessible errors:

```vue
<script setup lang="ts">
import { Field, Form, type SubmitHandler, useForm } from '@formisch/vue';
import Button from 'primevue/button';
import Checkbox from 'primevue/checkbox';
import InputText from 'primevue/inputtext';
import Password from 'primevue/password';
import * as v from 'valibot';
import type { ComponentPublicInstance } from 'vue';

const LoginSchema = v.object({
  email: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your email.'),
    v.email('The email address is badly formatted.')
  ),
  password: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your password.'),
    v.minLength(8, 'Your password must have 8 characters or more.')
  ),
  rememberMe: v.optional(v.boolean(), false),
});

const loginForm = useForm({
  schema: LoginSchema,
  initialInput: { email: '', password: '', rememberMe: false },
});

const handleSubmit: SubmitHandler<typeof LoginSchema> = (output) => {
  console.log(output);
};

// PrimeVue renders its focusable control inside a styled wrapper, so a ref
// placed on the component yields the wrapper, not the control. Formisch calls
// `.focus()` on whatever it is given, so hand it the real focusable element.
const FOCUSABLE = 'input, select, textarea, [tabindex]';

function elementRef(register: (element: Element | null) => void) {
  return (instance: Element | ComponentPublicInstance | null) => {
    const root = (
      instance && '$el' in instance ? instance.$el : instance
    ) as HTMLElement | null;
    register(
      root?.matches(FOCUSABLE) ? root : (root?.querySelector(FOCUSABLE) ?? root)
    );
  };
}
</script>

<template>
  <Form :of="loginForm" @submit="handleSubmit">
    <Field :of="loginForm" :path="['email']" v-slot="field">
      <div>
        <label for="login-email">Email</label>
        <InputText
          id="login-email"
          type="email"
          :ref="elementRef(field.props.ref)"
          :name="field.props.name"
          :autofocus="field.props.autofocus"
          v-model="field.input"
          :invalid="!!field.errors"
          aria-errormessage="login-email-error"
          @focus="field.props.onFocus"
          @change="field.props.onChange"
          @blur="field.props.onBlur"
        />
        <small v-if="field.errors" id="login-email-error">
          {{ field.errors[0] }}
        </small>
      </div>
    </Field>

    <Field :of="loginForm" :path="['password']" v-slot="field">
      <div>
        <label for="login-password">Password</label>
        <Password
          input-id="login-password"
          :ref="elementRef(field.props.ref)"
          :name="field.props.name"
          :autofocus="field.props.autofocus"
          v-model="field.input"
          :feedback="false"
          :invalid="!!field.errors"
          :input-props="{
            'aria-errormessage': 'login-password-error',
            onFocus: field.props.onFocus,
            onChange: field.props.onChange,
            onBlur: field.props.onBlur,
          }"
        />
        <small v-if="field.errors" id="login-password-error">
          {{ field.errors[0] }}
        </small>
      </div>
    </Field>

    <Field :of="loginForm" :path="['rememberMe']" v-slot="field">
      <div>
        <Checkbox
          input-id="login-remember-me"
          binary
          :ref="elementRef(field.props.ref)"
          :name="field.props.name"
          :model-value="field.input ?? false"
          :invalid="!!field.errors"
          :pt="{
            input: {
              autofocus: field.props.autofocus,
              'aria-errormessage': 'login-remember-me-error',
            },
          }"
          @update:model-value="(value) => (field.input = value as boolean)"
          @focus="field.props.onFocus"
          @change="field.props.onChange"
          @blur="field.props.onBlur"
        />
        <label for="login-remember-me">Remember me</label>
        <small v-if="field.errors" id="login-remember-me-error">
          {{ field.errors[0] }}
        </small>
      </div>
    </Field>

    <Button type="submit" label="Login" :disabled="loginForm.isSubmitting" />
  </Form>
</template>
```

The initial input keeps every control defined from its first render. `Password` takes its handlers through `inputProps`, since that component exposes its inner input that way.

#### Component reference

The following snippets assume a form store named `form`, initialized values that match the schema, and the `elementRef` helper from above.

##### Text input

`InputText` renders the native element as its root, so the reference reaches it without a lookup:

```vue
<template>
  <Field :of="form" :path="['email']" v-slot="field">
    <label for="profile-email">Email</label>
    <InputText
      id="profile-email"
      type="email"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :autofocus="field.props.autofocus"
      v-model="field.input"
      :invalid="!!field.errors"
      aria-errormessage="profile-email-error"
      @focus="field.props.onFocus"
      @change="field.props.onChange"
      @blur="field.props.onBlur"
    />
  </Field>
</template>
```

`Textarea` works the same way.

##### Checkbox

A boolean field needs the `binary` prop, and the payload is typed loosely, so narrow it:

```vue
<template>
  <Field :of="form" :path="['newsletter']" v-slot="field">
    <Checkbox
      input-id="settings-newsletter"
      binary
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :model-value="field.input ?? false"
      :invalid="!!field.errors"
      :pt="{ input: { autofocus: field.props.autofocus } }"
      @update:model-value="(value) => (field.input = value as boolean)"
      @focus="field.props.onFocus"
      @change="field.props.onChange"
      @blur="field.props.onBlur"
    />
    <label for="settings-newsletter">Newsletter</label>
  </Field>
</template>
```

##### Select

The focusable part is a span with a `combobox` role, which a `<label>` cannot name. PrimeVue writes its own `aria-label` from the current selection, so set `aria-label` explicitly to keep the name stable. Its change event is a PrimeVue payload rather than a DOM event, so forward the original:

```vue
<template>
  <Field :of="form" :path="['framework']" v-slot="field">
    <label for="project-framework">Framework</label>
    <Select
      label-id="project-framework"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :model-value="field.input"
      :options="frameworks"
      option-label="label"
      option-value="value"
      placeholder="Select a framework"
      aria-label="Framework"
      :invalid="!!field.errors"
      :pt="{
        label: {
          autofocus: field.props.autofocus,
          'aria-errormessage': 'project-framework-error',
        },
      }"
      @update:model-value="(value) => (field.input = value)"
      @focus="field.props.onFocus"
      @change="(event) => field.props.onChange(event.originalEvent)"
      @blur="field.props.onBlur"
    />
  </Field>
</template>
```

##### Radio group

Register every button. Formisch keeps a list of registered elements, so each radio registers itself just like a native radio group:

```vue
<template>
  <Field :of="form" :path="['plan']" v-slot="field">
    <span id="plan-label">Plan</span>
    <RadioButtonGroup
      :name="field.props.name"
      :model-value="field.input"
      aria-labelledby="plan-label"
      @update:model-value="(value) => (field.input = value)"
    >
      <div v-for="plan in plans" :key="plan.value">
        <RadioButton
          :input-id="`plan-${plan.value}`"
          :ref="elementRef(field.props.ref)"
          :value="plan.value"
          :invalid="!!field.errors"
          :pt="{
            input: {
              autofocus: field.props.autofocus,
              'aria-errormessage': 'plan-error',
            },
          }"
          @focus="field.props.onFocus"
          @change="field.props.onChange"
          @blur="field.props.onBlur"
        />
        <label :for="`plan-${plan.value}`">{{ plan.label }}</label>
      </div>
    </RadioButtonGroup>
  </Field>
</template>
```

##### Slider

`Slider` emits no focus or blur events of its own, so route those handlers through `pt` onto the inner range input. Its change event carries a raw number, so use `slideend` when you need the underlying DOM event:

```vue
<template>
  <Field :of="form" :path="['volume']" v-slot="field">
    <label for="settings-volume">Volume</label>
    <Slider
      input-id="settings-volume"
      :ref="elementRef(field.props.ref)"
      :name="field.props.name"
      :model-value="field.input"
      :min="0"
      :max="100"
      :step="1"
      aria-label="Volume"
      :invalid="!!field.errors"
      :pt="{
        input: {
          autofocus: field.props.autofocus,
          'aria-invalid': !!field.errors,
          'aria-errormessage': 'settings-volume-error',
          onFocus: field.props.onFocus,
          onBlur: field.props.onBlur,
        },
      }"
      @update:model-value="(value) => (field.input = value as number)"
      @slideend="(event) => field.props.onChange(event.originalEvent)"
    />
  </Field>
</template>
```

The slider's `slider` role sits on a real range input, and the default single-value mode renders exactly one.

#### Library-specific notes

PrimeVue v5 ships its own `Form` and `FormField` components built around its resolver based validation. You do not need them with Formisch: use Formisch's [`Form`](/vue/api/Form.md) and [`Field`](/vue/api/Field.md) and let your Valibot schema drive validation.

`field.props.autofocus` is a snapshot taken when the field mounts, not a reactive value. Formisch moves focus to the first invalid field after a failed submit on its own.

#### Next steps

Read the [input components](/vue/guides/input-components.md) guide to package repeated wiring into reusable controls, the [controlled fields](/vue/guides/controlled-fields.md) guide for the underlying pattern, and the [validation](/vue/guides/validation.md) guide for validation timing.