# 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 React Native. 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 – re-renders only if necessary
- Minimal, readable and well thought out API
- Supports native `TextInput` fields

#### Example

Every form starts with the [`useForm`](/react-native/api/useForm.md) hook. It initializes your form's store based on the provided Valibot schema and infers its types. Unlike the DOM frameworks, React Native has no native form element or submit event, so there is no `<Form />` component and submission is triggered explicitly with [`handleSubmit`](/methods/api/handleSubmit.md), for example from a button's `onPress` or a text input's `onSubmitEditing` handler. You can access the state of a field with the [`useField`](/react-native/api/useField.md) hook or the [`<Field />`](/react-native/api/Field.md) component to connect your `TextInput`.

```tsx
import { Field, handleSubmit, useForm } from '@formisch/react-native';
import { Button, Text, TextInput, View } from 'react-native';
import * as v from 'valibot';

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

export default function LoginScreen() {
  const loginForm = useForm({
    schema: LoginSchema,
  });

  const submitForm = handleSubmit(loginForm, (output) => console.log(output));

  return (
    <View>
      <Field of={loginForm} path={['email']}>
        {(field) => (
          <View>
            <TextInput
              {...field.props}
              value={field.input}
              autoCapitalize="none"
              keyboardType="email-address"
            />
            {field.errors && <Text>{field.errors[0]}</Text>}
          </View>
        )}
      </Field>
      <Field of={loginForm} path={['password']}>
        {(field) => (
          <View>
            <TextInput {...field.props} value={field.input} secureTextEntry />
            {field.errors && <Text>{field.errors[0]}</Text>}
          </View>
        )}
      </Field>
      <Button title="Login" onPress={submitForm} />
    </View>
  );
}
```

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), [`getDeepErrors`](/methods/api/getDeepErrors.md), [`getErrors`](/methods/api/getErrors.md), [`getInput`](/methods/api/getInput.md), [`handleSubmit`](/methods/api/handleSubmit.md), [`insert`](/methods/api/insert.md), [`move`](/methods/api/move.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), [`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 library is built, giving you native performance for any UI update. A modular methods API keeps bundles starting at just ~2.5 kB by only including the methods you import, and end-to-end type safety covers deeply nested paths and field arrays with TypeScript inference that stays fast even as forms grow.

For a side-by-side look at how Formisch compares to React Hook Form and TanStack Form, see the [comparison guide](/react-native/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.

```ts
{
  "compilerOptions": {
    "strict": true,
    // ...
  }
}
```

#### Install Valibot

Formisch uses [Valibot](https://valibot.dev/) for schema-based validation. You need to install it first because it is a peer dependency.

```bash
npm install valibot     # npm
yarn add valibot        # yarn
pnpm add valibot        # pnpm
bun add valibot         # bun
deno add npm:valibot    # deno
```

#### Install Formisch

You can add Formisch to your project with a single command using your favorite package manager.

```bash
npm install @formisch/react-native     # npm
yarn add @formisch/react-native        # yarn
pnpm add @formisch/react-native        # pnpm
bun add @formisch/react-native         # bun
deno add npm:@formisch/react-native    # deno
```

Then you can import it into any JavaScript or TypeScript file.

```ts
import { … } from '@formisch/react-native';
```

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

```json
{
  "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-react-native.txt`](/llms-react-native.txt) contains a table of contents with links to React Native-related files
- [`llms-react-native-full.txt`](/llms-react-native-full.txt) contains the Markdown content of the entire React Native docs
- [`llms-react-native-guides.txt`](/llms-react-native-guides.txt) contains the Markdown content of the React Native guides
- [`llms-react-native-api.txt`](/llms-react-native-api.txt) contains the Markdown content of the React Native 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. `/react-native/guides/installation/` becomes [`/react-native/guides/installation.md`](/react-native/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 React Native. The two most common alternatives, [React Hook Form](https://react-hook-form.com) and [TanStack Form](https://tanstack.com/form/latest), also run in React Native. This page is meant as a quick reference for picking the right tool. For a deeper explanation of the architectural differences and the reasoning behind each row of the table below, see our [long-form comparison article](/blog/react-form-library-comparison.md) — it was written for React on the web, but the architecture it describes applies equally to React Native.

#### At a glance

|                        | **Formisch**                                                   | React Hook Form                     | TanStack Form                                         |
| ---------------------- | -------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------- |
| Type source            | Inferred from schema                                           | Generic you declare                 | Inferred from `defaultValues`                         |
| Validation location    | Defined in schema                                              | Per-field or resolver               | Per-validator config                                  |
| Validation timing      | Form-wide `validate` / `revalidate`                            | Form-wide `mode` option             | Per-validator trigger                                 |
| Async validation       | Built-in via schema                                            | Manual loading state                | Built-in `isValidating`                               |
| Re-render scope        | Automatic per signal                                           | Manual via `watch` / `useFormState` | Automatic per subscription                            |
| Schema libraries       | Valibot                                                        | Any via resolvers                   | Standard Schema                                       |
| Bundle size (min+gzip) | From ~2.5 kB                                                   | ~12 kB                              | ~15 kB                                                |
| Framework support      | Angular, React, React Native, Preact, Solid, Svelte, Vue, Qwik | React, React Native                 | React, React Native, Vue, Solid, Svelte, Lit, Angular |

The table is intentionally short. It only covers the dimensions that most often drive a library choice in practice. Other differences such as devtools, ecosystem maturity, and community size are real but tend to matter less than how each library handles types, validation, and re-renders.

#### Why Formisch?

Three reasons to pick Formisch over the alternatives above:

**One schema, no second source of truth.** A single Valibot schema is everything the form needs: the runtime validator, the source of types, and the description of the form's structure — all at once. There is no separate TypeScript generic to declare, no `defaultValues` object to keep aligned with the schema, no resolver to configure. When the schema changes, every part of the form follows — at compile time and at runtime.

**The smallest bundle, by a wide margin.** Formisch starts at ~2.5 kB and grows only as you import additional methods like `focus`, `getInput`, and `reset`. That is several times smaller than the alternatives in the table above — and it stays that way because the core is intentionally small and the library is fully tree-shakable, so methods you don't import don't end up in your bundle.

**Type safety that stays fast.** Types flow from the schema through every API, including deeply nested paths and field arrays. The inference is structured to keep TypeScript editor performance from degrading as schemas grow — which matters in large codebases where heavily-generic form libraries become a friction point.

#### Which library should you use?

**React Hook Form** is a mature, well-documented choice with a large community and years of production usage. In React Native there are no DOM inputs to `register`, so each `TextInput` is wired up through its `Controller` component, which adds a wrapper per field. For simple to moderately complex forms, it remains a reasonable default. The tradeoffs only become visible as forms grow: types and schema drift out of sync, validation rules spread across components, and re-render scope becomes your responsibility.

**TanStack Form** is a good fit when you need fine-grained control over validation timing and built-in async validation handling without building that infrastructure yourself. It is also the natural choice if your team is already invested in the TanStack ecosystem and values a consistent mental model across data fetching, routing, and forms.

**Formisch** makes the most sense for new projects in TypeScript-heavy codebases, especially when you expect forms to grow in complexity. The schema-first design means there is a single source of truth for types, runtime validation, and form structure, so there is less to keep aligned over time. The main consideration is that Formisch currently supports only [Valibot](https://valibot.dev) as the schema library.

#### Migrating to Formisch

Migrating to Formisch is a genuine rewrite of the form layer, not a drop-in replacement. The mental model is different: instead of starting from a component and attaching form behavior to it, you start from a schema and build the component around it. The libraries can coexist in the same application, so you can migrate one form at a time.

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 React Hook Form](/react-native/guides/migrate-from-react-hook-form.md) and [migrate from TanStack Form](/react-native/guides/migrate-from-tanstack-form.md).

#### Next steps

If you have decided that Formisch is a good fit, install it via the [installation](/react-native/guides/installation.md) guide and start building by [defining your form](/react-native/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`](/react-native/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 screen.

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

### Create your form

Formisch consists of hooks, components and methods. To create a form you use the [`useForm`](/react-native/api/useForm.md) hook.

#### Form hook

The [`useForm`](/react-native/api/useForm.md) hook initializes and returns the store of your form. The store contains the state of the form and can be used with other Formisch hooks, components and methods to build your form.

Unlike the web, React Native has no native form element or submit event. Therefore, submission is triggered explicitly with the [`handleSubmit`](/methods/api/handleSubmit.md) method — for example, from a button's `onPress` handler. You will learn more about this in the [handle submission](/react-native/guides/handle-submission.md) guide.

```tsx
import { handleSubmit, useForm } from '@formisch/react-native';
import { Button, View } from 'react-native';
import * as v from 'valibot';

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

export default function LoginScreen() {
  const loginForm = useForm({
    schema: LoginSchema,
  });

  const submitForm = handleSubmit(loginForm, (output) => console.log(output));

  return (
    <View>
      {/* Form fields will go here */}
      <Button title="Login" onPress={submitForm} />
    </View>
  );
}
```

##### Configuration options

The [`useForm`](/react-native/api/useForm.md) hook accepts a configuration object with the following options:

- `schema`: Your Valibot schema that defines the form
- `initialInput`: Initial values for your form fields (optional)
- `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'`)

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

Formisch tracks two inputs for every field: the **initial input** (baseline for dirty tracking) and the **current input** (what the user is editing). In many apps, the initial input represents the server state while the current input represents the client state.

`isDirty` becomes `true` when a field's current input differs from its initial input. Use [`setInput`](/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`:

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

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 screen contains multiple forms, you can create separate form stores for each one:

```tsx
import { useForm } from '@formisch/react-native';
import { View } from 'react-native';
import * as v from 'valibot';

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

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

export default function AuthScreen() {
  const loginForm = useForm({ schema: LoginSchema });
  const registerForm = useForm({ schema: RegisterSchema });

  return (
    <View>
      <View>{/* Login form fields */}</View>
      <View>{/* Register form fields */}</View>
    </View>
  );
}
```

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](/react-native/guides/add-form-fields.md) guide to learn how to connect your input components to the form using the [`Field`](/react-native/api/Field.md) component.

### Add form fields

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

#### Field component

The [`Field`](/react-native/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.

##### Children prop

As a child, you pass a function to the [`Field`](/react-native/api/Field.md) component that returns JSX. The function receives the field store as its parameter, which includes the current value, error messages, and props to spread onto your `TextInput` component.

```tsx
import { Field, handleSubmit, useForm } from '@formisch/react-native';
import { Button, TextInput, View } from 'react-native';
import * as v from 'valibot';

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

export default function LoginScreen() {
  const loginForm = useForm({
    schema: LoginSchema,
  });

  const submitForm = handleSubmit(loginForm, (output) => console.log(output));

  return (
    <View>
      <Field of={loginForm} path={['email']}>
        {(field) => (
          <TextInput
            {...field.props}
            value={field.input}
            autoCapitalize="none"
            keyboardType="email-address"
          />
        )}
      </Field>
      <Field of={loginForm} path={['password']}>
        {(field) => (
          <TextInput {...field.props} value={field.input} secureTextEntry />
        )}
      </Field>
      <Button title="Login" onPress={submitForm} />
    </View>
  );
}
```

> **Important:** Text inputs are controlled. Always pass `value={field.input}` so that initial values from `initialInput` and programmatic updates via methods like [`setInput`](/methods/api/setInput.md) or [`reset`](/methods/api/reset.md) are reflected in the UI.

> **Important:** The `onChangeText` handler in `field.props` receives the value as a string. Fields with a non-string schema like `v.number()` or `v.date()` therefore need to use `field.onChange` to store the value with the correct type. See the [controlled fields](/react-native/guides/controlled-fields.md) guide to learn more.

##### Headless design

The [`Field`](/react-native/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 React Native's built-in components, custom components or an external UI library.

##### Path array

The `path` property accepts an array of strings and numbers that represents the path to the field in your schema. For top-level fields, it's simply the field name wrapped in an array:

```tsx
<Field of={loginForm} path={['email']}>
  {(field) => <TextInput {...field.props} value={field.input} />}
</Field>
```

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

```tsx
// For a schema like: v.object({ user: v.object({ email: v.string() }) })
<Field of={form} path={['user', 'email']}>
  {(field) => <TextInput {...field.props} value={field.input} />}
</Field>
```

##### Type safety

The API design of the [`Field`](/react-native/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 hook

For very complex forms where you create individual components for each form field, Formisch provides the [`useField`](/react-native/api/useField.md) hook. It allows you to access the field state directly within your component logic.

```tsx
import { useField } from '@formisch/react-native';
import type { FormStore } from '@formisch/react-native';
import { Text, TextInput, View } from 'react-native';
import * as v from 'valibot';

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

function EmailInput(props: EmailInputProps) {
  const field = useField(props.form, { path: ['email'] });

  return (
    <View>
      <TextInput
        {...field.props}
        value={field.input}
        autoCapitalize="none"
        keyboardType="email-address"
      />
      {field.errors && <Text>{field.errors[0]}</Text>}
    </View>
  );
}
```

##### When to use which

- **Use [`Field`](/react-native/api/Field.md) component**: When defining multiple fields in the same component. It ensures you don't accidentally access the wrong field store.
- **Use [`useField`](/react-native/api/useField.md) hook**: When creating field components for single fields. It allows you to access field state in your component logic.

The [`Field`](/react-native/api/Field.md) component is essentially a thin wrapper around [`useField`](/react-native/api/useField.md) that allows you to access the field state within JSX code.

#### Field store

The field store provides access to the following properties. They are plain values, but because Formisch wires into React's rendering, your components re-render when they change.

- `props`: Props to spread onto your `TextInput` component (includes the event handlers and the ref callback to register the field).
- `input`: The current input value of the field.
- `errors`: The current array of error messages if validation fails.
- `isTouched`: Whether the field has been touched.
- `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.
- `onChange`: Sets the field input value programmatically. Use this for components that don't render a text input (e.g., `Switch`, sliders or picker components).

#### Next steps

Now that you know how to add fields to your form, continue to the [input components](/react-native/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/react-native/components).

#### Why input components?

Currently, your fields might look something like this:

```tsx
<Field of={loginForm} path={['email']}>
  {(field) => (
    <View>
      <Text>Email</Text>
      <TextInput
        {...field.props}
        value={field.input}
        autoCapitalize="none"
        keyboardType="email-address"
      />
      {field.errors && <Text>{field.errors[0]}</Text>}
    </View>
  )}
</Field>
```

If styling and a few more functionalities are added here, the code quickly becomes confusing. In addition, you have to rewrite the same code for almost every form field.

Our goal is to develop a `TextInput` component so that the code ends up looking like this:

```tsx
<Field of={loginForm} path={['email']}>
  {(field) => (
    <TextInput
      {...field.props}
      type="email"
      label="Email"
      input={field.input}
      errors={field.errors}
      required
    />
  )}
</Field>
```

#### Create an input component

In the first step, you create a new file for the `TextInput` component and, if you use TypeScript, define its properties. By extending `FieldElementProps`, your component accepts the props of the field store, which include the event handlers and the ref callback.

```tsx
import type { FieldElementProps } from '@formisch/react-native';

interface TextInputProps extends FieldElementProps {
  type: 'text' | 'email' | 'tel' | 'password' | 'url';
  label?: string;
  placeholder?: string;
  input: string | undefined;
  errors: [string, ...string[]] | null;
  required?: boolean;
}
```

##### Component function

In the next step, add the component function to the file. We can destructure props directly and spread the remaining props. Since the component wraps React Native's own `TextInput`, we import it under the alias `RNTextInput`.

```tsx
import type { FieldElementProps } from '@formisch/react-native';
import { TextInput as RNTextInput, Text, View } from 'react-native';

interface TextInputProps extends FieldElementProps {
  /* ... */
}

export function TextInput({
  label,
  input,
  errors,
  type,
  required,
  ...props
}: TextInputProps) {
  // Component implementation
}
```

##### JSX code

After that, you can add the JSX code to the return statement. Since React Native has no input types, we map the `type` prop to the matching `keyboardType` and use `secureTextEntry` for passwords. React Native has no equivalent of the `aria-invalid` attribute, so the visible error message below the input is what communicates the invalid state. It also has no way to associate a separate label element with an input, so the label text is passed to the input as its `accessibilityLabel` for screen readers.

```tsx
import type { FieldElementProps } from '@formisch/react-native';
import {
  type KeyboardTypeOptions,
  TextInput as RNTextInput,
  Text,
  View,
} from 'react-native';

interface TextInputProps extends FieldElementProps {
  /* ... */
}

const KEYBOARD_TYPES: Record<TextInputProps['type'], KeyboardTypeOptions> = {
  text: 'default',
  email: 'email-address',
  tel: 'phone-pad',
  password: 'default',
  url: 'url',
};

export function TextInput({
  label,
  input,
  errors,
  type,
  required,
  ...props
}: TextInputProps) {
  return (
    <View>
      {label && (
        <Text>
          {label} {required && <Text>*</Text>}
        </Text>
      )}
      <RNTextInput
        {...props}
        value={input ?? ''}
        keyboardType={KEYBOARD_TYPES[type]}
        autoCapitalize={type === 'email' ? 'none' : undefined}
        secureTextEntry={type === 'password'}
        accessibilityLabel={label}
      />
      {errors && <Text>{errors[0]}</Text>}
    </View>
  );
}
```

##### Next steps

You can now build on this code and add styling, for example. You can also follow the procedure to create other components such as a `Switch` or a picker component.

##### Final code

Below is an overview of the entire code of the `TextInput` component.

```tsx
import type { FieldElementProps } from '@formisch/react-native';
import {
  type KeyboardTypeOptions,
  TextInput as RNTextInput,
  Text,
  View,
} from 'react-native';

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

const KEYBOARD_TYPES: Record<TextInputProps['type'], KeyboardTypeOptions> = {
  text: 'default',
  email: 'email-address',
  tel: 'phone-pad',
  password: 'default',
  url: 'url',
};

export function TextInput({
  label,
  input,
  errors,
  type,
  required,
  ...props
}: TextInputProps) {
  return (
    <View>
      {label && (
        <Text>
          {label} {required && <Text>*</Text>}
        </Text>
      )}
      <RNTextInput
        {...props}
        value={input ?? ''}
        keyboardType={KEYBOARD_TYPES[type]}
        autoCapitalize={type === 'email' ? 'none' : undefined}
        secureTextEntry={type === 'password'}
        accessibilityLabel={label}
      />
      {errors && <Text>{errors[0]}</Text>}
    </View>
  );
}
```

#### Non-text components

The props of the field store are designed for text inputs. React Native's own non-text components — such as `Switch`, sliders or picker components — do not accept an `onChangeText` handler, so you cannot spread `field.props` onto them. Use `field.onChange` to update the value instead:

```tsx
import { Switch } from 'react-native';

<Field of={form} path={['newsletter']}>
  {(field) => <Switch value={field.input} onValueChange={field.onChange} />}
</Field>;
```

The `field.onChange` method updates the field value and triggers validation. Your own components can still extend `FieldElementProps` as shown above: forward the `ref` to the pressable part of the component and call the `onFocus` and `onBlur` handlers when the interaction starts and ends, so that [`focus`](/methods/api/focus.md), `isTouched` and blur validation keep working. For more details, see the [controlled fields](/react-native/guides/controlled-fields.md) guide.

#### Next steps

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

### Handle submission

Now your first form is almost ready. There is only one little thing missing and that is the data processing when the form is submitted.

#### Submit function

React Native has no native form element or submit event. Instead, you create a submit function with the [`handleSubmit`](/methods/api/handleSubmit.md) method and call it explicitly — for example, from the `onPress` handler of a `Button` or `Pressable`. The [`handleSubmit`](/methods/api/handleSubmit.md) method takes your form store and a handler that receives the validated form values.

```tsx
import { handleSubmit, useForm } from '@formisch/react-native';
import { Button, View } from 'react-native';
import * as v from 'valibot';

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

export default function LoginScreen() {
  const loginForm = useForm({
    schema: LoginSchema,
  });

  const submitForm = handleSubmit(loginForm, (values) => {
    // Process the validated form values
    console.log(values); // { email: string, password: string }
  });

  return (
    <View>
      {/* Form fields will go here */}
      <Button title="Login" onPress={submitForm} />
    </View>
  );
}
```

When called, the returned function validates the form and only invokes your handler if validation succeeds. Since it accepts no arguments and returns a promise, you can also call it from anywhere to trigger submission programmatically.

If you define your handler separately, you can use the [`SubmitHandler`](/core/api/SubmitHandler.md) type to ensure type safety. It automatically infers the types of the validated values from your schema. Since React Native has no submit event, the handler receives only the validated values — there is no event object.

```tsx
import type { SubmitHandler } from '@formisch/react-native';

const submitHandler: SubmitHandler<typeof LoginSchema> = (values) => {
  // Process the validated form values
  console.log(values);
};

const submitForm = handleSubmit(loginForm, submitHandler);
```

##### Submit on editing

Besides a button, you can also trigger submission from the keyboard's submit key by passing the submit function to the `onSubmitEditing` prop of your last `TextInput`:

```tsx
<Field of={loginForm} path={['password']}>
  {(field) => (
    <TextInput
      {...field.props}
      value={field.input}
      secureTextEntry
      onSubmitEditing={submitForm}
    />
  )}
</Field>
```

##### Loading state

While the form is being submitted, you can use `loginForm.isSubmitting` to display a loading animation and disable the submit button:

```tsx
<Button
  title={loginForm.isSubmitting ? 'Submitting...' : 'Login'}
  disabled={loginForm.isSubmitting}
  onPress={submitForm}
/>
```

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:

```tsx
const submitForm = handleSubmit(loginForm, async (values) => {
  try {
    const response = await fetch('https://example.com/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);
  }
});
```

While the promise returned by your handler is pending, `loginForm.isSubmitting` stays `true`.

#### 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](/react-native/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
- [`getDeepErrors`](/methods/api/getDeepErrors.md): Get all error
  messages across the entire form

Formisch plugs into React's render cycle, so reading values with these methods inside components stays reactive. When the form state changes, components that rely on these values automatically re-render without manual subscriptions.

#### 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](/react-native/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

> When you have access to a field store (from [`useField`](/react-native/api/useField.md) or [`Field`](/react-native/api/Field.md)), you can use `field.onChange(value)` to update the value directly. This is especially useful for components that don't render a text input, such as `Switch`, sliders or picker components.

> 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`](/methods/api/setInput.md). The [`reset`](/methods/api/reset.md) method properly reinitializes the form state, while [`setInput`](/methods/api/setInput.md) 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
  function 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
- [`focus`](/methods/api/focus.md): Focus on a specific field

Since React Native has no native submit event, calling the function returned by [`handleSubmit`](/methods/api/handleSubmit.md) is also the way to trigger submission programmatically. See the [handle submission](/react-native/guides/handle-submission.md) guide to learn more.

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

```tsx
// Get the value of a field
const emailInput = getInput(loginForm, { path: ['email'] });

// Reset the form with new initial values
reset(loginForm, { initialInput: { email: '', password: '' } });

// Move an item in a field array
move(loginForm, { path: ['items'], from: 0, to: 3 });
```

#### API reference

You can find detailed documentation for each method in our [API reference](/react-native/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 `<TextInput />` 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 change to the field's value.
- `'change'`: same timing as `'input'` in React Native, since a field only has a single change event (`onChangeText` for text inputs or `field.onChange` for everything else).
- `'blur'`: when the field loses focus.
- `'submit'`: only when the form is submitted.

```tsx
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:

```tsx
import { Field, handleSubmit, useForm } from '@formisch/react-native';
import { Button, Text, TextInput, View } from 'react-native';
import * as v from 'valibot';

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

export default function LoginScreen() {
  const loginForm = useForm({
    schema: LoginSchema,
    validate: 'change',
  });

  const submitForm = handleSubmit(loginForm, (output) => console.log(output));

  return (
    <View>
      <Field of={loginForm} path={['email']}>
        {(field) => (
          <View>
            <TextInput
              {...field.props}
              value={field.input}
              autoCapitalize="none"
              keyboardType="email-address"
            />
            {(field.isEdited || loginForm.isSubmitted) && field.errors && (
              <Text>{field.errors[0]}</Text>
            )}
          </View>
        )}
      </Field>
      <Button title="Login" onPress={submitForm} />
    </View>
  );
}
```

`isEdited` is the right flag for this. `isTouched` would reveal the error as soon as the user moves 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](/react-native/guides/input-components.md) guide, so the `isEdited || isSubmitted` logic lives in exactly one place:

```tsx
import { Text } from 'react-native';

interface FieldErrorProps {
  errors: [string, ...string[]] | null;
  isEdited: boolean;
  isSubmitted: boolean;
}

export function FieldError({ errors, isEdited, isSubmitted }: FieldErrorProps) {
  if (!errors || (!isEdited && !isSubmitted)) {
    return null;
  }
  return <Text>{errors[0]}</Text>;
}
```

Each field then stays focused on its input:

```tsx
<Field of={loginForm} path={['email']}>
  {(field) => (
    <View>
      <TextInput
        {...field.props}
        value={field.input}
        autoCapitalize="none"
        keyboardType="email-address"
      />
      <FieldError
        errors={field.errors}
        isEdited={field.isEdited}
        isSubmitted={loginForm.isSubmitted}
      />
    </View>
  )}
</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.

```tsx
import { handleSubmit, useForm } from '@formisch/react-native';
import { Button, View } from 'react-native';
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.')
  ),
});

export default function SignUpScreen() {
  const signUpForm = useForm({
    schema: SignUpSchema,
    validate: 'blur',
  });

  const submitForm = handleSubmit(signUpForm, (output) => console.log(output));

  return (
    <View>
      {/* fields */}
      <Button
        title={signUpForm.isValidating ? 'Checking...' : 'Sign up'}
        disabled={signUpForm.isValidating}
        onPress={submitForm}
      />
    </View>
  );
}
```

`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](/react-native/guides/handle-submission.md) guide. For working with the fields a user has changed, see the [dirty fields](/react-native/guides/dirty-fields.md) guide.

### Special inputs

React Native has no built-in form elements beyond text entry — there are no native checkboxes, dropdown selects or file inputs. Text is entered through `TextInput`, which connects to a field by spreading `field.props`. Every other kind of input — switches, sliders, selection lists, pickers — is wired up manually: read the current value from `field.input` and write it back with `field.onChange`. This guide covers the most common cases.

> In our [playground](/playground/special/) you can take a look at such fields and test them out.

Because `field.onChange` accepts whatever type your schema defines for the field, this pattern is not limited to strings. A switch stores a boolean, a slider stores a number, and a multi-select stores an array — no string conversion involved.

#### Switch

A boolean field is represented by React Native's `Switch` component. Pass the field's input as `value` and forward `onValueChange` to `field.onChange`:

```tsx
<Field of={form} path={['cookies']}>
  {(field) => (
    <View>
      <Text>Yes, I want cookies</Text>
      <Switch value={field.input} onValueChange={field.onChange} />
    </View>
  )}
</Field>
```

The corresponding schema entry is a plain boolean, for example `v.optional(v.boolean(), false)`.

#### Slider

Sliders such as the community package `@react-native-community/slider` emit real numbers. Unlike a DOM range input, which reports its value as a string, no conversion is needed — define the field as `v.number()` and pass the emitted value straight to `field.onChange`:

```tsx
import Slider from '@react-native-community/slider';

<Field of={form} path={['volume']}>
  {(field) => (
    <Slider
      value={field.input}
      minimumValue={0}
      maximumValue={100}
      step={1}
      onValueChange={field.onChange}
    />
  )}
</Field>;
```

#### Checkbox group

A group of checkboxes represents an array of strings. Since React Native has no native checkbox, you build one yourself — typically a `Pressable` that toggles its state — or use one from a component library. The wiring is always the same: a checkbox is checked when its value is included in `field.input`, and toggling it calls `field.onChange` with a new array that adds or removes the value.

```tsx
<View>
  {[
    { label: 'Bananas', value: 'bananas' },
    { label: 'Apples', value: 'apples' },
    { label: 'Grapes', value: 'grapes' },
  ].map(({ label, value }) => (
    <Field key={value} of={form} path={['fruits']}>
      {(field) => (
        <Checkbox
          label={label}
          checked={field.input.includes(value)}
          onValueChange={(checked) =>
            field.onChange(
              checked
                ? [...field.input, value]
                : field.input.filter((item) => item !== value)
            )
          }
        />
      )}
    </Field>
  ))}
</View>
```

For a single boolean checkbox, skip the array logic and pass `field.onChange` directly, exactly like the `Switch` example above.

#### Radio group

A group of radio buttons stores a single string. Each option is selected when it equals `field.input`, and pressing an option simply calls `field.onChange` with its value:

```tsx
<Field of={form} path={['color']}>
  {(field) => (
    <View>
      {[
        { label: 'Red', value: 'red' },
        { label: 'Green', value: 'green' },
        { label: 'Blue', value: 'blue' },
      ].map(({ label, value }) => (
        <Radio
          key={value}
          label={label}
          selected={field.input === value}
          onPress={() => field.onChange(value)}
        />
      ))}
    </View>
  )}
</Field>
```

#### Select

Selection lists — whether you build them with a modal, a bottom sheet, or a picker component — follow the same two patterns. A single select stores a string:

```tsx
<Field of={form} path={['framework']}>
  {(field) => (
    <Select
      value={field.input}
      options={[
        { label: 'React Native', value: 'react-native' },
        { label: 'React', value: 'react' },
        { label: 'Solid', value: 'solid' },
      ]}
      onValueChange={field.onChange}
    />
  )}
</Field>
```

A multi-select stores an array of strings. Toggle the pressed value in or out of the array, just like the checkbox group:

```tsx
<Field of={form} path={['frameworks']}>
  {(field) => (
    <Select
      value={field.input}
      options={[
        { label: 'React Native', value: 'react-native' },
        { label: 'React', value: 'react' },
        { label: 'Solid', value: 'solid' },
      ]}
      multiple
      onValueChange={(value) =>
        field.onChange(
          field.input.includes(value)
            ? field.input.filter((item) => item !== value)
            : [...field.input, value]
        )
      }
    />
  )}
</Field>
```

#### File

React Native has no `File` class and no file input element. Instead, document and image pickers such as `expo-document-picker` or `expo-image-picker` return plain asset objects that describe the selected file by its URI. You store these objects directly in the form and describe their shape in your schema. The schema below matches the assets of `expo-document-picker`; other pickers report different metadata — `expo-image-picker`, for example, returns `fileName` and `fileSize` instead of `name` and `size` — so map their assets to the shape your schema expects:

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

const FileAssetSchema = v.object({
  uri: v.string(),
  name: v.string(),
  mimeType: v.optional(v.string()),
  size: v.optional(v.number()),
});

const FormSchema = v.object({
  avatar: v.optional(FileAssetSchema),
  documents: v.array(FileAssetSchema),
});
```

To connect a picker, open it from a press handler and pass the resulting asset to `field.onChange`:

```tsx
import * as DocumentPicker from 'expo-document-picker';

<Field of={form} path={['avatar']}>
  {(field) => (
    <Pressable
      onPress={async () => {
        const result = await DocumentPicker.getDocumentAsync();
        if (!result.canceled) {
          const { uri, name, mimeType, size } = result.assets[0];
          field.onChange({ uri, name, mimeType, size });
        }
      }}
    >
      <Text>{field.input?.name ?? 'Select file'}</Text>
    </Pressable>
  )}
</Field>;
```

For multiple files, open the picker with `multiple: true` and pass the mapped array of assets to `field.onChange`. The field then holds `FileAsset[]`, and your submit handler can upload the selected files by their URIs.

> Components like these never focus or blur on their own. When you extract them into reusable input components as described in the [input components](/react-native/guides/input-components.md) guide, accept `field.props` and call its `onFocus` handler on the first interaction so that `isTouched` and the `'touch'` validation mode keep working. If you also validate on `'blur'`, call its `onBlur` handler when the interaction ends.

### Controlled fields

In React Native, all form fields are controlled. There is no browser that keeps its own input state on a DOM element — a `TextInput` displays exactly what you pass as `value` and reports changes through `onChangeText`. Formisch embraces this: the form store holds every field value, and `field.input` is the single source of truth.

#### Why controlled?

Because the value lives in the form store, everything Formisch does is immediately reflected in the UI: initial values appear on the first render, [`setInput`](/methods/api/setInput.md) and [`reset`](/methods/api/reset.md) update the visible text, and array operations like [`insert`](/methods/api/insert.md) or [`move`](/methods/api/move.md) rearrange the displayed values automatically. There is no extra wiring to opt in to — you get it by always passing `value`.

##### Text input example

For a text field, spread `field.props` and pass the field's input as `value`:

```tsx
<Field of={loginForm} path={['firstName']}>
  {(field) => <TextInput {...field.props} value={field.input} />}
</Field>
```

Spreading `field.props` registers the `TextInput` instance via `ref` (which is what makes [`focus`](/methods/api/focus.md) work) and connects the `onFocus`, `onBlur` and `onChangeText` handlers that keep the store in sync and trigger validation. Passing `value={field.input}` closes the loop: the input always displays the store's current value.

##### Setting values programmatically

To change a field's value from outside the input — for example from a button press or after a network request — use [`setInput`](/methods/api/setInput.md), or call `field.onChange` when you are inside the field's render function. Both update the store and trigger validation, and the controlled `TextInput` re-renders with the new value automatically.

##### No exception for files

Unlike the web, where a file input cannot be controlled, file fields in React Native are controlled like any other field. Document and image pickers return plain asset objects that you store with `field.onChange`. See the [special inputs](/react-native/guides/special-inputs.md) guide for a full example.

#### Numbers and dates

A `TextInput` only reads and writes strings. If a field should end up as a number or a `Date`, you have two options.

##### Transform in the schema

Keep the field a string in the form and let your schema transform it during validation. The user types into a regular `TextInput`, `field.input` stays a string, and the validated output has the transformed type:

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

const ProfileSchema = v.object({
  age: v.pipe(v.string(), v.decimal(), v.transform(Number)),
});

<Field of={profileForm} path={['age']}>
  {(field) => (
    <TextInput {...field.props} value={field.input} keyboardType="numeric" />
  )}
</Field>;
```

##### Use a component that emits the right type

Components that are not text-based emit real values, so no conversion is needed. A slider emits numbers and a date picker emits `Date` objects — define the schema with `v.number()` or `v.date()` and store the emitted value with `field.onChange`:

```tsx
import DateTimePicker from '@react-native-community/datetimepicker';

<Field of={profileForm} path={['birthday']}>
  {(field) => (
    <DateTimePicker
      value={field.input ?? new Date()}
      onValueChange={(event, date) => field.onChange(date)}
    />
  )}
</Field>;
```

#### Custom inputs and component libraries

The `onChangeText` handler in `field.props` is designed for text inputs. For components that report changes differently — sliders, switches, pickers, rich text editors, or components from a UI library — use `field.onChange` to set the value:

```tsx
import { ColorPicker } from 'some-component-library';

<Field of={form} path={['color']}>
  {(field) => (
    <ColorPicker value={field.input} onColorChange={field.onChange} />
  )}
</Field>;
```

The `field.onChange` method updates the field value and triggers validation, just like typing into a connected `TextInput` would.

#### Next steps

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

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

const ContactSchema = v.object({
  name: v.object({
    first: v.pipe(v.string(), v.nonEmpty()),
    last: v.pipe(v.string(), v.nonEmpty()),
  }),
  email: v.pipe(v.string(), v.email()),
  message: v.pipe(v.string(), v.nonEmpty()),
});
```

#### Path array

When creating a nested field, use an array with multiple elements for the `path` property to refer to the nested field. The array represents the path through the nested structure.

```tsx
<Field of={contactForm} path={['name', 'first']}>
  {(field) => <TextInput {...field.props} value={field.input} />}
</Field>
```

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:

```tsx
const ProfileSchema = v.object({
  user: v.object({
    address: v.object({
      street: v.string(),
      city: v.string(),
      country: v.string(),
    }),
  }),
});

// Access deeply nested field
<Field of={profileForm} path={['user', 'address', 'city']}>
  {(field) => <TextInput {...field.props} value={field.input} />}
</Field>;
```

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

```tsx
import {
  getDirtyInput,
  handleSubmit,
  type SubmitHandler,
  useForm,
} from '@formisch/react-native';
import { Button, View } from 'react-native';
import * as v from 'valibot';

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

export default function EditProfileScreen({ user }) {
  const profileForm = useForm({
    schema: UserSchema,
    initialInput: user,
  });

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

  const submitForm = handleSubmit(profileForm, onSubmit);

  return (
    <View>
      {/* fields */}
      <Button title="Save" onPress={submitForm} />
    </View>
  );
}
```

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.

```tsx
import { getDirtyPaths } from '@formisch/react-native';

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.

```tsx
import { pickDirty, type SubmitHandler } from '@formisch/react-native';

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:

```tsx
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.

```tsx
import { pickDirty, type SubmitHandler } from '@formisch/react-native';

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`](/react-native/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.

```tsx
import type { SubmitHandler } from '@formisch/react-native';

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

##### Send only the dirty raw input

```tsx
import { getDirtyInput } from '@formisch/react-native';

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

##### Send only the dirty validated output

```tsx
import { pickDirty, type SubmitHandler } from '@formisch/react-native';

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

A somewhat more special case are dynamically generated form fields based on an array. Since adding, removing, swapping and moving items can be a big challenge here, the library provides the [`FieldArray`](/react-native/api/FieldArray.md) component which, in combination with various methods, makes it very easy for you to create such forms.

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

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

const TodoFormSchema = v.object({
  heading: v.pipe(v.string(), v.nonEmpty()),
  todos: v.pipe(
    v.array(
      v.object({
        label: v.pipe(v.string(), v.nonEmpty()),
        deadline: v.pipe(v.string(), v.nonEmpty()),
      })
    ),
    v.nonEmpty(),
    v.maxLength(10)
  ),
});
```

##### FieldArray component

To dynamically generate the form fields for the todos, you use the [`FieldArray`](/react-native/api/FieldArray.md) component in combination with React's `Array.map()`. The field array provides an `items` array of unique string identifiers which are used to detect when an item is added, moved, or removed.

```tsx
import {
  Field,
  FieldArray,
  handleSubmit,
  useForm,
} from '@formisch/react-native';
import { Button, Text, TextInput, View } from 'react-native';

export default function TodosScreen() {
  const todoForm = useForm({
    schema: TodoFormSchema,
    initialInput: {
      heading: '',
      todos: [{ label: '', deadline: '' }],
    },
  });

  const submitForm = handleSubmit(todoForm, (output) => console.log(output));

  return (
    <View>
      <Field of={todoForm} path={['heading']}>
        {(field) => (
          <View>
            <TextInput {...field.props} value={field.input} />
            {field.errors && <Text>{field.errors[0]}</Text>}
          </View>
        )}
      </Field>

      <FieldArray of={todoForm} path={['todos']}>
        {(fieldArray) => (
          <View>
            {fieldArray.items.map((item, index) => (
              <View key={item}>
                <Field of={todoForm} path={['todos', index, 'label']}>
                  {(field) => (
                    <View>
                      <TextInput {...field.props} value={field.input} />
                      {field.errors && <Text>{field.errors[0]}</Text>}
                    </View>
                  )}
                </Field>

                <Field of={todoForm} path={['todos', index, 'deadline']}>
                  {(field) => (
                    <View>
                      <TextInput
                        {...field.props}
                        value={field.input}
                        placeholder="YYYY-MM-DD"
                      />
                      {field.errors && <Text>{field.errors[0]}</Text>}
                    </View>
                  )}
                </Field>
              </View>
            ))}
            {fieldArray.errors && <Text>{fieldArray.errors[0]}</Text>}
          </View>
        )}
      </FieldArray>

      <Button title="Submit" onPress={submitForm} />
    </View>
  );
}
```

##### Path array with index

As with [nested fields](/react-native/guides/nested-fields.md), you use an array for the `path` property. The key difference is that you include the index from the `map()` function to specify which array item you're referencing. This ensures the paths update correctly when items are added, moved, or removed.

```tsx
<Field of={todoForm} path={['todos', index, 'label']}>
  {(field) => <TextInput {...field.props} value={field.input} />}
</Field>
```

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

```tsx
import { insert } from '@formisch/react-native';

<Button
  title="Add Todo"
  onPress={() =>
    insert(todoForm, {
      path: ['todos'],
      initialInput: { label: '', deadline: '' },
    })
  }
/>;
```

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:

```tsx
import { remove } from '@formisch/react-native';

<Button
  title="Delete"
  onPress={() =>
    remove(todoForm, {
      path: ['todos'],
      at: index,
    })
  }
/>;
```

##### Move method

Move an item from one position to another:

```tsx
import { move } from '@formisch/react-native';

<Button
  title="Move first to end"
  onPress={() =>
    move(todoForm, {
      path: ['todos'],
      from: 0,
      to: fieldArray.items.length - 1,
    })
  }
/>;
```

##### Swap method

Swap two items in the array:

```tsx
import { swap } from '@formisch/react-native';

<Button
  title="Swap first two"
  onPress={() =>
    swap(todoForm, {
      path: ['todos'],
      at: 0,
      and: 1,
    })
  }
/>;
```

##### Replace method

Replace an item with new data:

```tsx
import { replace } from '@formisch/react-native';

<Button
  title="Replace first"
  onPress={() =>
    replace(todoForm, {
      path: ['todos'],
      at: 0,
      initialInput: {
        label: 'New task',
        deadline: new Date().toISOString().split('T')[0],
      },
    })
  }
/>;
```

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

```tsx
const NestedSchema = v.object({
  categories: v.array(
    v.object({
      name: v.string(),
      items: v.array(
        v.object({
          title: v.string(),
        })
      ),
    })
  ),
});

<FieldArray of={form} path={['categories']}>
  {(categoryArray) => (
    <>
      {categoryArray.items.map((categoryItem, categoryIndex) => (
        <View key={categoryItem}>
          <Field of={form} path={['categories', categoryIndex, 'name']}>
            {(field) => <TextInput {...field.props} value={field.input} />}
          </Field>

          <FieldArray of={form} path={['categories', categoryIndex, 'items']}>
            {(itemArray) => (
              <>
                {itemArray.items.map((item, itemIndex) => (
                  <Field
                    key={item}
                    of={form}
                    path={[
                      'categories',
                      categoryIndex,
                      'items',
                      itemIndex,
                      'title',
                    ]}
                  >
                    {(field) => (
                      <TextInput {...field.props} value={field.input} />
                    )}
                  </Field>
                ))}
              </>
            )}
          </FieldArray>
        </View>
      ))}
    </>
  )}
</FieldArray>;
```

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:

```tsx
const TodoFormSchema = v.object({
  todos: v.pipe(
    v.array(
      v.object({
        label: v.string(),
        deadline: v.string(),
      })
    ),
    v.minLength(1),
    v.maxLength(10)
  ),
});
```

The validation errors for the field array itself are available in `fieldArray.errors` and can be displayed alongside the array.

### TypeScript

Since the library is written in TypeScript and we put a lot of emphasis on the development experience, you can expect maximum TypeScript support. Types are automatically inferred from your [Valibot schemas](/react-native/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.

```tsx
import { Field, handleSubmit, useForm } from '@formisch/react-native';
import { Button, View } from 'react-native';
import * as v from 'valibot';

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

export default function LoginScreen() {
  const loginForm = useForm({
    schema: LoginSchema,
  });

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

  const submitForm = handleSubmit(loginForm, (output) => {
    // output is fully typed based on LoginSchema
    console.log(output.email); // ✓ Type-safe
    console.log(output.username); // ✗ TypeScript error
  });

  return (
    <View>
      {/* Form fields */}
      <Button title="Login" onPress={submitForm} />
    </View>
  );
}
```

##### Input and output types

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

```tsx
import { Field, handleSubmit, useForm } from '@formisch/react-native';
import { Button, TextInput, View } from 'react-native';
import * as v from 'valibot';

const ProfileSchema = v.object({
  age: v.pipe(
    v.string(), // Input type: string (from TextInput)
    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()
  ),
});

export default function ProfileScreen() {
  const profileForm = useForm({
    schema: ProfileSchema,
  });

  const submitForm = handleSubmit(profileForm, (output) => {
    // output is: { age: number; birthDate: Date }
    console.log(output.age); // number
    console.log(output.birthDate); // Date
  });

  return (
    <View>
      <Field of={profileForm} path={['age']}>
        {(field) => (
          // field.input is string
          <TextInput
            {...field.props}
            value={field.input}
            keyboardType="numeric"
          />
        )}
      </Field>

      <Field of={profileForm} path={['birthDate']}>
        {(field) => (
          // field.input is string
          <TextInput
            {...field.props}
            value={field.input}
            placeholder="YYYY-MM-DD"
          />
        )}
      </Field>

      <Button title="Submit" onPress={submitForm} />
    </View>
  );
}
```

##### Type-safe paths

Field paths are fully type-checked. TypeScript will provide autocompletion and catch invalid paths at compile time.

```tsx
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']} />
<Field of={userForm} path={['profile', 'email']} />

// ✗ Invalid paths - TypeScript error
<Field of={userForm} path={['profile', 'age']} />
<Field of={userForm} path={['username']} />
```

#### Type-safe props

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

```tsx
import { type FormStore, handleSubmit, useForm } from '@formisch/react-native';
import { Button, View } from 'react-native';
import * as v from 'valibot';

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

export default function LoginScreen() {
  const loginForm = useForm({
    schema: LoginSchema,
  });

  return <FormContent of={loginForm} />;
}

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

function FormContent(props: FormContentProps) {
  const submitForm = handleSubmit(props.of, (output) => console.log(output));

  return (
    <View>
      {/* Form fields */}
      <Button title="Login" onPress={submitForm} />
    </View>
  );
}
```

#### Generic field components

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

```tsx
import { type FormStore, useField } from '@formisch/react-native';
import type { FunctionComponent } from 'react';
import { Text, TextInput, View } from 'react-native';
import * as v from 'valibot';

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

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

  return (
    <View>
      <Text>Email</Text>
      <TextInput
        {...field.props}
        value={field.input}
        autoCapitalize="none"
        keyboardType="email-address"
      />
      {field.errors && <Text>{field.errors[0]}</Text>}
    </View>
  );
};
```

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/react-native`. You can find all available types in our [API reference](/react-native/api/).

- [`FormStore`](/react-native/api/FormStore.md) - The form store
  type
- [`FieldStore`](/react-native/api/FieldStore.md) - The field
  store type
- [`FieldArrayStore`](/react-native/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 that receive the validated output

### 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 React Native, Angular, SolidJS, React, Vue, 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/react-native`](https://github.com/open-circle/formisch/tree/main/frameworks/react-native) is the thin user-facing layer. It provides the [`useForm`](/react-native/api/useForm.md), [`useField`](/react-native/api/useField.md) and [`useFieldArray`](/react-native/api/useFieldArray.md) hooks, the [`<Field />`](/react-native/api/Field.md) and [`<FieldArray />`](/react-native/api/FieldArray.md) components, and re-exports every method from `@formisch/methods` so you only import from a single package.

```
@formisch/react-native
  ├─ useForm, <Field />, <FieldArray />, …       (React Native-specific layer)
  └─ re-exports @formisch/methods/react-native   (focus, reset, validate, …)
         └─ @formisch/core/react-native          (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` and `<Field />` ships nothing else, even though `@formisch/react-native` 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/react-native`, `@formisch/core/react`, `@formisch/core/solid`, …), 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.react-native.ts` (or `.react.ts`, `.solid.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.

React Native shares React's rendering core, and neither has a native signal primitive. [The React Native adapter](https://github.com/open-circle/formisch/blob/main/packages/core/src/framework/index.react-native.ts) therefore re-exports [the React adapter](https://github.com/open-circle/formisch/blob/main/packages/core/src/framework/index.react.ts), which implements a small pub/sub system from scratch that exposes the `Signal<T>` shape:

```ts
export function createSignal<T>(value: T): Signal<T> {
  const subscribers = new Set<Listener>();
  return {
    get value() {
      if (listener) {
        subscribers.add(listener);
        listener[1].add(subscribers);
      }
      return value;
    },
    set value(newValue: T) {
      if (newValue !== value) {
        value = newValue;
        // notify subscribers …
      }
    },
  };
}
```

A companion [`useSignals`](https://github.com/open-circle/formisch/blob/main/frameworks/react-native/src/hooks/useSignals/useSignals.ts) hook in the React Native wrapper registers your component as a listener and forces a re-render when any signal it read changes. For frameworks that already have native signals (Solid, Preact, Vue, Svelte, Qwik), the adapter is a thin wrapper around the framework's own primitive, sometimes just a single re-export. 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. In React Native, form state lives in the same minimal pub/sub the wrapper already needs to subscribe components, with no second abstraction on top.

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 React Native, React, Solid, Vue 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 `<TextInput />`) 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`](/react-native/api/useForm.md), three layers cooperate to produce the form store you receive.

```tsx
import { useForm } from '@formisch/react-native';
import * as v from 'valibot';

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

function LoginScreen() {
  const loginForm = useForm({ schema: LoginSchema });
  // …
}
```

First, the [React Native wrapper](https://github.com/open-circle/formisch/blob/main/frameworks/react-native/src/hooks/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) inside a `useMemo`, together with a parse closure that captures your schema:

```ts
const internalFormStore = useMemo(
  () =>
    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 React Native wrapper builds the public form store you actually receive. It's a small 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 computed on demand from the field tree. The whole object is memoized so it survives re-renders:

```ts
return useMemo(
  () => ({
    [INTERNAL]: internalFormStore,
    get isSubmitting() {
      return internalFormStore.isSubmitting.value;
    },
    get isTouched() {
      return getFieldBool(internalFormStore, 'isTouched');
    },
    // …
  }),
  [internalFormStore]
);
```

At the very top of the hook body, before any of this, the wrapper calls `useSignals()` to bridge the signals into React's render cycle: it registers the component as a listener so any signal read by the getters above will trigger a re-render when it changes.

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/react-native`](https://github.com/open-circle/formisch/tree/main/frameworks/react-native), a form that uses only [`useForm`](/react-native/api/useForm.md) and [`<Field />`](/react-native/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 only the components subscribed to that specific signal re-render. 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 React Hook Form and TanStack Form, head to the [comparison](/react-native/guides/comparison.md) guide. For a closer look at how Valibot's inference flows into your editor, see [TypeScript](/react-native/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 React Hook Form

This guide walks you through migrating your React Native forms from [React Hook Form](https://react-hook-form.com) to Formisch. It covers the mental-model shift, a complete side-by-side example, a step-by-step migration path, and a mapping of React Hook Form APIs to their Formisch equivalents.

Migrating is a rewrite of the form layer, not a drop-in replacement. The mental model is different: instead of starting from a component and attaching form behavior to it, you start from a Valibot schema and build the component around it. The good news is that forms are naturally isolated units, so the rewrite happens one form at a time.

Both libraries can coexist in the same application without conflicts. You can install Formisch next to React Hook Form, migrate a single form, and remove React Hook Form once the last one is converted. Since both libraries export a hook named `useForm`, the import path determines which one a component uses.

#### Key differences

React Hook Form is component-first. You declare a TypeScript generic for your form values, wrap each input in a `Controller` addressed by string name, and attach validation either as per-field rules or through a resolver. Formisch is schema-first: a single Valibot schema is the source of types, validation rules, and form structure all at once. There is no separate generic to declare and no `defaultValues` object to keep aligned with your validation.

The most important differences at a glance:

- **Type source**: React Hook Form types come from a generic you declare on `useForm<FormValues>()`. Formisch infers all types, including field paths and the validated output, from the schema.
- **Validation location**: React Hook Form spreads validation across `Controller` rules or a resolver. Formisch defines all validation in the schema, next to the structure it validates.
- **Validation timing**: React Hook Form uses the `mode` and `reValidateMode` options. Formisch uses the equivalent `validate` and `revalidate` options with slightly different mode names.
- **Validation scope**: React Hook Form validates individual fields as they trigger. Formisch always parses the entire form against the schema in a single pass and distributes the resulting errors to the individual fields. Cross-field rules work without extra wiring, and each field still only re-renders when its own errors change.
- **Reactivity**: React Hook Form makes re-render scope your responsibility through `watch`, `useWatch`, and the `formState` Proxy with its destructuring rules. Formisch is built on fine-grained signals, so components automatically re-render when the state they read changes. There is no subscription API to manage.
- **Field binding**: In React Native, React Hook Form connects inputs through the `Controller` component, whose `render` prop hands you `value`, `onChange`, and `onBlur` to wire to your `TextInput` manually. Formisch connects fields through the headless [`Field`](/react-native/api/Field.md) component with a type-safe path array (`path={['user', 'email']}`) and a single spread of `field.props`.

If you already validate with `valibotResolver` from `@hookform/resolvers`, you are halfway there: your Valibot schema carries over to Formisch unchanged.

#### Side-by-side example

The following login form has two validated fields, displays error messages, disables the submit button while submitting, and processes the values on submission. Both versions implement identical behavior.

##### React Hook Form

```tsx
import { Controller, type SubmitHandler, useForm } from 'react-hook-form';
import { Button, Text, TextInput, View } from 'react-native';

interface LoginValues {
  email: string;
  password: string;
}

export default function LoginScreen() {
  const {
    control,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<LoginValues>({
    defaultValues: { email: '', password: '' },
  });

  const onSubmit: SubmitHandler<LoginValues> = async (values) => {
    // Process the validated form values
    console.log(values);
  };

  return (
    <View>
      <Controller
        control={control}
        name="email"
        rules={{
          required: 'Please enter your email.',
          pattern: {
            value: /^\S+@\S+\.\S+$/u,
            message: 'The email address is badly formatted.',
          },
        }}
        render={({ field: { onChange, onBlur, value } }) => (
          <TextInput
            value={value}
            onChangeText={onChange}
            onBlur={onBlur}
            autoCapitalize="none"
            keyboardType="email-address"
          />
        )}
      />
      {errors.email && <Text>{errors.email.message}</Text>}
      <Controller
        control={control}
        name="password"
        rules={{
          required: 'Please enter your password.',
          minLength: {
            value: 8,
            message: 'Your password must have 8 characters or more.',
          },
        }}
        render={({ field: { onChange, onBlur, value } }) => (
          <TextInput
            value={value}
            onChangeText={onChange}
            onBlur={onBlur}
            secureTextEntry
          />
        )}
      />
      {errors.password && <Text>{errors.password.message}</Text>}
      <Button
        title="Login"
        onPress={handleSubmit(onSubmit)}
        disabled={isSubmitting}
      />
    </View>
  );
}
```

##### Formisch

```tsx
import {
  Field,
  handleSubmit,
  type SubmitHandler,
  useForm,
} from '@formisch/react-native';
import { Button, Text, TextInput, View } from 'react-native';
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.')
  ),
});

export default function LoginScreen() {
  const loginForm = useForm({ schema: LoginSchema });

  const onSubmit: SubmitHandler<typeof LoginSchema> = async (values) => {
    // Process the validated form values
    console.log(values);
  };

  const submitForm = handleSubmit(loginForm, onSubmit);

  return (
    <View>
      <Field of={loginForm} path={['email']}>
        {(field) => (
          <View>
            <TextInput
              {...field.props}
              value={field.input}
              autoCapitalize="none"
              keyboardType="email-address"
            />
            {field.errors && <Text>{field.errors[0]}</Text>}
          </View>
        )}
      </Field>
      <Field of={loginForm} path={['password']}>
        {(field) => (
          <View>
            <TextInput {...field.props} value={field.input} secureTextEntry />
            {field.errors && <Text>{field.errors[0]}</Text>}
          </View>
        )}
      </Field>
      <Button
        title="Login"
        onPress={submitForm}
        disabled={loginForm.isSubmitting}
      />
    </View>
  );
}
```

Notice how the validation rules moved out of the JSX and into the schema, and how the `LoginValues` interface disappeared because the schema provides the types. The `Controller` wrapper with its manual `value`, `onChangeText`, and `onBlur` wiring became a `Field` that spreads `field.props`, and error messages live on each field store instead of a central `errors` object.

#### Migration steps

##### Install Formisch

Add Formisch and Valibot alongside React Hook Form. Both form libraries can run in parallel during the migration.

```bash
npm install @formisch/react-native valibot
```

See the [installation](/react-native/guides/installation.md) guide for other package managers.

##### Move validation into a Valibot schema

Translate your `Controller` rules or resolver schema into a single Valibot schema. Each rule has a direct counterpart: `required` becomes `v.nonEmpty()`, `minLength` becomes `v.minLength()`, and `pattern` usually becomes a dedicated action like `v.email()` or `v.regex()`.

```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 use `valibotResolver`, reuse your existing schema as-is. Define fields in the same order they appear in your form, because Formisch focuses the first field with an error on a failed submit. The [define your form](/react-native/guides/define-your-form.md) guide covers schema design in detail.

##### Replace the form setup

Swap React Hook Form's `useForm` for the Formisch [`useForm`](/react-native/api/useForm.md) hook. The generic and the resolver disappear, and the schema takes their place. `defaultValues` becomes `initialInput` and is optional: required string fields start as an empty string automatically, so you no longer need to list every field just to avoid `undefined` values.

```tsx
// Before
import { useForm } from 'react-hook-form';

const { control, handleSubmit, formState } = useForm<LoginValues>({
  resolver: valibotResolver(LoginSchema),
  defaultValues: { email: '', password: '' },
  mode: 'onTouched',
});
```

```tsx
// After
import { useForm } from '@formisch/react-native';

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

The `mode` and `reValidateMode` options map to `validate` and `revalidate`. See the [validation timing](#validation-timing) section below for the exact mapping.

##### Replace field bindings

Replace each `Controller` with the [`Field`](/react-native/api/Field.md) component. Instead of wiring `value`, `onChange`, and `onBlur` from the render prop by hand, you spread `field.props` onto the `TextInput` and bind `field.input` as its value. Errors move from the central `formState.errors` object to the field store, so the error display lives right next to the input.

```tsx
// Before
<>
  <Controller
    control={control}
    name="email"
    rules={{ required: 'Please enter your email.' }}
    render={({ field: { onChange, onBlur, value } }) => (
      <TextInput value={value} onChangeText={onChange} onBlur={onBlur} />
    )}
  />
  {errors.email && <Text>{errors.email.message}</Text>}
</>
```

```tsx
// After
<Field of={loginForm} path={['email']}>
  {(field) => (
    <View>
      <TextInput {...field.props} value={field.input} />
      {field.errors && <Text>{field.errors[0]}</Text>}
    </View>
  )}
</Field>
```

String paths with dots become type-safe path arrays: `name="user.email"` turns into `path={['user', 'email']}` and `name="todos.0.label"` turns into `path={['todos', 0, 'label']}`. Where you used the `useController` hook for individual field components, use the [`useField`](/react-native/api/useField.md) hook instead. The [add form fields](/react-native/guides/add-form-fields.md) guide explains both in detail.

##### Update submission handling

The submission wiring keeps the same shape: a `handleSubmit` function wraps your handler and returns a function to pass to `onPress`. The Formisch [`handleSubmit`](/methods/api/handleSubmit.md) method is standalone and takes the form store as its first argument. Your handler only runs after validation succeeds and receives the validated values, which are now typed as the schema's output.

```tsx
// Before
<Button title="Login" onPress={handleSubmit(onSubmit)} />
```

```tsx
// After
const submitForm = handleSubmit(loginForm, onSubmit);

<Button title="Login" onPress={submitForm} />;
```

You can pass the returned function to any trigger, for example a `TextInput`'s `onSubmitEditing` to submit from the keyboard. Async handlers work the same way, and `loginForm.isSubmitting` replaces `formState.isSubmitting` for the loading state. See the [handle submission](/react-native/guides/handle-submission.md) guide for details.

#### API mapping

| React Hook Form                       | Formisch                                                                                                                                                                                             |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useForm<T>(config)`                  | [`useForm`](/react-native/api/useForm.md) with `schema` (types are inferred)                                                                                                          |
| `resolver: valibotResolver(schema)`   | `schema` option                                                                                                                                                                                      |
| `defaultValues`                       | `initialInput` option                                                                                                                                                                                |
| `mode` / `reValidateMode`             | `validate` / `revalidate` options                                                                                                                                                                    |
| `<Controller name="email" />`         | [`Field`](/react-native/api/Field.md) component with `path={['email']}`                                                                                                               |
| `useController`                       | [`useField`](/react-native/api/useField.md) hook or `field.onChange`                                                                                                                  |
| `handleSubmit(onValid)`               | [`handleSubmit`](/methods/api/handleSubmit.md) method                                                                                                                                 |
| `formState.errors`                    | `field.errors` per field, [`getErrors`](/methods/api/getErrors.md), [`getDeepErrors`](/methods/api/getDeepErrors.md)                                                   |
| `formState.isDirty` / `dirtyFields`   | `form.isDirty`, `field.isDirty`, [`getDirtyInput`](/methods/api/getDirtyInput.md)                                                                                                     |
| `formState.touchedFields`             | `field.isTouched`                                                                                                                                                                                    |
| `formState.isSubmitting`              | `form.isSubmitting`                                                                                                                                                                                  |
| `formState.isSubmitted`               | `form.isSubmitted`                                                                                                                                                                                   |
| `formState.isValid`                   | `form.isValid`                                                                                                                                                                                       |
| `formState.isValidating`              | `form.isValidating`                                                                                                                                                                                  |
| `watch('name')` / `useWatch`          | `field.input`, [`getInput`](/methods/api/getInput.md)                                                                                                                                 |
| `getValues()`                         | [`getInput`](/methods/api/getInput.md)                                                                                                                                                |
| `setValue`                            | [`setInput`](/methods/api/setInput.md)                                                                                                                                                |
| `setError` / `clearErrors`            | [`setErrors`](/methods/api/setErrors.md)                                                                                                                                              |
| `trigger`                             | [`validate`](/methods/api/validate.md)                                                                                                                                                |
| `setFocus`                            | [`focus`](/methods/api/focus.md)                                                                                                                                                      |
| `reset` / `resetField`                | [`reset`](/methods/api/reset.md)                                                                                                                                                      |
| `useFieldArray`                       | [`FieldArray`](/react-native/api/FieldArray.md) component or [`useFieldArray`](/react-native/api/useFieldArray.md) hook                                                |
| `append` / `prepend` / `insert`       | [`insert`](/methods/api/insert.md)                                                                                                                                                    |
| `remove` / `move` / `swap` / `update` | [`remove`](/methods/api/remove.md), [`move`](/methods/api/move.md), [`swap`](/methods/api/swap.md), [`replace`](/methods/api/replace.md) |
| `FormProvider` / `useFormContext`     | Not needed (see notes)                                                                                                                                                                               |
| `unregister` / `shouldUnregister`     | No equivalent (see notes)                                                                                                                                                                            |

A few entries deserve extra context:

- **`FormProvider` / `useFormContext`**: The Formisch form store is a plain object. Pass it down as a prop, as our [input components](/react-native/guides/input-components.md) do, or share it through your own React context if you prefer.
- **`unregister` / `shouldUnregister`**: In Formisch, the schema defines which fields exist, independent of what is currently mounted. For conditional form shapes, model the variants in the schema, for example with `v.optional` or `v.variant`.
- **`watch` callbacks and subscriptions**: There is no subscription API because none is needed. Reading `field.input` or any form state during render is automatically reactive.
- **`trigger('name')`**: The [`validate`](/methods/api/validate.md) method always validates the entire form against the schema. The results are still distributed per field, so field-level triggering is not necessary.
- **`shouldFocusError`**: Formisch focuses the first field with an error automatically when a submit fails, following the field order of your schema.
- **`formState.isValid`**: In Formisch, `form.isValid` reflects the result of the last validation run. With the default `validate: 'submit'` timing it stays `true` until the first submit, unlike React Hook Form's `isValid`, which validates proactively. If you rely on it before the first submit, for example to disable the submit button, set `validate: 'initial'`.
- **`formState.touchedFields`**: Formisch marks a field as touched when it receives focus, while React Hook Form marks it on blur. Logic that shows errors based on touched state therefore reacts one event earlier.

#### Common patterns

##### Form state

React Hook Form exposes form state through the `formState` Proxy, which requires you to destructure the properties you use so the subscription is set up correctly. In Formisch, you read state directly from the form store. Reads are tracked through signals, so components re-render automatically and only when the state they read changes.

```tsx
// Before
const {
  formState: { isDirty, isSubmitting },
} = useForm<ProfileValues>();
<Button title="Save" disabled={!isDirty || isSubmitting} onPress={onPress} />;

// After
const profileForm = useForm({ schema: ProfileSchema });
<Button
  title="Save"
  disabled={!profileForm.isDirty || profileForm.isSubmitting}
  onPress={submitForm}
/>;
```

##### Validation timing

React Hook Form's `mode` and `reValidateMode` map to Formisch's `validate` and `revalidate`. The Formisch mode `'input'` fires on every keystroke and is what React Hook Form calls `onChange`. A separate `'change'` mode exists, but because `TextInput` emits its change on every keystroke, both behave the same in React Native, so prefer `'input'`. There are also more options like `'touch'` and `'initial'`.

```tsx
// Before
const form = useForm<Values>({
  resolver: valibotResolver(Schema),
  mode: 'onTouched',
  reValidateMode: 'onChange',
});

// After: first validation on blur, revalidation on every keystroke
const form = useForm({
  schema: Schema,
  validate: 'blur',
  revalidate: 'input',
});
```

The defaults are already close: Formisch validates on submit first and revalidates on input, similar to React Hook Form's `onSubmit` mode with `onChange` revalidation. See the [validation](/react-native/guides/validation.md) guide for all modes and for showing errors at the right time.

##### Field arrays

React Hook Form's `useFieldArray` returns `fields` with stable `id` keys plus mutation functions. Formisch provides the [`FieldArray`](/react-native/api/FieldArray.md) component, whose `items` array contains unique string identifiers to use as keys, and standalone methods like [`insert`](/methods/api/insert.md) and [`remove`](/methods/api/remove.md).

```tsx
// Before
const { fields, append, remove } = useFieldArray({ control, name: 'todos' });

<>
  {fields.map((item, index) => (
    <View key={item.id}>
      <Controller
        control={control}
        name={`todos.${index}.label`}
        render={({ field: { onChange, onBlur, value } }) => (
          <TextInput value={value} onChangeText={onChange} onBlur={onBlur} />
        )}
      />
      <Button title="Delete" onPress={() => remove(index)} />
    </View>
  ))}
  <Button title="Add" onPress={() => append({ label: '' })} />
</>;
```

```tsx
// After
import { Field, FieldArray, insert, remove } from '@formisch/react-native';

<FieldArray of={todoForm} path={['todos']}>
  {(fieldArray) => (
    <View>
      {fieldArray.items.map((item, index) => (
        <View key={item}>
          <Field of={todoForm} path={['todos', index, 'label']}>
            {(field) => <TextInput {...field.props} value={field.input} />}
          </Field>
          <Button
            title="Delete"
            onPress={() => remove(todoForm, { path: ['todos'], at: index })}
          />
        </View>
      ))}
      <Button
        title="Add"
        onPress={() =>
          insert(todoForm, { path: ['todos'], initialInput: { label: '' } })
        }
      />
    </View>
  )}
</FieldArray>;
```

Unlike `append` and `prepend`, the single `insert` method covers all positions through its optional `at` option. See the [field arrays](/react-native/guides/field-arrays.md) guide for moving, swapping, and validating arrays.

##### Reset

React Hook Form's `reset()` restores `defaultValues`, and `reset(values)` replaces them. The Formisch [`reset`](/methods/api/reset.md) method works the same way with its config object, and it also resets individual fields through the `path` option, replacing `resetField`.

```tsx
import { reset } from '@formisch/react-native';

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

// Reset with new initial input, e.g. after refetching server data
reset(profileForm, { initialInput: { name: 'Jane' } });

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

As in React Hook Form, resetting updates the baseline for dirty tracking. Text inputs in Formisch are always controlled through `value={field.input}`, so programmatic resets are reflected immediately; the same applies to non-text components that bind `field.input`, as described in the [controlled fields](/react-native/guides/controlled-fields.md) guide.

##### Non-text components

With React Hook Form, components like `Switch` are wired through `Controller`, passing the render prop's `value` and `onChange` to the component manually. In Formisch, text inputs are covered by spreading `field.props`, while non-text components bind `field.input` and set their value with `field.onChange`:

```tsx
<Field of={form} path={['cookies']}>
  {(field) => (
    <View>
      <Text>Yes, I want cookies</Text>
      <Switch value={field.input} onValueChange={field.onChange} />
    </View>
  )}
</Field>
```

Where you used `valueAsNumber` or parsed values inside a `Controller`, note that native components emit typed values: a `Switch` passes booleans and a slider passes real numbers straight to `field.onChange`, so no conversion is needed. The [special inputs](/react-native/guides/special-inputs.md) guide covers switches, sliders, radio groups, selects, and file pickers in detail.

#### Next steps

You now have everything you need to migrate your forms. Start with the [define your form](/react-native/guides/define-your-form.md) and [create your form](/react-native/guides/create-your-form.md) guides to deepen the schema-first workflow, build reusable [input components](/react-native/guides/input-components.md) to keep your migrated forms tidy, and explore the [form methods](/react-native/guides/form-methods.md) guide for everything that replaces React Hook Form's imperative API.

### Migrate from TanStack Form

This guide walks you through migrating your React Native forms from [TanStack Form](https://tanstack.com/form/latest) to Formisch. It explains the mental-model shift, shows the same form in both libraries side by side, breaks the migration into small steps, and maps common TanStack Form APIs to their Formisch equivalents.

Migrating is a rewrite of the form layer, not a drop-in replacement. The component structure often stays similar, but the way you define types, validation, and state access changes. The good news: TanStack Form supports Standard Schema validators, so if you already validate with [Valibot](https://valibot.dev), your schemas carry over unchanged.

Both libraries can coexist in the same application without conflicts. You can migrate one form at a time and remove `@tanstack/react-form` once the last form has been converted. Since both libraries export a hook named `useForm`, the import path determines which one a component uses.

#### Key differences

TanStack Form starts from a state container: you declare `defaultValues`, TypeScript infers the form's types from them, and you attach validators to the form or to individual fields, each with its own trigger like `onChange`, `onBlur`, or `onSubmit`. Reactivity is subscription-based: you opt into re-renders with `form.Subscribe` or `useStore` selectors.

Formisch starts from a schema: a single Valibot schema is the source of types, validation rules, and form structure at once. There is no `defaultValues` object to keep aligned with your types and no per-field validator configuration. Validation always parses the entire form against the schema, so cross-field rules work without extra wiring, and its timing is controlled form-wide with the `validate` and `revalidate` config. Reactivity is built on fine-grained signals wired into React's render cycle, so you read state directly from the form store and only the components that depend on it re-render.

In practice, the migration boils down to these changes:

- **Types**: Inferred from the schema instead of from `defaultValues`.
- **Validation**: Defined once in the schema instead of spread across `validators` configs; timing moves from per-validator triggers to the form-wide `validate` and `revalidate` options.
- **Field addressing**: Path arrays like `['todos', 0, 'label']` instead of interpolated string names like `` `todos[${index}].label` ``.
- **Field binding**: Spreading `field.props` instead of manually wiring `value`, `onChangeText`, and `onBlur`.
- **Submission**: A press handler created with [`handleSubmit`](/methods/api/handleSubmit.md) instead of calling `form.handleSubmit()` yourself.
- **State access**: Reading the form store directly instead of subscribing with selectors.
- **Errors**: Plain string arrays in `field.errors` instead of issue objects in `field.state.meta.errors`.

#### Side-by-side example

The following login form validates an email and a password and logs the values on submission. Both versions use the exact same Valibot schema, which TanStack Form accepts as a Standard Schema validator.

##### TanStack Form

```tsx
import { useForm } from '@tanstack/react-form';
import { Button, Text, TextInput, View } from 'react-native';
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.')
  ),
});

export default function LoginScreen() {
  const form = useForm({
    defaultValues: {
      email: '',
      password: '',
    },
    validators: {
      onChange: LoginSchema,
    },
    onSubmit: async ({ value }) => {
      console.log(value);
    },
  });

  return (
    <View>
      <form.Field name="email">
        {(field) => (
          <View>
            <TextInput
              value={field.state.value}
              onChangeText={field.handleChange}
              onBlur={field.handleBlur}
              autoCapitalize="none"
              keyboardType="email-address"
            />
            {!field.state.meta.isValid && (
              <Text>{field.state.meta.errors[0]?.message}</Text>
            )}
          </View>
        )}
      </form.Field>
      <form.Field name="password">
        {(field) => (
          <View>
            <TextInput
              value={field.state.value}
              onChangeText={field.handleChange}
              onBlur={field.handleBlur}
              secureTextEntry
            />
            {!field.state.meta.isValid && (
              <Text>{field.state.meta.errors[0]?.message}</Text>
            )}
          </View>
        )}
      </form.Field>
      <form.Subscribe selector={(state) => state.isSubmitting}>
        {(isSubmitting) => (
          <Button
            title="Login"
            onPress={() => form.handleSubmit()}
            disabled={isSubmitting}
          />
        )}
      </form.Subscribe>
    </View>
  );
}
```

##### Formisch

```tsx
import { Field, handleSubmit, useForm } from '@formisch/react-native';
import { Button, Text, TextInput, View } from 'react-native';
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.')
  ),
});

export default function LoginScreen() {
  const loginForm = useForm({
    schema: LoginSchema,
  });

  const submitForm = handleSubmit(loginForm, async (values) => {
    console.log(values);
  });

  return (
    <View>
      <Field of={loginForm} path={['email']}>
        {(field) => (
          <View>
            <TextInput
              {...field.props}
              value={field.input}
              autoCapitalize="none"
              keyboardType="email-address"
            />
            {field.errors && <Text>{field.errors[0]}</Text>}
          </View>
        )}
      </Field>
      <Field of={loginForm} path={['password']}>
        {(field) => (
          <View>
            <TextInput {...field.props} value={field.input} secureTextEntry />
            {field.errors && <Text>{field.errors[0]}</Text>}
          </View>
        )}
      </Field>
      <Button
        title="Login"
        onPress={submitForm}
        disabled={loginForm.isSubmitting}
      />
    </View>
  );
}
```

Notice what disappeared: the `defaultValues` object (required string fields start as `''` automatically), the manual `value`, `onChangeText`, and `onBlur` wiring (replaced by spreading `field.props`), and the `form.Subscribe` wrapper around the submit button (`loginForm.isSubmitting` is read directly). The `onSubmit` option moved out of the hook into the [`handleSubmit`](/methods/api/handleSubmit.md) method, which returns a ready-to-use press handler. One timing difference: the TanStack Form version validates on every change from the start, while Formisch by default waits until the first submit and then revalidates on every input. Pass `validate: 'input'` to [`useForm`](/react-native/api/useForm.md) if you want to match the TanStack Form behavior.

#### Migration steps

##### Install Formisch

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

```bash
npm install @formisch/react-native valibot
```

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

##### Move validation into a Valibot schema

If your form already passes a Valibot schema to `validators`, you can reuse it as is. If you use another Standard Schema library like Zod, or hand-written validator functions attached to fields, rewrite the rules as a single Valibot schema. Each field-level validator becomes a validation rule in the schema:

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

// Before: onChange: ({ value }) => (!value ? 'Please enter your email.' : undefined)
// After: defined once in the schema
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(), v.minLength(8)),
});
```

Define the fields in the same order they appear in your form, because Formisch focuses the first field with an error after a failed submission. See the [define your form](/react-native/guides/define-your-form.md) guide for details.

##### Replace the form setup

Swap the `useForm` import from `@tanstack/react-form` to `@formisch/react-native` and pass your schema instead of `defaultValues` and `validators`. The `onSubmit` option moves out of the hook (see below). If your `defaultValues` contained real data instead of empty placeholders, pass it as `initialInput`:

```tsx
import { useForm } from '@formisch/react-native';

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

Required string fields start as `''` automatically, so you no longer need to list every field just to initialize it. See the [create your form](/react-native/guides/create-your-form.md) guide for all configuration options.

##### Replace field bindings

Replace each `form.Field` with the [`Field`](/react-native/api/Field.md) component. String names become path arrays, and the manual event wiring becomes a spread of `field.props`:

```tsx
import { Field } from '@formisch/react-native';

<Field of={loginForm} path={['email']}>
  {(field) => (
    <View>
      <TextInput {...field.props} value={field.input} />
      {field.errors && <Text>{field.errors[0]}</Text>}
    </View>
  )}
</Field>;
```

`field.state.value` becomes `field.input`, and `field.state.meta.errors` becomes `field.errors`, which is either `null` or a non-empty array of strings, so no `.message` access is needed. For nested fields, `name="user.email"` becomes `path={['user', 'email']}` with full autocompletion from your schema. If you extracted fields into their own components, use the [`useField`](/react-native/api/useField.md) hook instead, as shown in the [add form fields](/react-native/guides/add-form-fields.md) guide.

##### Update submission handling

Replace the `form.handleSubmit()` call with the Formisch [`handleSubmit`](/methods/api/handleSubmit.md) method. Your `onSubmit` option becomes its second argument, and it receives the validated output of your schema, fully typed by [`SubmitHandler`](/core/api/SubmitHandler.md). The returned function is passed to `onPress`, or to a `TextInput`'s `onSubmitEditing` to submit from the keyboard:

```tsx
import { handleSubmit } from '@formisch/react-native';

const submitForm = handleSubmit(loginForm, async (values) => {
  await fetch('https://api.example.com/login', {
    method: 'POST',
    body: JSON.stringify(values),
  });
});

<Button title="Login" onPress={submitForm} disabled={loginForm.isSubmitting} />;
```

The handler only runs when the form input passes your schema; on a failed submission, Formisch focuses the first field with an error instead. See the [handle submission](/react-native/guides/handle-submission.md) guide for async patterns and error handling.

#### API mapping

| TanStack Form                            | Formisch                                                                                                                               |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `useForm({ defaultValues, validators })` | [`useForm`](/react-native/api/useForm.md) with `schema`                                                                 |
| `defaultValues`                          | `initialInput` (optional, types come from the schema)                                                                                  |
| `onSubmit` option of `useForm`           | Handler passed to [`handleSubmit`](/methods/api/handleSubmit.md)                                                        |
| `form.handleSubmit()` in `onPress`       | Function returned by [`handleSubmit`](/methods/api/handleSubmit.md), passed to `onPress`                                |
| `form.Field` with `name="user.email"`    | [`Field`](/react-native/api/Field.md) with `path={['user', 'email']}`                                                   |
| `field.state.value`                      | `field.input`                                                                                                                          |
| `field.handleChange`, `field.handleBlur` | Spread `field.props`, or `field.onChange` for non-text components                                                                      |
| `field.state.meta.errors`                | `field.errors`                                                                                                                         |
| `field.state.meta.isTouched`             | `field.isTouched`                                                                                                                      |
| `field.state.meta.isDirty`               | `field.isEdited` (see below)                                                                                                           |
| `field.state.meta.isDefaultValue`        | `!field.isDirty` (see below)                                                                                                           |
| `form.Subscribe`, `useStore(form.store)` | Read the form store directly (e.g. `form.isSubmitting`, `form.isDirty`)                                                                |
| `state.canSubmit`                        | No direct equivalent (see below)                                                                                                       |
| `form.state.values`                      | [`getInput`](/methods/api/getInput.md)                                                                                  |
| `form.setFieldValue(name, value)`        | [`setInput`](/methods/api/setInput.md)                                                                                  |
| `form.reset()`                           | [`reset`](/methods/api/reset.md)                                                                                        |
| `form.Field` with `mode="array"`         | [`FieldArray`](/react-native/api/FieldArray.md) or [`useFieldArray`](/react-native/api/useFieldArray.md) |
| `pushValue`, `insertValue`               | [`insert`](/methods/api/insert.md)                                                                                      |
| `removeValue`, `moveValue`               | [`remove`](/methods/api/remove.md), [`move`](/methods/api/move.md)                                       |
| `swapValues`, `replaceValue`             | [`swap`](/methods/api/swap.md), [`replace`](/methods/api/replace.md)                                     |
| `createFormHook`, `useAppForm`           | No equivalent needed (see below)                                                                                                       |
| `asyncDebounceMs`                        | No direct equivalent (see below)                                                                                                       |

A few entries deserve a short note:

- **`state.canSubmit`**: Formisch does not compute a combined "can submit" flag. The idiomatic pattern is to keep the submit button enabled and let submission trigger validation, which focuses the first invalid field. If you want a validity-based flag, `form.isValid` reflects the result of the last validation run. With the default `validate: 'submit'` timing it stays `true` until the first submit, so combine it with `validate: 'initial'` if you want TanStack-like behavior.
- **Dirty state** is split differently. 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 and turns back off when they match, like TanStack Form's `isDefaultValue` inverted.
- **`createFormHook` and `useAppForm`**: These exist in TanStack Form to pre-bind typed field components and share form configuration. Formisch does not need them, since every hook and component is already fully typed by your schema. The role of pre-bound field components is filled by regular [input components](/react-native/guides/input-components.md).
- **`asyncDebounceMs`**: Formisch has no built-in debounce option. Async rules live in the schema via `v.pipeAsync` and `v.checkAsync`, and `form.isValidating` is `true` while they run. See the [validation](/react-native/guides/validation.md) guide.

#### Common patterns

##### Form state

In TanStack Form you subscribe to state with a selector to control re-renders, either through `form.Subscribe` (as with the submit button in the side-by-side example above) or with the `useStore` hook in component logic. In Formisch you read the form store directly. The store is built on fine-grained signals wired into React's render cycle, so components re-render only when the properties they read change, without selectors:

```tsx
<Button
  title={loginForm.isSubmitting ? 'Submitting...' : 'Login'}
  onPress={submitForm}
  disabled={loginForm.isSubmitting}
/>
```

The form store exposes `isSubmitting`, `isSubmitted`, `isValidating`, `isTouched`, `isEdited`, `isDirty`, `isValid`, and `errors`. To read field values in component logic, use the [`getInput`](/methods/api/getInput.md) method, which also stays reactive inside components.

##### Validation timing

TanStack Form couples timing to each validator: the key you register a rule under (`onChange`, `onBlur`, `onSubmit`, `onMount`) decides when it runs. In Formisch, the rules live in the schema and timing is configured once for the whole form:

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

The `validate` option controls when a field is first validated (`'initial'`, `'touch'`, `'input'`, `'change'`, `'blur'`, or `'submit'`), and `revalidate` controls when it is checked again after it has an error or the form was submitted. As a rough mapping, `validators.onSubmit` corresponds to `validate: 'submit'` (the default), `validators.onBlur` to `validate: 'blur'`, `validators.onChange` to `validate: 'input'`, and `validators.onMount` to `validate: 'initial'`. Unlike TanStack Form, every validation pass parses the entire schema, so cross-field rules stay correct no matter which field triggered it. The [validation](/react-native/guides/validation.md) guide covers this in depth, including how to show errors only at the right time.

##### Field arrays

In TanStack Form you set `mode="array"` on a field, map over `field.state.value`, and address items with interpolated string names:

```tsx
<form.Field name="todos" mode="array">
  {(todosField) => (
    <View>
      {todosField.state.value.map((_, index) => (
        <form.Field key={index} name={`todos[${index}].label`}>
          {(field) => (
            <TextInput
              value={field.state.value}
              onChangeText={field.handleChange}
            />
          )}
        </form.Field>
      ))}
      <Button
        title="Add todo"
        onPress={() => todosField.pushValue({ label: '' })}
      />
    </View>
  )}
</form.Field>
```

In Formisch you use the [`FieldArray`](/react-native/api/FieldArray.md) component and standalone methods. The `items` array contains stable unique IDs to use as keys, so React correctly tracks items when they are added, moved, or removed:

```tsx
import { Field, FieldArray, insert } from '@formisch/react-native';

<FieldArray of={todoForm} path={['todos']}>
  {(fieldArray) => (
    <View>
      {fieldArray.items.map((item, index) => (
        <Field key={item} of={todoForm} path={['todos', index, 'label']}>
          {(field) => <TextInput {...field.props} value={field.input} />}
        </Field>
      ))}
      <Button
        title="Add todo"
        onPress={() =>
          insert(todoForm, { path: ['todos'], initialInput: { label: '' } })
        }
      />
    </View>
  )}
</FieldArray>;
```

The [`insert`](/methods/api/insert.md), [`remove`](/methods/api/remove.md), [`move`](/methods/api/move.md), [`swap`](/methods/api/swap.md), and [`replace`](/methods/api/replace.md) methods cover the operations of `pushValue`, `removeValue`, `moveValue`, `swapValues`, and `replaceValue`. For example, `todosField.removeValue(index)` becomes `remove(todoForm, { path: ['todos'], at: index })`. Rules like a minimum or maximum number of items move into the schema, for example `v.pipe(v.array(…), v.maxLength(10))`. See the [field arrays](/react-native/guides/field-arrays.md) guide for the full picture.

##### Reset

Where TanStack Form offers `form.reset()` to restore `defaultValues`, Formisch provides the [`reset`](/methods/api/reset.md) method, which can also target individual fields or update the baseline:

```tsx
import { reset } from '@formisch/react-native';

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

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

// Reset with a new initial input (e.g. refreshed server data)
reset(loginForm, { initialInput: { email: 'jane@example.com' } });
```

Passing `initialInput` updates the dirty-tracking baseline, which is the right tool when server data changes. Use [`setInput`](/methods/api/setInput.md) instead when you only want to change the current value.

##### Non-text components

In TanStack Form, components like `Switch` are wired manually, for example with `field.handleChange(checked)` inside the component's change handler. In Formisch, spreading `field.props` covers text inputs; non-text components bind `field.input` and set their value with `field.onChange`:

```tsx
<Field of={form} path={['cookies']}>
  {(field) => (
    <View>
      <Text>Yes, I want cookies</Text>
      <Switch value={field.input} onValueChange={field.onChange} />
    </View>
  )}
</Field>
```

Native components emit typed values, so a `Switch` passes booleans and a slider passes real numbers straight to `field.onChange` without any conversion. See the [special inputs](/react-native/guides/special-inputs.md) guide for switches, sliders, radio groups, selects, and file pickers.

#### Next steps

You now have everything you need to convert your forms one by one. To deepen your understanding of the Formisch side, read the [define your form](/react-native/guides/define-your-form.md) and [add form fields](/react-native/guides/add-form-fields.md) guides, explore the [form methods](/react-native/guides/form-methods.md) for programmatic control, and check out the [TypeScript](/react-native/guides/typescript.md) guide to get the most out of schema-based type inference.

### Migrate from Formik

This guide walks you through migrating your React Native forms from [Formik](https://formik.org) to Formisch. It covers the mental-model shift, a complete side-by-side example, a step-by-step migration path, and a mapping of Formik APIs to their Formisch equivalents.

Migrating is a rewrite of the form layer, not a drop-in replacement. The mental model shifts: instead of starting from an `initialValues` object and attaching validation to it, you start from a Valibot schema that provides values, types, and validation at once. The good news is that forms are naturally isolated units, so the rewrite happens one form at a time.

Both libraries can coexist in the same application without conflicts. You can install Formisch next to Formik, migrate a single form, and remove Formik once the last one is converted. Since both libraries export `Field`, `FieldArray`, and `useField`, the import path determines which ones a component uses.

#### Key differences

Formik is values-first. You declare an `initialValues` object, TypeScript infers your form's types from it, and validation is attached separately through a `validationSchema` written with [Yup](https://github.com/jquense/yup), a `validate` function, or `validate` props on individual fields. All form state lives in a single React state object and reaches your inputs through render props or context.

Formisch is schema-first: a single Valibot schema is the source of types, validation rules, and form structure all at once. There is no separate `initialValues` object to keep aligned with your validation, and state is read directly from a signal-based form store.

The most important differences at a glance:

- **Type source**: Formik infers types from `initialValues`, and your Yup schema is typed separately. Formisch infers all types, including field paths and the validated output, from the schema.
- **Validation location**: Formik spreads validation across `validationSchema`, the `validate` function, and field-level `validate` props. Formisch defines all validation in the schema, next to the structure it validates.
- **Validation timing**: Formik has two boolean switches, `validateOnChange` and `validateOnBlur`, both `true` by default, so validation runs on every keystroke from the start. Formisch uses the `validate` and `revalidate` options with event-based modes and by default stays quiet until the first submit.
- **Error display**: Formik computes `errors` eagerly and expects you to gate their display with the `touched` object. In Formisch, errors appear on a field only once validation has run, so no gating is needed in the default configuration.
- **Reactivity**: Formik stores all form state in React state, so every keystroke re-renders the entire `<Formik>` subtree, which is why `<FastField>` exists. Formisch is built on fine-grained signals, so each field only re-renders when its own state changes.
- **Field binding**: In React Native, Formik connects a `TextInput` manually by string name through `handleChange('email')`, `handleBlur('email')`, and `values.email`. Formisch connects fields through the headless [`Field`](/react-native/api/Field.md) component with a type-safe path array (`path={['user', 'email']}`) and a single spread of `field.props`.

If your forms already use `validationSchema`, the structure of your Yup schemas translates almost one-to-one to Valibot.

#### Side-by-side example

The following login form has two validated fields, displays error messages, disables the submit button while submitting, and processes the values on submission.

##### Formik

```tsx
import { Formik } from 'formik';
import { Button, Text, TextInput, View } from 'react-native';
import * as Yup from 'yup';

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

export default function LoginScreen() {
  return (
    <Formik
      initialValues={{ email: '', password: '' }}
      validationSchema={LoginSchema}
      onSubmit={async (values) => {
        // Process the validated form values
        console.log(values);
      }}
    >
      {({
        handleChange,
        handleBlur,
        handleSubmit,
        values,
        errors,
        touched,
        isSubmitting,
      }) => (
        <View>
          <TextInput
            value={values.email}
            onChangeText={handleChange('email')}
            onBlur={handleBlur('email')}
            autoCapitalize="none"
            keyboardType="email-address"
          />
          {touched.email && errors.email && <Text>{errors.email}</Text>}
          <TextInput
            value={values.password}
            onChangeText={handleChange('password')}
            onBlur={handleBlur('password')}
            secureTextEntry
          />
          {touched.password && errors.password && (
            <Text>{errors.password}</Text>
          )}
          <Button
            title="Login"
            onPress={() => handleSubmit()}
            disabled={isSubmitting}
          />
        </View>
      )}
    </Formik>
  );
}
```

##### Formisch

```tsx
import {
  Field,
  handleSubmit,
  type SubmitHandler,
  useForm,
} from '@formisch/react-native';
import { Button, Text, TextInput, View } from 'react-native';
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.')
  ),
});

export default function LoginScreen() {
  const loginForm = useForm({ schema: LoginSchema });

  const onSubmit: SubmitHandler<typeof LoginSchema> = async (values) => {
    // Process the validated form values
    console.log(values);
  };

  const submitForm = handleSubmit(loginForm, onSubmit);

  return (
    <View>
      <Field of={loginForm} path={['email']}>
        {(field) => (
          <View>
            <TextInput
              {...field.props}
              value={field.input}
              autoCapitalize="none"
              keyboardType="email-address"
            />
            {field.errors && <Text>{field.errors[0]}</Text>}
          </View>
        )}
      </Field>
      <Field of={loginForm} path={['password']}>
        {(field) => (
          <View>
            <TextInput {...field.props} value={field.input} secureTextEntry />
            {field.errors && <Text>{field.errors[0]}</Text>}
          </View>
        )}
      </Field>
      <Button
        title="Login"
        onPress={submitForm}
        disabled={loginForm.isSubmitting}
      />
    </View>
  );
}
```

Notice how the Yup schema became a Valibot schema that now also provides the form's types, and how `initialValues` disappeared because required string fields start as an empty string automatically. The `onSubmit` handler moved from the `Formik` component to the [`handleSubmit`](/methods/api/handleSubmit.md) method, which returns a ready-to-use press handler and passes the validated output of the schema to your callback. The render prop disappeared entirely: instead of wiring `handleChange`, `handleBlur`, and `values` to each `TextInput`, each field spreads `field.props` and renders its `field.errors` directly, without a `touched` gate. One timing difference: Formik validates on every keystroke from the start and hides the messages behind its `touched` gate, while Formisch by default validates on the first submit and then revalidates on every input. The [validation timing](#validation-timing) section below shows how to align the two.

#### Migration steps

##### Install Formisch

Add Formisch and Valibot alongside Formik. Both form libraries can run in parallel during the migration.

```bash
npm install @formisch/react-native valibot
```

See the [installation](/react-native/guides/installation.md) guide for other package managers.

##### Move validation into a Valibot schema

Translate your Yup schema, `validate` function, or field-level `validate` props into a single Valibot schema. Most Yup rules have a direct counterpart: `.required()` becomes `v.nonEmpty()`, `.min()` becomes `v.minLength()`, `.email()` becomes `v.email()`, and `.matches()` becomes `v.regex()`.

```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.')
  ),
});
```

Cross-field rules that you built with `Yup.ref`, such as a password confirmation, become schema-level checks with `v.forward` and `v.partialCheck`. 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. The [define your form](/react-native/guides/define-your-form.md) guide covers schema design in detail.

##### Replace the form setup

Whether your forms use the `useFormik` hook, the `<Formik>` component, or the `withFormik` higher-order component, they all become the same [`useForm`](/react-native/api/useForm.md) hook. There is no render-prop or HOC variant because you read state directly from the returned form store.

```tsx
// Before
import { useFormik } from 'formik';

const formik = useFormik({
  initialValues: { email: '', password: '' },
  validationSchema: LoginSchema,
  onSubmit: async (values) => {
    console.log(values);
  },
});
```

```tsx
// After
import { useForm } from '@formisch/react-native';

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

`initialValues` is replaced by the optional `initialInput`: required string fields start as an empty string automatically, so you only pass it when you have real data, such as a profile loaded from the server. The `onSubmit` option moves to the `handleSubmit` method (see below), and the `validateOnChange` and `validateOnBlur` switches map to the `validate` and `revalidate` options. See the [create your form](/react-native/guides/create-your-form.md) guide for all configuration options.

##### Replace field bindings

Replace the manual wiring of `handleChange('email')`, `handleBlur('email')`, and `values.email` with the Formisch [`Field`](/react-native/api/Field.md) component. It is headless: it never renders an input itself, and its render function spreads `field.props` onto your `TextInput` and binds `field.input` as its value, so one spread replaces all three handlers at once.

```tsx
// Before
<>
  <TextInput
    value={values.email}
    onChangeText={handleChange('email')}
    onBlur={handleBlur('email')}
  />
  {touched.email && errors.email && <Text>{errors.email}</Text>}
</>
```

```tsx
// After
<Field of={loginForm} path={['email']}>
  {(field) => (
    <View>
      <TextInput {...field.props} value={field.input} />
      {field.errors && <Text>{field.errors[0]}</Text>}
    </View>
  )}
</Field>
```

String names become type-safe path arrays: `handleChange('user.email')` turns into `path={['user', 'email']}` and ``handleChange(`todos.${index}.label`)`` turns into `path={['todos', index, 'label']}`. The `touched` gate disappears: `field.errors` is either `null` or a non-empty array of strings that is only populated once validation has run, so you render it right next to the input. Custom inputs built on Formik's `useField` map to the Formisch [`useField`](/react-native/api/useField.md) hook, which returns a single field store instead of a `[field, meta, helpers]` tuple: `meta.error` becomes `field.errors`, `meta.touched` becomes `field.isTouched`, and `helpers.setValue` becomes `field.onChange`. The [add form fields](/react-native/guides/add-form-fields.md) guide explains both in detail.

##### Update submission handling

Replace the call to Formik's `handleSubmit` with the function returned by the Formisch [`handleSubmit`](/methods/api/handleSubmit.md) method, and move the handler from the form config to its second argument. The handler only runs after validation succeeds and receives the validated values, typed as the schema's output.

```tsx
// Before
<Button title="Login" onPress={() => formik.handleSubmit()} />
```

```tsx
// After
const submitForm = handleSubmit(loginForm, async (values) => {
  console.log(values);
});

<Button title="Login" onPress={submitForm} />;
```

You can pass the returned function to any trigger, for example a `TextInput`'s `onSubmitEditing` to submit from the keyboard. `setSubmitting` disappears. Formik resets `isSubmitting` automatically only when your handler returns a promise and expects a manual `setSubmitting(false)` otherwise, while Formisch manages `loginForm.isSubmitting` in both cases. The same applies to the rest of Formik's submission bag: helpers like `resetForm` and `setFieldError` that Formik passes as the second argument are standalone methods in Formisch, such as [`reset`](/methods/api/reset.md) and [`setErrors`](/methods/api/setErrors.md), which you call with the form store from anywhere. See the [handle submission](/react-native/guides/handle-submission.md) guide for details.

#### API mapping

| Formik                                    | Formisch                                                                                                                                              |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useFormik` / `<Formik>` / `withFormik`   | [`useForm`](/react-native/api/useForm.md) with `schema` (types are inferred)                                                           |
| `initialValues`                           | `initialInput` option (optional)                                                                                                                      |
| `validationSchema` / `validate`           | `schema` option                                                                                                                                       |
| `validate` prop of `Field`                | Validation rules in the schema                                                                                                                        |
| `validateOnChange` / `validateOnBlur`     | `validate` / `revalidate` options (see notes)                                                                                                         |
| `handleChange('email')` / `values.email`  | [`Field`](/react-native/api/Field.md) with `path={['email']}`, spread `field.props` and bind `value={field.input}`                     |
| `touched.email && errors.email && <Text>` | `field.errors` rendered next to the input (see notes)                                                                                                 |
| `useField('email')`                       | [`useField`](/react-native/api/useField.md) hook with `path: ['email']`                                                                |
| `values`                                  | `field.input`, [`getInput`](/methods/api/getInput.md)                                                                                  |
| `errors`                                  | `field.errors` per field, [`getErrors`](/methods/api/getErrors.md), [`getDeepErrors`](/methods/api/getDeepErrors.md)    |
| `touched`                                 | `field.isTouched` (see notes)                                                                                                                         |
| `dirty`                                   | `form.isDirty` (see notes)                                                                                                                            |
| `isValid`                                 | `form.isValid` (see notes)                                                                                                                            |
| `isSubmitting`                            | `form.isSubmitting`                                                                                                                                   |
| `isValidating`                            | `form.isValidating`                                                                                                                                   |
| `submitCount`                             | No direct equivalent (see notes)                                                                                                                      |
| `handleSubmit` / `submitForm`             | [`handleSubmit`](/methods/api/handleSubmit.md) method, its returned function passed to `onPress`                                       |
| `handleReset` / `resetForm`               | [`reset`](/methods/api/reset.md)                                                                                                       |
| `enableReinitialize`                      | [`reset`](/methods/api/reset.md) with `initialInput` (see notes)                                                                       |
| `setFieldValue` / `setValues`             | [`setInput`](/methods/api/setInput.md)                                                                                                 |
| `setFieldError` / `setErrors`             | [`setErrors`](/methods/api/setErrors.md)                                                                                               |
| `setFieldTouched` / `setTouched`          | No direct equivalent (see notes)                                                                                                                      |
| `validateField` / `validateForm`          | [`validate`](/methods/api/validate.md) (see notes)                                                                                     |
| `<FieldArray name="todos">`               | [`FieldArray`](/react-native/api/FieldArray.md) component or [`useFieldArray`](/react-native/api/useFieldArray.md) hook |
| `push` / `unshift` / `insert`             | [`insert`](/methods/api/insert.md)                                                                                                     |
| `remove` / `pop`                          | [`remove`](/methods/api/remove.md)                                                                                                     |
| `swap` / `move` / `replace`               | [`swap`](/methods/api/swap.md), [`move`](/methods/api/move.md), [`replace`](/methods/api/replace.md)     |
| `<FastField>`                             | Not needed (see notes)                                                                                                                                |
| `useFormikContext` / `connect`            | Not needed (see notes)                                                                                                                                |
| `status` / `setStatus`                    | No equivalent (see notes)                                                                                                                             |

A few entries deserve extra context:

- **The `touched` gate**: Formik validates eagerly and computes `errors` for every field, so their display must be gated behind `touched`. Formisch populates `field.errors` only once validation has actually run for a field. With the default `validate: 'submit'` timing there is nothing to gate, and if you validate earlier, guard the display with field state like `isEdited`, as shown in the [validation](/react-native/guides/validation.md) guide.
- **`touched`**: Formisch marks a field as touched when it receives focus, while Formik marks it on blur. Logic that shows errors based on touched state therefore reacts one event earlier.
- **`dirty`**: Formik's `dirty` is comparison-based: it is `true` while `values` differs from `initialValues` and flips back off when the user reverts their changes. That matches `form.isDirty` exactly. Formisch's `form.isEdited` is the sticky variant that stays `true` once anything was edited, even after the value is changed back.
- **`isValid`**: In Formisch, `form.isValid` reflects the result of the last validation run. With the default `validate: 'submit'` timing it stays `true` until the first submit, unlike Formik's `isValid`, which is recomputed on every change. If you rely on it before the first submit, for example to disable the submit button, set `validate: 'initial'`.
- **`submitCount`**: Formisch tracks whether the form has been submitted as the boolean `form.isSubmitted` instead of a counter. If you used `submitCount > 0` to reveal errors after the first submit attempt, `form.isSubmitted` covers that. An actual attempt count requires your own state.
- **`validateField`**: The [`validate`](/methods/api/validate.md) method always validates the entire form against the schema. The results are still distributed per field, so field-level triggering is not necessary.
- **`setFieldTouched` / `setTouched`**: There is no imperative touched setter. Fields become touched automatically when they receive focus, and the custom blur handlers these helpers are typically used in are replaced by spreading `field.props`.
- **`<FastField>`**: `FastField` exists to cut down Formik's subtree re-renders. Formisch's signal-based store already re-renders each field only when its own state changes, so an opt-out component is not needed.
- **`useFormikContext` / `connect`**: The Formisch form store is a plain object. Pass it down as a prop, as our [input components](/react-native/guides/input-components.md) do, or share it through your own React context if you prefer.
- **`status` / `setStatus`**: Form-adjacent state like a submission error message is regular component state in Formisch. For errors that should live on the form itself, [`setErrors`](/methods/api/setErrors.md) sets root-level errors that appear in `form.errors`.

#### Common patterns

##### Form state

Formik hands you form state through the object returned by `useFormik` or through render props, and updating any part of it re-renders everything below the form. In Formisch, you read state directly from the form store. Reads are tracked through signals, so components re-render automatically and only when the state they read changes.

```tsx
// Before
const formik = useFormik({ initialValues, onSubmit });
<Button
  title="Save"
  onPress={() => formik.handleSubmit()}
  disabled={!formik.dirty || formik.isSubmitting}
/>;

// After
const profileForm = useForm({ schema: ProfileSchema });
const submitForm = handleSubmit(profileForm, onSubmit);
<Button
  title="Save"
  onPress={submitForm}
  disabled={!profileForm.isDirty || profileForm.isSubmitting}
/>;
```

The form store exposes `isSubmitting`, `isSubmitted`, `isValidating`, `isTouched`, `isEdited`, `isDirty`, `isValid`, and `errors`. To read field values in component logic, use the [`getInput`](/methods/api/getInput.md) method, which also stays reactive inside components.

##### Validation timing

Formik's timing options are boolean switches: `validateOnChange` and `validateOnBlur` turn whole trigger types on or off, and `validateOnMount` validates once on mount. Formisch instead distinguishes between the first validation of a field and every following one:

```tsx
// Closest match to Formik's default behavior
const loginForm = useForm({
  schema: LoginSchema,
  validate: 'input',
});
```

The `validate` option controls when a field is first validated (`'initial'`, `'touch'`, `'input'`, `'change'`, `'blur'`, or `'submit'`), and `revalidate` controls when it is checked again once it has an error or the form was submitted. With `validate: 'input'`, each field is validated from the first keystroke, like Formik's default. In practice, the behavior your users saw is closer to `validate: 'blur'` with `revalidate: 'input'`, because Formik's `touched` gate delays the first visible error until the field is left. If you disabled both switches to validate only on submit, use `validate: 'submit'` with `revalidate: 'submit'` for the same behavior. The Formisch defaults (`validate: 'submit'`, `revalidate: 'input'`) also stay quiet until the first submit, but afterwards they re-check fields on every keystroke instead of leaving stale errors until the next submit. Finally, `validateOnMount` maps to `validate: 'initial'`. The [validation](/react-native/guides/validation.md) guide covers all modes and how to show errors at the right time.

##### Field arrays

Formik's `FieldArray` provides its mutation helpers through a render prop, you map over the corresponding value from `values`, and the docs key items by index:

```tsx
// Before, inside the <Formik> render prop
<FieldArray name="todos">
  {({ push, remove }) => (
    <View>
      {values.todos.map((_, index) => (
        <View key={index}>
          <TextInput
            value={values.todos[index].label}
            onChangeText={handleChange(`todos.${index}.label`)}
          />
          <Button title="Delete" onPress={() => remove(index)} />
        </View>
      ))}
      <Button title="Add" onPress={() => push({ label: '' })} />
    </View>
  )}
</FieldArray>
```

In Formisch you use the [`FieldArray`](/react-native/api/FieldArray.md) component and standalone methods. The `items` array contains stable unique IDs to use as keys, so React correctly tracks items when they are added, moved, or removed:

```tsx
// After
import { Field, FieldArray, insert, remove } from '@formisch/react-native';

<FieldArray of={todoForm} path={['todos']}>
  {(fieldArray) => (
    <View>
      {fieldArray.items.map((item, index) => (
        <View key={item}>
          <Field of={todoForm} path={['todos', index, 'label']}>
            {(field) => <TextInput {...field.props} value={field.input} />}
          </Field>
          <Button
            title="Delete"
            onPress={() => remove(todoForm, { path: ['todos'], at: index })}
          />
        </View>
      ))}
      <Button
        title="Add"
        onPress={() =>
          insert(todoForm, { path: ['todos'], initialInput: { label: '' } })
        }
      />
    </View>
  )}
</FieldArray>;
```

The helpers map as follows: `push` becomes [`insert`](/methods/api/insert.md), which appends by default, `unshift` becomes `insert` with `at: 0`, and `insert(index, value)` becomes `insert` with the `at` option. `remove(index)` and `pop` become [`remove`](/methods/api/remove.md) with the `at` option, while `swap`, `move`, and `replace` map one-to-one. Unlike Formik's helpers, the Formisch methods are not bound to a render prop: they work anywhere you have access to the form store. Rules like a minimum or maximum number of items move into the schema, for example `v.pipe(v.array(…), v.maxLength(10))`. See the [field arrays](/react-native/guides/field-arrays.md) guide for the full picture.

##### Reset

Formik's `resetForm()` restores `initialValues`, and `resetForm({ values })` replaces them. The Formisch [`reset`](/methods/api/reset.md) method covers both through its config object and additionally resets individual fields through the `path` option.

```tsx
import { reset } from '@formisch/react-native';

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

// Reset with new initial input, e.g. after refetching server data
reset(profileForm, { initialInput: { name: 'Jane' } });

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

`reset` with `initialInput` also replaces `enableReinitialize`: instead of a flag that watches `initialValues` with deep equality, you call `reset` with the fresh data when it arrives, for example in an effect after a refetch. As in Formik, resetting updates the baseline for dirty tracking. Text inputs in Formisch are always controlled through `value={field.input}`, so programmatic resets are reflected immediately; the same applies to non-text components that bind `field.input`, as described in the [controlled fields](/react-native/guides/controlled-fields.md) guide.

##### Non-text components

Formik wires non-text components like `Switch` manually, typically with `setFieldValue` inside the component's change handler. In Formisch, text inputs are covered by spreading `field.props`, while non-text components bind `field.input` and set their value with `field.onChange`:

```tsx
<Field of={form} path={['cookies']}>
  {(field) => (
    <View>
      <Text>Yes, I want cookies</Text>
      <Switch value={field.input} onValueChange={field.onChange} />
    </View>
  )}
</Field>
```

Because native components emit typed values, a `Switch` passes booleans and a slider passes real numbers straight to `field.onChange`, so no string parsing is needed. The [special inputs](/react-native/guides/special-inputs.md) guide covers switches, sliders, radio groups, selects, and file pickers in detail.

#### Next steps

You now have everything you need to migrate your forms one at a time. Start with the [define your form](/react-native/guides/define-your-form.md) and [create your form](/react-native/guides/create-your-form.md) guides to deepen the schema-first workflow, build reusable [input components](/react-native/guides/input-components.md) to replace your Formik field components, and explore the [form methods](/react-native/guides/form-methods.md) guide for everything that replaces Formik's imperative helpers.