# NotForm

> Vue forms without the friction.

Canonical Origin: https://notformdocs.vercel.app/

## LLM Resources

- [Full Content](https://notformdocs.vercel.app/llms-full.txt): Complete page content in markdown format.

---

- **Page:** NotForm - Vue Forms without the friction
- **Source:** https://notformdocs.vercel.app/
- **Description:** Vue forms without the friction.

```yaml
meta:
  og:image: https://notformdocs.vercel.app/_og/s/o_65377eab73c456c4.png
  og:image:height: "600"
  og:image:type: image/png
  og:image:width: "1200"
  twitter:image: https://notformdocs.vercel.app/_og/s/o_65377eab73c456c4.png
```

# Vue Forms <br> without the friction.

Headless form state and validation library for Vue 3. Bring your own schema, keep your own components, and stay in control of every interaction.

[**Read the Docs **](https://notformdocs.vercel.app/docs/getting-started/introduction) [** Try the Playground **](https://notformdocs.vercel.app/playground)

- **Bring your own schema**

  Use Zod, Valibot, ArkType, or any Standard Schema validator. Your validation library stays completely separate from your form state.
- **Headless by design**

  Headless components and composables give you state, events, and validation without forcing a design system, markup structure, or styling approach.
- **Isolated form instances**

  Keep multiple independent forms on the same page. Every form owns its own values, errors, lifecycle, and submission state.
- **Granular validation**

  Validate everything or target a specific field, object, or array scope. Choose when validation runs with blur, change, input, or manually.
- **First-class arrays**

  Append, prepend, insert, update, remove, swap, and move array items while keeping their associated state in sync.
- **Stable dynamic fields**

  Stable array item keys keep reordered fields tied to the right item, avoiding the remount and state-shuffling problems of index-based keys.
- **Type-safe by default**

  Field paths, values, and schema input types are inferred from your schema, so invalid paths and incompatible values are caught before runtime.
- **Async-safe validation**

  Async validation stays predictable even when values change while validation is in flight. Stale results cannot overwrite newer form state.
- **Server error handling**

  Set server-side issues directly onto fields, render them through the same error system, and keep server errors alongside schema validation.

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://notformdocs.vercel.app/#website","@type":"WebSite","description":"Vue forms without the friction.","name":"NotForm","url":"https://notformdocs.vercel.app/","publisher":{"@id":"https://notformdocs.vercel.app/#identity"}},{"@id":"https://notformdocs.vercel.app/#webpage","@type":"WebPage","description":"Vue forms without the friction.","url":"https://notformdocs.vercel.app/","about":{"@id":"https://notformdocs.vercel.app/#identity"},"isPartOf":{"@id":"https://notformdocs.vercel.app/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://notformdocs.vercel.app/"]}]},{"@id":"https://notformdocs.vercel.app/#identity","applicationCategory":"DeveloperApplication","description":"Vue forms without the friction.","name":"NotForm","operatingSystem":"Web","url":"https://notformdocs.vercel.app","@type":["Organization","SoftwareApplication"],"aggregateRating":{"@type":"AggregateRating","bestRating":"5","ratingValue":"4.9","reviewCount":"13","worstRating":"1"},"author":{"@type":"Person","name":"Favour Emeka","url":"https://favorodera.vercel.app"},"keywords":["Vue forms","Nuxt form validation","Vue 3 form library","TypeScript form validation","headless form components"],"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"},"sameAs":["https://www.npmjs.com/package/notform","https://www.npmjs.com/package/@notform/nuxt","https://github.com/favorodera/notform"]}]}
```

---

- **Page:** Playground | NotForm
- **Source:** https://notformdocs.vercel.app/playground
- **Description:** Interactive Vue 3 playground for NotForm.

```yaml
meta:
  og:image: https://notformdocs.vercel.app/_og/s/o_e48b6827c1d53a45.png
  og:image:height: "600"
  og:image:type: image/png
  og:image:width: "1200"
  twitter:image: https://notformdocs.vercel.app/_og/s/o_e48b6827c1d53a45.png
```

# NotForm Playground

Loading playground

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://notformdocs.vercel.app/#website","@type":"WebSite","description":"Vue forms without the friction.","name":"NotForm","url":"https://notformdocs.vercel.app/","publisher":{"@id":"https://notformdocs.vercel.app/#identity"}},{"@id":"https://notformdocs.vercel.app/playground#webpage","@type":"WebPage","description":"Interactive Vue 3 playground for NotForm.","name":"Playground","url":"https://notformdocs.vercel.app/playground","isPartOf":{"@id":"https://notformdocs.vercel.app/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://notformdocs.vercel.app/playground"]}]},{"@id":"https://notformdocs.vercel.app/#identity","applicationCategory":"DeveloperApplication","description":"Vue forms without the friction.","name":"NotForm","operatingSystem":"Web","url":"https://notformdocs.vercel.app","@type":["Organization","SoftwareApplication"],"aggregateRating":{"@type":"AggregateRating","bestRating":"5","ratingValue":"4.9","reviewCount":"13","worstRating":"1"},"author":{"@type":"Person","name":"Favour Emeka","url":"https://favorodera.vercel.app"},"keywords":["Vue forms","Nuxt form validation","Vue 3 form library","TypeScript form validation","headless form components"],"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"},"sameAs":["https://www.npmjs.com/package/notform","https://www.npmjs.com/package/@notform/nuxt","https://github.com/favorodera/notform"]}]}
```

---

- **Page:** Introduction
- **Source:** https://notformdocs.vercel.app/docs/getting-started/introduction
- **Description:** NotForm is a headless, schema-driven form library for Vue 3 and Nuxt. See what it does, what it leaves to you, and where to start.

NotForm manages form state for Vue 3 and Nuxt. You describe your data with a schema, NotForm turns it into a typed reactive form, and you keep full control of the markup and styling.

<code-collapse>

```vue
<script setup lang="ts">
import { Field, FieldError, Form, useForm } from 'notform'
import { z } from 'zod'

const form = useForm({
  initialValues: { email: '', message: '' },
  async onSubmit(data) {
    await fetch('/api/contact', {
      body: JSON.stringify(data),
      headers: { 'content-type': 'application/json' },
      method: 'POST',
    })
  },
  schema: z.object({
    email: z.email('Enter a valid email address.'),
    message: z.string().min(10, 'Write at least 10 characters.'),
  }),
})
</script>

<template>
  <Form :form="form">
    <Field
      v-slot="{ field }"
      :field="form.field('email')"
    >
      <label :for="field.path">Email</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        type="email"
      >

      <FieldError :errors="field" />
    </Field>

    <Field
      v-slot="{ field }"
      :field="form.field('message')"
    >
      <label :for="field.path">Message</label>

      <textarea
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
      />

      <FieldError :errors="field" />
    </Field>

    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      Send
    </button>
  </Form>
</template>
```

</code-collapse>

## What you get

- **Types from your schema.** Field paths, field values, `form.values`, and the data passed to `onSubmit` are all inferred. A mistyped path is a compile error.
- **Validation you can tune.** Choose, per field, whether blur, change, or input triggers validation, whether errors clear eagerly, and how long to debounce.
- **Stable fields.** `form.field(path)` always returns the same instance for the same path, so touched state and pending validation survive re-renders.
- **Repeatable sections.** Array fields give every item a stable identity and keep errors attached to the right item when you add, remove, move, or swap.
- **Plain, reactive state.** `isDirty`, `isSubmitting`, `isValidating`, and the rest are ordinary reactive properties. There is nothing to subscribe to.
- **Any validator.** Zod, Valibot, ArkType, or any other library that implements [Standard Schema](https://standardschema.dev).

## What NotForm leaves to you

- **UI.** NotForm renders a native `<form>` and nothing else. Inputs, labels, layout, and styling are yours, or your component library's.
- **Validation rules.** Rules are written in your schema, not in NotForm.
- **Networking.** `onSubmit` receives validated data. How you send it is up to you.
- **Global state.** Every `useForm` call creates an independent form. There is no store to configure.

## Packages

<table>
<thead>
  <tr>
    <th>
      Package
    </th>
    
    <th>
      Use it for
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        notform
      </code>
    </td>
    
    <td>
      Vue 3 and Vite applications. Import components and <code>
        useForm
      </code>
      
       explicitly.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @notform/nuxt
      </code>
    </td>
    
    <td>
      Nuxt 4 applications. Registers the same components and <code>
        useForm
      </code>
      
       as auto-imports.
    </td>
  </tr>
</tbody>
</table>

<note>

These docs describe NotForm v4. If your project uses NotForm 3.x, start with the [v3 migration guide](https://notformdocs.vercel.app/docs/migrations/notform-v3).

</note>

## How this docs is organized

<card-group>
<app-card title="Getting started" to="/docs/getting-started/installation">

Install NotForm, build your first form, and learn the mental model.

</app-card>

<app-card title="Guides" to="/docs/guides/binding-inputs">

Task-oriented explanations of binding inputs, validation, errors, submission, state, and arrays.

</app-card>

<app-card title="Recipes" to="/docs/recipes/server-errors">

Complete solutions to common problems such as server errors, async checks, and multi-step forms.

</app-card>

<app-card title="Reference" to="/docs/components/form">

Exact contracts for components, `useForm`, and every public type.

</app-card>
</card-group>

## Suggested reading order

1. [Installation](https://notformdocs.vercel.app/docs/getting-started/installation)
2. [Quickstart](https://notformdocs.vercel.app/docs/getting-started/quickstart)
3. [Core concepts](https://notformdocs.vercel.app/docs/getting-started/core-concepts)
4. [Binding inputs](https://notformdocs.vercel.app/docs/guides/binding-inputs) and [Validation](https://notformdocs.vercel.app/docs/guides/validation)
5. Whatever your form needs next: [errors](https://notformdocs.vercel.app/docs/guides/errors), [array fields](https://notformdocs.vercel.app/docs/guides/array-fields), or a [recipe](https://notformdocs.vercel.app/docs/recipes/server-errors)

Building with an AI coding assistant? See [Working with AI](https://notformdocs.vercel.app/docs/ai/working-with-ai).

---

- **Page:** Binding inputs
- **Source:** https://notformdocs.vercel.app/docs/guides/binding-inputs
- **Description:** Connect text inputs, textareas, numbers, checkboxes, radios, selects, dates, and files to NotForm fields.

Every control connects to a field the same way: write the value through `field.model`, and report interaction through `field.events`. This page shows the pattern for each native input type. For custom components, see [Custom components](https://notformdocs.vercel.app/docs/integrations/custom-components).

## The pattern

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('email')"
  >
    <label :for="field.path">Email</label>

    <input
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
      autocomplete="email"
      type="email"
    >
  </Field>
</template>
```

- `field.model` is a two-way binding to `form.values` at the field's path. Writing to it does **not** validate.
- `field.events` is `{ onBlur, onChange, onInput }`. These mark the field touched and trigger validation according to the field's configuration.
- Put `v-model` before `v-bind="field.events"`. The value must be written before the validation event reads it.

## Always give initial values

Though not mandatory, provide an entry in `initialValues` for every field you bind. Missing values reach your schema as `undefined`, so validators report their generic "expected string, received undefined" message instead of your custom one, and `isDirty` can become `true` after a user types and deletes.

```ts
const form = useForm({
  initialValues: {
    age: undefined,
    interests: [],
    name: '',
    newsletter: false
  },
  schema,
})
```

## Text, email, password, search, URL

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('name')"
  >
    <label :for="field.path">Name</label>

    <input
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
      type="text"
    >

    <FieldError :errors="field" />
  </Field>
</template>
```

Native modifiers work as usual. `v-model.trim` for example removes surrounding whitespace as the user types.

## Textarea

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('message')"
  >
    <label :for="field.path">Message</label>

    <textarea
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
      rows="4"
    />
  </Field>
</template>
```

## Number

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('quantity')"
  >
    <label :for="field.path">Quantity</label>

    <input
      :id="field.path"
      v-model.number="field.model"
      v-bind="field.events"
      type="number"
      min="0"
    >
  </Field>
</template>
```

```ts
const schema = z.object({ quantity: z.number().min(1, 'Order at least one.') })
// initialValues: { quantity: 1 }
```

`v-model.number` converts typed text to a number. If the user clears the box, the browser reports an empty string, which a `z.number()` schema rejects with its type message. Set a custom type message in your schema, or keep the input as a string and convert in the schema. See [Schema input and output](https://notformdocs.vercel.app/docs/guides/schema-input-output).

## Single checkbox

Bind a boolean.

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('acceptTerms')"
  >
    <label>
      <input
        v-model="field.model"
        v-bind="field.events"
        type="checkbox"
      >
      I accept the terms
    </label>

    <FieldError :errors="field" />
  </Field>
</template>
```

```ts
const schema = z.object({
  acceptTerms: z.boolean('You must accept the terms.'),
})
// initialValues: { acceptTerms: false }
```

## Checkbox group

Bind one field to an array of the selected values. Each checkbox has its own `:value`.

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('interests')"
  >
    <fieldset>
      <legend>Interests</legend>

      <label
        v-for="option in ['design', 'code', 'writing']"
        :key="option"
      >
        <input
          v-model="field.model"
          v-bind="field.events"
          type="checkbox"
          :value="option"
        >
        {{ option }}
      </label>
    </fieldset>

    <FieldError :errors="field" />
  </Field>
</template>
```

```ts
const schema = z.object({
  interests: z.array(z.string()).min(1, 'Pick at least one.'),
})
// initialValues: { interests: [] }
```

<note>

A checkbox group is a plain `form.field()` whose value happens to be an array of fixed choices. Use [`form.arrayField()`](https://notformdocs.vercel.app/docs/guides/array-fields) when users add, remove, or reorder rows of structured data.

</note>

## Radio group

All radios share one field and differ by `:value`.

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('plan')"
  >
    <fieldset>
      <legend>Plan</legend>

      <label
        v-for="option in ['free', 'pro']"
        :key="option"
      >
        <input
          v-model="field.model"
          v-bind="field.events"
          type="radio"
          :value="option"
        >
        {{ option }}
      </label>
    </fieldset>

    <FieldError :errors="field" />
  </Field>
</template>
```

## Select

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('nationality')"
  >
    <label :for="field.path">Nationality</label>

    <select
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
    >
      <option
        value=""
        disabled
      >
        Choose a country
      </option>

      <option
        v-for="country in countries"
        :key="country.code"
        :value="country.code"
      >
        {{ country.name }}
      </option>
    </select>

    <FieldError :errors="field" />
  </Field>
</template>
```

For `<select multiple>`, bind an array exactly like a checkbox group.

## Dates and times

Native date and time inputs produce **strings** such as `2026-11-02`. Bind them like text, and validate or transform them in the schema.

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('birthday')"
  >
    <label :for="field.path">Birthday</label>

    <input
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
      type="date"
    >

    <FieldError :errors="field" />
  </Field>
</template>
```

## Files

`v-model` does not work on file inputs. Write the file with an event handler instead and report the change yourself.

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('avatar')"
  >
    <label :for="field.path">Avatar</label>

    <input
      :id="field.path"
      type="file"
      @change="(event) => {
        field.model = (event.target as HTMLInputElement).files?.[0]
        field.events.onChange()
      }"
      @blur="field.events.onBlur"
    >

    <FieldError :errors="field" />
  </Field>
</template>
```

## Skipping the Field component

`Field` only hands the field to its slot. If you prefer, create the field in script and use it directly. This is common in reusable input components.

```vue
<script setup lang="ts">
const email = form.field('email')
</script>

<template>
  <input
    v-bind="email.events"
    :id="email.path"
    v-model="email.model"
    type="email"
    :name="email.path"
  >
</template>
```

## Labels and accessibility

- Use `field.path` for the control's `id` and the label's `for`. `field.id` is a symbol and is not valid as an HTML id.
- Mark invalid controls with `:aria-invalid="!field.isValid"`.
- Link errors to controls with `aria-describedby`. See [Errors](https://notformdocs.vercel.app/docs/guides/errors#accessible-error-markup).

## Next steps

- [Validation](https://notformdocs.vercel.app/docs/guides/validation) controls when errors appear.
- [Errors](https://notformdocs.vercel.app/docs/guides/errors) covers rendering every kind of error.

---

- **Page:** Core concepts
- **Source:** https://notformdocs.vercel.app/docs/getting-started/core-concepts
- **Description:** The mental model behind NotForm: the schema, the form instance, fields, paths, the initial-values baseline, and what happens on every keystroke and submit.

Everything in NotForm follows from a handful of ideas. Read this page once and the rest of the documentation becomes predictable.

## The schema is the source of truth

You pass an **object** schema to `useForm`. NotForm derives three things from it:

- the type of `form.values`, which is the schema's **input**;
- the paths that `form.field()` and `form.arrayField()` accept;
- the type of the data that `onSubmit` receives, which is the schema's **output**.

The schema also performs all validation. NotForm has no rule syntax of its own.

Input and output can differ. A schema that turns the text `'42'` into the number `42` has input `{ age: string }` and output `{ age: number }`. Inputs bind to the values users edit. Outputs are what your code receives. See [Schema input and output](https://notformdocs.vercel.app/docs/guides/schema-input-output).

## One form instance owns the state

`useForm` returns a reactive form instance. It owns:

- `values`: the live, editable data;
- `errors`: the current list of validation issues;
- state flags such as `isDirty`, `isSubmitting`, and `isValidating`;
- actions such as `submit`, `validate`, `reset`, `setError`, and `setValue`.

You read state directly (`form.isDirty`, not `form.isDirty.value`) and pass the instance to `<Form :form="form">`.

## Fields are handles, not copies

`form.field('email')` does not store a value. It returns a handle whose `model` reads and writes `form.values.email`, and whose `errors`, `isTouched`, `isDirty`, and events are scoped to that path.

Fields are **cached by path**. Calling `form.field('email')` again, including on every render, returns the same instance with the same `id`. That is why touched state and pending validation survive re-renders.

Consequence: the optional configuration passed to `form.field(path, config)` is read **once**, on the first call for that path.

`Field` is a convenience component that hands a field to its slot. It is optional. A field is also usable straight from script.

## Paths are strings; issue paths are segments

You address values with dot-notation **paths**: `'email'`, `'address.city'`, `'contacts.0.email'`. Paths are checked against the schema input.

Validators report where an issue occurred as an array of **segments**: `['address', 'city']`. When you set errors yourself, you write segments:

```ts
form.setError({ message: 'Already taken.', path: ['username'] })
```

An issue with no `path` applies to the whole form.

## Initial values are a baseline

`initialValues` and `initialErrors` define the baseline. The form compares against it to compute `isDirty`, and `reset()` restores it. `reset(values, errors)` replaces the baseline, which is how you load saved data into an edit form.

## What happens when a user types

1. The input updates `field.model`, which writes into `form.values`.
2. The input's event (`input`, `change`, or `blur`) calls the matching handler in `field.events`.
3. The handler checks the field's configuration: is this event enabled, or is the field in eager mode with an existing error?
4. If a debounce is configured, validation waits for a pause. Blur never waits.
5. NotForm validates a snapshot of the whole form with your schema.
6. Only the issues at this field's exact path replace the field's errors.
7. If the user changed any value while validation was running, the result is discarded as **stale** and the errors are left alone.

Details are in [Validation](https://notformdocs.vercel.app/docs/guides/validation).

## What happens when a user submits

1. If a submit is already running, the new one is ignored.
2. `isSubmitting` becomes `true` and `submitCount` increases. Every field now counts as touched.
3. The whole form is validated.
4. If a value changed while validating, validation runs again.
5. If the schema reports issues, they replace all errors and `onSubmit` is **not** called.
6. If it passes, errors are cleared and `onSubmit` is awaited with the validated output.
7. `isSubmitting` returns to `false`, even if `onSubmit` throws.

Details are in [Submission and reset](https://notformdocs.vercel.app/docs/guides/submission-and-reset).

## Glossary

<table>
<thead>
  <tr>
    <th>
      Term
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Schema input
      </strong>
    </td>
    
    <td>
      The shape of <code>
        form.values
      </code>
      
      : what users edit, before parsing.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Schema output
      </strong>
    </td>
    
    <td>
      The shape <code>
        onSubmit
      </code>
      
       receives: the parsed result.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Path
      </strong>
    </td>
    
    <td>
      A dot-notation string such as <code>
        'address.city'
      </code>
      
      . Used with <code>
        form.field()
      </code>
      
       and <code>
        form.setValue()
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Segments
      </strong>
    </td>
    
    <td>
      A path as an array, such as <code>
        ['address', 'city']
      </code>
      
      . Used by issues.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Issue
      </strong>
    </td>
    
    <td>
      One validation problem: a <code>
        message
      </code>
      
       and an optional <code>
        path
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Field instance
      </strong>
    </td>
    
    <td>
      The cached handle returned by <code>
        form.field(path)
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Array field
      </strong>
    </td>
    
    <td>
      A field for an array, with <code>
        items
      </code>
      
       and mutation methods. Returned by <code>
        form.arrayField(path)
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Item
      </strong>
    </td>
    
    <td>
      One entry of an array field. It is a field for its own value and has an <code>
        index
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Baseline
      </strong>
    </td>
    
    <td>
      The current <code>
        initialValues
      </code>
      
       and <code>
        initialErrors
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Touched
      </strong>
    </td>
    
    <td>
      A field was blurred, or a submit was attempted.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Dirty
      </strong>
    </td>
    
    <td>
      Current values differ from the baseline.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Stale
      </strong>
    </td>
    
    <td>
      A validation result that was made obsolete by a newer run or a value change. It is discarded.
    </td>
  </tr>
</tbody>
</table>

## Next steps

- [Binding inputs](https://notformdocs.vercel.app/docs/guides/binding-inputs) shows how to connect every kind of control.
- [Validation](https://notformdocs.vercel.app/docs/guides/validation) explains how to tune the behavior described above.

---

- **Page:** Schema input and output
- **Source:** https://notformdocs.vercel.app/docs/guides/schema-input-output
- **Description:** Understand how NotForm types the values users edit separately from the validated data your submit handler receives.

A schema can accept one shape and produce another. NotForm keeps these two shapes distinct everywhere:

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      Input
    </th>
    
    <th>
      Output
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      What it is
    </td>
    
    <td>
      What users edit, before parsing
    </td>
    
    <td>
      What the schema produces after validating
    </td>
  </tr>
  
  <tr>
    <td>
      Where it appears
    </td>
    
    <td>
      <code>
        form.values
      </code>
      
      , <code>
        initialValues
      </code>
      
      , <code>
        field.model
      </code>
      
      , <code>
        form.setValue()
      </code>
    </td>
    
    <td>
      The argument of <code>
        onSubmit
      </code>
      
      , and <code>
        { value }
      </code>
      
       from <code>
        form.validate()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Type helper
    </td>
    
    <td>
      <code>
        SchemaInput<typeof schema>
      </code>
    </td>
    
    <td>
      <code>
        SchemaOutput<typeof schema>
      </code>
    </td>
  </tr>
</tbody>
</table>

## A transform changes the output

```ts
import { z } from 'zod'

const orderSchema = z.object({
  quantity: z.string().transform(Number),
})

const form = useForm({
  initialValues: { quantity: '2' },
  onSubmit(data) {
    data.quantity.toFixed(0) // data.quantity is a number
  },
  schema: orderSchema,
})

form.values.quantity // a string
```

The input control holds text, so the form value stays a string. Your handler receives the converted number. The same distinction applies to every Standard Schema validator.

## Common ways input and output differ

<table>
<thead>
  <tr>
    <th>
      Schema feature
    </th>
    
    <th>
      Effect on the shapes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Transform or coercion
    </td>
    
    <td>
      The output type differs from the input type.
    </td>
  </tr>
  
  <tr>
    <td>
      Default value
    </td>
    
    <td>
      The key is optional in the input and required in the output.
    </td>
  </tr>
  
  <tr>
    <td>
      Trimming or normalizing
    </td>
    
    <td>
      <code>
        form.values
      </code>
      
       keeps what the user typed. The output is normalized.
    </td>
  </tr>
  
  <tr>
    <td>
      Pipes into another schema
    </td>
    
    <td>
      The output is the final stage. The input is the first.
    </td>
  </tr>
</tbody>
</table>

Because `form.values` always holds the input, the text a user typed is never silently rewritten. Normalization happens only in the data you receive on submit.

## Initial values

`initialValues` use the **input** shape, and may be partial. They are the values controls display, so use the representation your controls and schema expect, not the parsed output.

```ts
useForm({
  initialValues: { quantity: '2' }, // input shape, not a number
  schema,
})
```

Though not mandatory, provide a value for every field you bind. A key missing from `initialValues` reaches the schema as `undefined`, and validators then report their generic type message instead of your custom one. Empty strings, `false`, and `[]` are the usual starting values for text, checkboxes, and lists.

## Typed paths and values

Paths and values for `form.field()`, `form.arrayField()`, and `form.setValue()` come from the input shape. A path that does not exist is a TypeScript error, and `setValue` checks the value type.

```ts
form.setValue('quantity', '3') // ok
form.setValue('quantity', 3) // type error: input is a string
form.field('quantty') // type error: no such path
```

## Naming the types

Import the helpers when you need to name a shape, for example in a function signature.

```ts
import type { SchemaInput, SchemaOutput } from 'notform'

type OrderInput = SchemaInput<typeof orderSchema>
type OrderOutput = SchemaOutput<typeof orderSchema>

async function saveOrder(order: OrderOutput) {
  // ...
}
```

See [TypeScript](https://notformdocs.vercel.app/docs/guides/typescript) for more patterns.

## Next steps

- [Validation](https://notformdocs.vercel.app/docs/guides/validation) explains when the schema runs.
- [Submission and reset](https://notformdocs.vercel.app/docs/guides/submission-and-reset) explains how output reaches `onSubmit`.

---

- **Page:** Quickstart
- **Source:** https://notformdocs.vercel.app/docs/getting-started/quickstart
- **Description:** Build a complete sign-in form with schema validation, field errors, a submit handler, and reset.

This page builds a sign-in form from start to finish. You will define a schema, create a form, bind two inputs, and handle submission.

It assumes you have completed [Installation](https://notformdocs.vercel.app/docs/getting-started/installation).

## 1. Define a schema

The schema describes the values the user edits and the rules they must satisfy.

```vue
<script setup lang="ts">
import { z } from 'zod'

const signInSchema = z.object({
  email: z.email('Enter a valid email address.'),
  password: z.string().min(8, 'Use at least 8 characters.'),
})
</script>
```

## 2. Create the form

`useForm` takes the schema, the starting values, and a submit handler.

```vue
<script setup lang="ts">
import { useForm } from 'notform'

const form = useForm({
  initialValues: { email: '', password: '' },
  async onSubmit(data) {
    await signIn(data)
  },
  schema: signInSchema,
})
</script>
```

- `initialValues` are what the inputs show first. See [Schema input and output](https://notformdocs.vercel.app/docs/guides/schema-input-output#initial-values).
- `onSubmit` runs only after the whole schema validates. `data` is the validated output.

## 3. Bind the fields

`form.field(path)` creates a field. `Field` hands it to your template through a slot.

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('email')"
  >
    <label :for="field.path">Email</label>

    <input
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
      autocomplete="email"
      type="email"
    >

    <FieldError :errors="field" />
  </Field>
</template>
```

- `v-model="field.model"` reads and writes the value in `form.values`.
- `v-bind="field.events"` spreads `onBlur`, `onChange`, and `onInput`, which tell NotForm when to validate.
- `FieldError` shows the first error for this field and renders nothing when there is none.

## 4. Render and submit

`Form` renders a native `<form>`. Native submit calls `form.submit`, and native reset calls `form.reset`.

<code-collapse>

```vue
<script setup lang="ts">
import { Field, FieldError, Form, useForm } from 'notform'
import { z } from 'zod'

const signInSchema = z.object({
  email: z.email('Enter a valid email address.'),
  password: z.string().min(8, 'Use at least 8 characters.'),
})

const form = useForm({
  initialValues: { email: '', password: '' },
  async onSubmit(data) {
    await signIn(data)
  },
  schema: signInSchema,
})

async function signIn(data: { email: string, password: string }) {
  await fetch('/api/sign-in', {
    body: JSON.stringify(data),
    headers: { 'content-type': 'application/json' },
    method: 'POST',
  })
}
</script>

<template>
  <Form
    :form="form"
    novalidate
  >
    <Field
      v-slot="{ field }"
      :field="form.field('email')"
    >
      <label :for="field.path">Email</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        autocomplete="email"
        type="email"
      >

      <FieldError :errors="field" />
    </Field>

    <Field
      v-slot="{ field }"
      :field="form.field('password')"
    >
      <label :for="field.path">Password</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        autocomplete="current-password"
        type="password"
      >

      <FieldError :errors="field" />
    </Field>

    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      {{ form.isSubmitting ? 'Signing in...' : 'Sign in' }}
    </button>

    <button
      type="reset"
      :disabled="form.isSubmitting"
    >
      Reset
    </button>
  </Form>
</template>
```

</code-collapse>

`novalidate` turns off the browser's built-in constraint validation so your schema controls every message.

## What you just built

<table>
<thead>
  <tr>
    <th>
      Behavior
    </th>
    
    <th>
      Why it happens
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Leaving an empty email field shows an error.
    </td>
    
    <td>
      Fields validate on <strong>
        blur
      </strong>
      
       and <strong>
        change
      </strong>
      
       by default.
    </td>
  </tr>
  
  <tr>
    <td>
      Typing does not show errors on a pristine field.
    </td>
    
    <td>
      <strong>
        Input
      </strong>
      
       events only validate after the field already has an error.
    </td>
  </tr>
  
  <tr>
    <td>
      After an error appears, fixing the value clears it as you type.
    </td>
    
    <td>
      Default <code>
        eager
      </code>
      
       mode re-validates on input once a field has an error.
    </td>
  </tr>
  
  <tr>
    <td>
      Clicking Sign in with invalid values shows every error and does not call <code>
        onSubmit
      </code>
      
      .
    </td>
    
    <td>
      Submit validates the whole form first.
    </td>
  </tr>
  
  <tr>
    <td>
      The button is disabled while the request runs.
    </td>
    
    <td>
      <code>
        form.isSubmitting
      </code>
      
       stays <code>
        true
      </code>
      
       until <code>
        onSubmit
      </code>
      
       settles.
    </td>
  </tr>
  
  <tr>
    <td>
      Reset restores the starting values and clears errors.
    </td>
    
    <td>
      <code>
        Form
      </code>
      
       calls <code>
        form.reset()
      </code>
      
       on native reset.
    </td>
  </tr>
</tbody>
</table>

## Next steps

- Learn the model behind this in [Core concepts](https://notformdocs.vercel.app/docs/getting-started/core-concepts).
- Bind checkboxes, radios, selects, and more with [Binding inputs](https://notformdocs.vercel.app/docs/guides/binding-inputs).
- Tune when errors appear in [Validation](https://notformdocs.vercel.app/docs/guides/validation).
- Show errors returned by your API with [Server errors](https://notformdocs.vercel.app/docs/recipes/server-errors).

---

- **Page:** Nuxt module
- **Source:** https://notformdocs.vercel.app/docs/getting-started/nuxt-module
- **Description:** Register @notform/nuxt to use NotForm's components and useForm as Nuxt auto-imports, and resolve naming conflicts with aliases.

`@notform/nuxt` registers NotForm's public components and composable as Nuxt auto-imports. It does not change validation, field, or submission behavior. Every other page in these docs applies unchanged.

The module requires Nuxt 4 or later. For Vue or Vite applications, use the [`notform` package](https://notformdocs.vercel.app/docs/getting-started/installation).

## Install and register

<code-group>

```bash [pnpm]
pnpm add @notform/nuxt zod
```

```bash [npm]
npm install @notform/nuxt zod
```

```bash [yarn]
yarn add @notform/nuxt zod
```

```bash [bun]
bun add @notform/nuxt zod
```

</code-group>

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@notform/nuxt'],
})
```

<tip>

Restart the dev server after changing the module list.

</tip>

## What is auto-imported

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Kind
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        useForm
      </code>
    </td>
    
    <td>
      Composable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Form
      </code>
    </td>
    
    <td>
      Component
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Field
      </code>
    </td>
    
    <td>
      Component
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ArrayField
      </code>
    </td>
    
    <td>
      Component
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FieldError
      </code>
    </td>
    
    <td>
      Component
    </td>
  </tr>
</tbody>
</table>

Your schema library is not auto-imported. Import it as usual.

<code-collapse>

```vue
<script setup lang="ts">
import { z } from 'zod'

const form = useForm({
  initialValues: { email: '' },
  onSubmit(data) {
    console.log(data.email)
  },
  schema: z.object({
    email: z.email('Enter a valid email address.')
  }),
})
</script>

<template>
  <Form :form="form">
    <Field
      v-slot="{ field }"
      :field="form.field('email')"
    >
      <label :for="field.path">Email</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        type="email"
      >

      <FieldError :errors="field" />
    </Field>

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

</code-collapse>

## Import types

Types are not auto-imported. To import them, add `notform` as a direct dependency of your app. Package managers such as pnpm do not expose a module's own dependencies to your code.

```bash
pnpm add notform
```

```ts
import type { SchemaInput, SchemaOutput, UseFormInstance } from 'notform'
```

The same applies if you prefer explicit imports of components or `useForm` over auto-imports. Both approaches work together.

## Avoid name conflicts

If your app, or another module, already defines `Form`, `Field`, `FieldError`, `ArrayField`, or `useForm`, register NotForm's version under another name with the `aliases` option. Add only the aliases you need.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@notform/nuxt'],
  notform: {
    aliases: {
      Field: 'NotField',
      FieldError: 'NotFieldError',
      Form: 'AppForm',
      useForm: 'useAppForm',
    },
  },
})
```

Then use the alias everywhere:

```vue
<template>
  <AppForm :form="form">
    <NotField
      v-slot="{ field }"
      :field="form.field('email')"
    >
      <NotFieldError :errors="field" />
    </NotField>
  </AppForm>
</template>
```

Keys are the original NotForm names. Values are the names you want to use.

<tip>

Component libraries that ship their own `Field` or `FieldError`, such as ShadcnVue, are the most common source of conflicts. See [ShadcnVue](https://notformdocs.vercel.app/docs/integrations/shadcn-vue).

</tip>

## Server-side rendering

NotForm creates form state during setup and does not need browser APIs to do it, so forms render on the server. Validation timers and event handlers only run in the browser, in response to user interaction.

## Next steps

- Build your first form with the [Quickstart](https://notformdocs.vercel.app/docs/getting-started/quickstart).
- Use NotForm with Nuxt UI in the [Nuxt UI guide](https://notformdocs.vercel.app/docs/integrations/nuxt-ui).

---

- **Page:** Installation
- **Source:** https://notformdocs.vercel.app/docs/getting-started/installation
- **Description:** Install NotForm and a schema validator in a Vue 3, Vite, or Nuxt application.

NotForm ships as two packages that expose the same API.

<table>
<thead>
  <tr>
    <th>
      Package
    </th>
    
    <th>
      Use it for
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        notform
      </code>
    </td>
    
    <td>
      Vue 3 and Vite applications.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @notform/nuxt
      </code>
    </td>
    
    <td>
      Nuxt 4 applications. Adds auto-imports for the same API.
    </td>
  </tr>
</tbody>
</table>

## Requirements

- **Vue 3.5 or later** (declared as a peer dependency of `notform`).
- **Nuxt 4 or later** when using `@notform/nuxt`.
- **A Standard Schema-compatible validator**, installed separately. The examples use Zod.
- **Node.js 24 or later**. Depending on your package manager or environment settings, an older version may warn or fail.

## Vue and Vite

Install `notform` and a validator:

<code-group>

```bash [pnpm]
pnpm add notform zod
```

```bash [npm]
npm install notform zod
```

```bash [yarn]
yarn add notform zod
```

```bash [bun]
bun add notform zod
```

</code-group>

NotForm needs no Vue plugin and no global registration. Import what you use:

```ts
import { ArrayField, Field, FieldError, Form, useForm } from 'notform'
```

## Nuxt

Install the module and a validator:

<code-group>

```bash [pnpm]
pnpm add @notform/nuxt zod
```

```bash [npm]
npm install @notform/nuxt zod
```

```bash [yarn]
yarn add @notform/nuxt zod
```

```bash [bun]
bun add @notform/nuxt zod
```

</code-group>

Register the module, then restart the dev server:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@notform/nuxt'],
})
```

`useForm`, `Form`, `Field`, `ArrayField`, and `FieldError` are now auto-imported. See the [Nuxt module guide](https://notformdocs.vercel.app/docs/getting-started/nuxt-module) for aliases and type imports.

<tip>

Code samples in these docs import from `notform` so they work anywhere. In a Nuxt project, delete the `import ... from 'notform'` line and keep the rest.

</tip>

## Choose a validator

NotForm accepts any object schema that implements [Standard Schema](https://standardschema.dev). It does not bundle a validator and does not translate rules between libraries. Switching validators changes only the schema.

<code-group>

```ts [Zod]
import { z } from 'zod'

const schema = z.object({
  email: z.email('Enter a valid email address.'),
})
```

```ts [Valibot]
import * as v from 'valibot'

const schema = v.object({
  email: v.pipe(v.string(), v.email('Enter a valid email address.')),
})
```

```ts [ArkType]
import { type } from 'arktype'

const schema = type({
  email: 'string.email',
})
```

</code-group>

<note>

Zod examples use the Zod 4 API (`z.email()`). On Zod 3, write `z.string().email()` instead. Standard Schema support requires Zod 3.24 or later, and recent releases of Valibot and ArkType.

</note>

The schema must be an **object** schema. A bare `z.string()` is rejected by TypeScript, because form values are always a keyed object.

## Verify the install

Render this component. Submitting an empty field should show the message, and a valid email should log the data.

<code-collapse>

```vue
<script setup lang="ts">
import { Field, FieldError, Form, useForm } from 'notform'
import { z } from 'zod'

const form = useForm({
  initialValues: { email: '' },
  onSubmit: (data) => {
    return console.log(data)
  },
  schema: z.object({
    email: z.email('Enter a valid email address.')
  }),
})
</script>

<template>
  <Form :form="form">
    <Field
      v-slot="{ field }"
      :field="form.field('email')"
    >
      <label :for="field.path">Email</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        type="email"
      >

      <FieldError :errors="field" />
    </Field>

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

</code-collapse>

## Next steps

Continue with the [Quickstart](https://notformdocs.vercel.app/docs/getting-started/quickstart).

---

- **Page:** Errors
- **Source:** https://notformdocs.vercel.app/docs/guides/errors
- **Description:** Render field, form-level, and section errors, add server errors, and make error messages accessible.

All errors are **issues**: an object with a `message` and an optional `path`.

```ts-type
{ message: 'Enter a valid email address.', path: ['email'] }
```

- `path` is an array of segments. Segments are property names and array indices: `['contacts', 0, 'email']`. Depending on the validator, a segment may be a string, a number, or an object with a `key`.
- An issue **without** a path is a form-level issue.

`form.errors` is the full list. Each field exposes the issues at its own exact path as `field.errors`.

## Show a field's error

`FieldError` renders the first message and nothing when there is no error.

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('email')"
  >
    <label :for="field.path">Email</label>

    <input
      v-bind="field.events"
      :id="field.path"
      v-model="field.model"
      type="email"
    >

    <FieldError :errors="field" />
  </Field>
</template>
```

Style it, change its element, or use a slot. See [FieldError](https://notformdocs.vercel.app/docs/components/field-error).

```vue
<template>
  <FieldError
    :errors="field"
    as="p"
    class="text-red-600"
    role="alert"
  />
</template>
```

## Show every error

`FieldError` shows only the first message. To list all of them, render `field.errors`.

```vue
<template>
  <ul v-if="field.errors.length > 0">
    <li
      v-for="(issue, index) in field.errors"
      :key="index"
    >
      {{ issue.message }}
    </li>
  </ul>
</template>
```

## Show form-level errors

Read `form.errors` and keep the issues without a path.

```vue
<script setup lang="ts">
import { computed } from 'vue'

const formErrors = computed(() => {
  return form.errors.filter((issue) => {
    return !issue.path?.length
  })
})
</script>

<template>
  <p
    v-for="(issue, index) in formErrors"
    :key="index"
    role="alert"
  >
    {{ issue.message }}
  </p>
</template>
```

You can also pass an issue array straight to `FieldError`: `<FieldError :errors="formErrors" as="p" role="alert" />`.

## Show errors for a section

A field shows only issues at its exact path. An issue on `['address']` does not appear on the `address.city` field. To summarize a whole section, filter by the first segment.

```ts
function keyOf(segment: PropertyKey | { key: PropertyKey }) {
  return typeof segment === 'object' ? segment.key : segment
}

function sectionErrors(section: string) {
  return form.errors.filter((issue) => {
    return issue.path?.[0] !== undefined && String(keyOf(issue.path[0])) === section
  })
}
```

## Show an error summary

After a failed submit, `form.errors` holds every problem in the form. It is the natural source for a summary at the top of a long form.

```vue
<template>
  <div
    v-if="form.isSubmitted && form.errors.length > 0"
    role="alert"
  >
    <p>Fix {{ form.errors.length }} problem(s) to continue.</p>

    <ul>
      <li
        v-for="(issue, index) in form.errors"
        :key="index"
      >
        {{ issue.message }}
      </li>
    </ul>
  </div>
</template>
```

## Add errors yourself

`form.setError(issue)` adds an error, typically after a server response.

```ts
form.setError({ message: 'This email address is already in use.', path: ['email'] })
form.setError({ message: 'We could not reach the server.' }) // form-level
```

- With a `path`, it **replaces** the errors already at that exact path.
- Without a `path`, it **appends** a form-level error. Calling it twice adds two.

See [Server errors](https://notformdocs.vercel.app/docs/recipes/server-errors) for a complete submit flow.

## Start with errors

Pass `initialErrors` when a form should open with issues, for example after a server-side render.

```ts
const form = useForm({
  initialErrors: [{ message: 'Verify this address.', path: ['email'] }],
  initialValues: { email: 'jane@example.com' },
  schema,
})
```

`reset()` returns to the current initial errors. `reset(values, errors)` replaces them.

## When errors change

<table>
<thead>
  <tr>
    <th>
      Event
    </th>
    
    <th>
      Effect on errors
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      A field validates (blur, change, input, <code>
        field.validate()
      </code>
      
      )
    </td>
    
    <td>
      Replaces only the errors at that field's exact path.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        form.validate()
      </code>
    </td>
    
    <td>
      Replaces all errors with the schema's result.
    </td>
  </tr>
  
  <tr>
    <td>
      Submit
    </td>
    
    <td>
      Replaces all errors with the schema's result. A passing submit clears them before <code>
        onSubmit
      </code>
      
       runs.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        form.setError(issue)
      </code>
    </td>
    
    <td>
      Adds or replaces errors at one path, or appends a form-level error.
    </td>
  </tr>
  
  <tr>
    <td>
      An array mutation
    </td>
    
    <td>
      Errors stay attached to the item they belong to. Removed items lose their errors. See <a href="/docs/guides/array-fields">
        Array fields
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        form.reset()
      </code>
    </td>
    
    <td>
      Restores the initial errors.
    </td>
  </tr>
</tbody>
</table>

<warning>

Because a field validation replaces the errors at its path, a server error on `email` disappears the next time `email` validates and the schema reports no problem there. Form-level server errors stay until the next submit or reset. This is usually what you want, since editing a field makes its server error stale.

</warning>

## Accessible error markup

Connect each message to its control so assistive technology announces it.

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('email')"
  >
    <label :for="field.path">Email</label>

    <input
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
      type="email"
      :aria-invalid="!field.isValid"
      :aria-describedby="field.isValid ? undefined : `${field.path}-error`"
    >

    <FieldError
      :id="`${field.path}-error`"
      :errors="field"
      role="alert"
    />
  </Field>
</template>
```

`FieldError` forwards `id`, `class`, `role`, and other attributes to the element it renders.

## Next steps

- [Submission and reset](https://notformdocs.vercel.app/docs/guides/submission-and-reset)
- [Server errors recipe](https://notformdocs.vercel.app/docs/recipes/server-errors)

---

- **Page:** Validation
- **Source:** https://notformdocs.vercel.app/docs/guides/validation
- **Description:** How NotForm validates, when each field validates, and how to tune triggers, debounce, async rules, and stale results.

Rules live in your schema. NotForm decides **when** to run the schema and **which errors** to keep.

## How validation works

NotForm always validates the whole form against a snapshot of the current values. What differs is which results are kept:

- A **field validation** is triggered by a field event or `field.validate()`. The whole schema runs, but only issues at that field's **exact path** replace that field's errors. Other errors are untouched.
- A **form validation** is triggered by `form.validate()` or a submit. Every error is replaced with the schema's result.

Three consequences are worth remembering:

1. An issue reported on a parent path such as `['address']` is not shown by the `address.city` field, and the reverse is also true.
2. A rule that spans fields must report its issue on the path of the field that should display it. See [Cross-field validation](https://notformdocs.vercel.app/docs/recipes/cross-field-validation).
3. Every field validation executes the entire schema. This matters for slow or asynchronous rules. See [Async rules and performance](#async-rules-and-performance).

## When fields validate

Each field has three trigger events. These are the defaults:

<table>
<thead>
  <tr>
    <th>
      Event
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Behavior
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        blur
      </code>
    </td>
    
    <td>
      Validates immediately
    </td>
    
    <td>
      Always marks the field touched, even if validation on blur is turned off.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        change
      </code>
    </td>
    
    <td>
      Validates
    </td>
    
    <td>
      Fires when a control commits a value, such as picking an option.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        input
      </code>
    </td>
    
    <td>
      Does not validate
    </td>
    
    <td>
      Fires while typing. Validates only if the field already has an error and the mode is <code>
        eager
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

Together with the default `eager` mode, this gives the most common behavior: no errors while a user first types, an error when they leave the field, and the error clearing as soon as they fix it.

## Configure a field

Pass a `FieldConfig` as the second argument to `form.field()` or `form.arrayField()`.

```ts
const username = form.field('username', {
  debounce: 300,
  validateOn: { input: true },
  validationMode: 'lazy',
})
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        validateOn
      </code>
    </td>
    
    <td>
      <code>
        { blur?: boolean, change?: boolean, input?: boolean }
      </code>
    </td>
    
    <td>
      <code>
        blur
      </code>
      
       and <code>
        change
      </code>
      
       on, <code>
        input
      </code>
      
       off
    </td>
    
    <td>
      Events that trigger validation. Omitted keys keep their defaults.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validationMode
      </code>
    </td>
    
    <td>
      <code>
        'eager' | 'lazy'
      </code>
    </td>
    
    <td>
      <code>
        'eager'
      </code>
    </td>
    
    <td>
      <code>
        eager
      </code>
      
      : once a field has errors, <code>
        input
      </code>
      
       and <code>
        change
      </code>
      
       re-validate it. <code>
        lazy
      </code>
      
      : only events enabled in <code>
        validateOn
      </code>
      
       validate.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        debounce
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
      
       (ms)
    </td>
    
    <td>
      none
    </td>
    
    <td>
      Delay for <code>
        input
      </code>
      
       and <code>
        change
      </code>
      
       validation. Blur and submit are never delayed.
    </td>
  </tr>
</tbody>
</table>

<warning>

The config is read once, when the field is first created. Later calls with the same path return the cached field and ignore any new config. Create each field with its config in one place, preferably in `<script setup>`.

</warning>

## Presets

<code-group>

```ts [Validate on leave (default)]
form.field('email')
```

```ts [Instant feedback]
form.field('password', { validateOn: { input: true } })
```

```ts [Validate on submit only]
form.field('notes', {
  validateOn: { blur: false, change: false },
  validationMode: 'lazy',
})
```

```ts [Debounced async check]
form.field('username', { debounce: 400, validateOn: { input: true } })
```

</code-group>

In the submit-only preset, blur still marks the field touched, but nothing validates until the user submits. After a failed submit, errors appear for every field.

## Debounce

`debounce` waits for the user to pause before validating on `input` or `change`. It collapses a burst of keystrokes into one validation, which is most useful when the schema performs network calls.

```ts
const username = form.field('username', { debounce: 400 })
```

- Blur and form submission are not delayed.
- `field.validate()` skips any pending debounce and validates immediately.
- Resetting the form cancels pending debounced validations.

## Validate explicitly

```ts
// Whole form. Replaces all errors. Does not call onSubmit.
const result = await form.validate()
if (result.issues) {
  // invalid
} else {
  result.value // parsed output
}

// One field. Skips pending debounce. Updates only that field's errors.
const outcome = await form.field('email').validate()
```

`form.isValid` does not run validation. It only reports whether the current error list is empty. See [Form state](https://notformdocs.vercel.app/docs/guides/form-state).

## Programmatic changes do not validate

Writing through `field.model`, `form.setValue()`, or `form.values` changes data but does not validate. Validate afterward if you need fresh errors.

```ts
form.setValue('country', 'NG')
await form.field('country').validate()
```

## Async rules and performance

Standard Schema validators can return promises, so async rules, such as "is this username taken?", work.

Because every field validation runs the whole schema, an async rule runs whenever **any** field validates, not only the field it belongs to. For network checks:

- debounce the field that owns the rule;
- cache results by value so unchanged values do not hit the network again;
- skip the check when cheaper rules, such as minimum length, already fail.

The [Async validation recipe](https://notformdocs.vercel.app/docs/recipes/async-validation) shows all three.

## Stale results

Validation is asynchronous, so values can change while a run is in flight. NotForm discards such results instead of overwriting newer state:

- **Any value change** marks every in-flight validation stale. Its result is dropped and the errors stay as they were. The change's own event normally starts a fresh validation.
- A newer validation of the same field replaces an older one.
- A submit in progress is never invalidated by a field or manual validation. It is re-run only when a value changes underneath it.
- Changing a reactive schema or resetting the form also marks in-flight runs stale.

You never need to manage this yourself, but it explains why a result that arrives late may not show up.

## Reactive schemas

`schema` accepts a value, a ref, or a getter. NotForm reads it each time validation runs.

```ts
const requireTaxId = ref(false)

const form = useForm({
  schema: () => {
    return requireTaxId.value ? businessSchema : personalSchema
  },
})
```

Changing the schema discards in-flight validations, but it does not re-validate or change existing errors. Call `form.validate()` after switching if you want fresh results. Keep the input shape compatible between schemas, because the typed paths come from the schema's type.

## Next steps

- [Errors](https://notformdocs.vercel.app/docs/guides/errors) shows how to render what validation finds.
- [Cross-field validation](https://notformdocs.vercel.app/docs/recipes/cross-field-validation) covers confirm-password and date ranges.

---

- **Page:** Submission and reset
- **Source:** https://notformdocs.vercel.app/docs/guides/submission-and-reset
- **Description:** Submit validated data, handle errors thrown by your submit handler, validate without submitting, and reset values, errors, and state.

## Submit with Form

`Form` renders a native `<form>`. It prevents the browser's page navigation on submit, calls `form.submit`, and handles native reset by calling `form.reset`.

```vue
<template>
  <Form :form="form">
    <!-- fields -->
    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      {{ form.isSubmitting ? 'Saving...' : 'Save' }}
    </button>

    <button
      type="reset"
      :disabled="form.isSubmitting"
    >
      Reset
    </button>
  </Form>
</template>
```

## What a submit does

1. A submit while another is still running is **ignored**.
2. `isSubmitting` becomes `true`, `submitCount` increases, and every field counts as touched.
3. The whole form is validated.
4. If a value changed while validation was running, validation runs again on the new values.
5. If the schema reports issues, they replace all errors and `onSubmit` is **not** called. `isSubmitted` is still `true`.
6. If validation passes, errors are cleared and `onSubmit` is awaited with the validated **output**.
7. `isSubmitting` becomes `false` again, even if `onSubmit` throws.

`onSubmit` can be sync or async. `isSubmitting` stays `true` for the whole duration, so you can use it to disable the button or show a spinner.

```ts
const form = useForm({
  initialValues,
  async onSubmit(data) {
    await api.save(data) // data is SchemaOutput<typeof schema>
  },
  schema,
})
```

## Errors thrown in onSubmit

If `onSubmit` throws or rejects, `isSubmitting` is reset and the error propagates out of `form.submit()`.

- When `Form` triggers the submit, the rejection goes to Vue's error handler (`app.config.errorHandler`, or `vue:error` in Nuxt) and your UI gets no error message.
- When you call `form.submit()` yourself, the returned promise rejects.

Handle expected failures inside `onSubmit` and turn them into form errors:

```ts
const form = useForm({
  async onSubmit(data) {
    try {
      await api.save(data)
    } catch {
      form.setError({ message: 'We could not save your changes. Try again.' })
    }
  }
})
```

The [Server errors recipe](https://notformdocs.vercel.app/docs/recipes/server-errors) shows how to map field-level responses as well.

## Submit programmatically

Call `form.submit()` when a submit does not start from `<Form>`, for example from a keyboard shortcut or a button outside the form element. It validates before invoking `onSubmit`.

```ts
await form.submit()
```

Passed a native submit event, it also calls `preventDefault()`. If you do not want to use `Form`, this is the equivalent markup:

```vue
<template>
  <form
    @submit="form.submit"
    @reset.prevent="form.reset"
  >
  <!-- fields -->
  </form>
</template>
```

## Validate without submitting

`form.validate()` validates the whole form, updates `form.errors`, and does not call `onSubmit`.

```ts
const result = await form.validate()

if (result.issues) {
  // show a message, scroll to the first error, etc.
} else {
  result.value // parsed output
}
```

## Reset the form

`form.reset()` returns the form to its baseline:

- `values` return to the current `initialValues`;
- `errors` return to the current `initialErrors`;
- touched state and `submitCount` are cleared, so `isTouched` and `isSubmitted` become `false`;
- pending debounced validations and in-flight validations are cancelled, along with any submit in progress;
- array items receive fresh identities, and `resetCount` increases.

Use `type="reset"` inside `<Form>`, or call `form.reset()` yourself.

<note>

Reset restores the **baseline**, not an empty form. If the baseline holds loaded data, reset returns to that data.

</note>

### Replace the baseline

Pass values, errors, or both to start from a new baseline. The values you supply **replace** the old baseline. They are not merged with it. An omitted argument keeps its current baseline.

```ts
form.reset(
  { email: 'jane@example.com' },
  [{ message: 'Verify this address.', path: ['email'] }],
)
```

The next plain `form.reset()` returns to this new baseline. Use this when saved data should become the new starting point for dirty tracking. See [Editing existing data](https://notformdocs.vercel.app/docs/recipes/editing-existing-data).

### Remount inputs after reset

`form.resetCount` increases on every reset. Use it as a `:key` on a subtree whose uncontrolled state should be discarded.

```vue
<template>
  <MyThirdPartyEditor
    :key="form.resetCount"
    v-model="form.values.body"
  />
</template>
```

### Reset after a successful submit

NotForm does not reset on its own after `onSubmit`. Do it when it suits your flow:

```ts
const form = useForm({
  async onSubmit(data) {
    await api.create(data)
    form.reset() // back to a blank form
  // or: form.reset(data) to make the saved data the new baseline
  }
})
```

## Next steps

- [Form state](https://notformdocs.vercel.app/docs/guides/form-state) lists every flag the form exposes.
- [Server errors](https://notformdocs.vercel.app/docs/recipes/server-errors)

---

- **Page:** Form state
- **Source:** https://notformdocs.vercel.app/docs/guides/form-state
- **Description:** Read reactive form and field state such as dirty, touched, valid, validating, and submitting, and avoid the common pitfalls.

State is exposed as plain reactive properties. Read only what your interface needs. Vue tracks those reads in templates and computed values, so there is nothing to subscribe to.

## Form state

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        isDirty
      </code>
    </td>
    
    <td>
      Current values differ (deep comparison) from the baseline <code>
        initialValues
      </code>
      
      . Reverting every change makes it <code>
        false
      </code>
      
       again.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isTouched
      </code>
    </td>
    
    <td>
      A field has blurred, or a submit has been attempted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isSubmitted
      </code>
    </td>
    
    <td>
      At least one submit has been attempted, even an invalid one.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isSubmitting
      </code>
    </td>
    
    <td>
      Validation or the asynchronous <code>
        onSubmit
      </code>
      
       is running.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isValidating
      </code>
    </td>
    
    <td>
      A schema validation is running.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isValid
      </code>
    </td>
    
    <td>
      The current error list is empty. It does <strong>
        not
      </strong>
      
       run validation.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        submitCount
      </code>
    </td>
    
    <td>
      Number of submit attempts. Reset to <code>
        0
      </code>
      
       by <code>
        reset()
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        resetCount
      </code>
    </td>
    
    <td>
      Number of resets. Useful as a <code>
        :key
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        errors
      </code>
    </td>
    
    <td>
      The current list of issues.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        values
      </code>
    </td>
    
    <td>
      The live input values.
    </td>
  </tr>
</tbody>
</table>

```vue
<template>
  <Form :form="form">
    <p v-if="form.isDirty">
      You have unsaved changes.
    </p>

    <p
      v-if="form.isValidating"
      role="status"
    >
      Checking values...
    </p>

    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      {{ form.isSubmitting ? 'Saving...' : 'Save' }}
    </button>
  </Form>
</template>
```

## isValid describes errors, not values

`isValid` is `true` whenever `form.errors` is empty. A pristine form with invalid values reports `isValid === true` until something validates. Two consequences:

- Do not use `:disabled="!form.isValid"` to gate submission. A pristine but invalid form reports `true`, so the button stays enabled and signals nothing. Submitting is already safe, because `onSubmit` only runs when the schema passes.
- To get a fresh answer, call `await form.validate()`, or submit.

Prefer disabling the button with `isSubmitting`, and let validation show errors after the user acts.

## Field state

Every field instance exposes its own state.

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        errors
      </code>
    </td>
    
    <td>
      Issues reported at exactly this field's path.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isValid
      </code>
    </td>
    
    <td>
      <code>
        errors
      </code>
      
       is empty.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isDirty
      </code>
    </td>
    
    <td>
      The value differs (deep comparison) from the baseline value at this path.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isTouched
      </code>
    </td>
    
    <td>
      The field blurred, or a submit was attempted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isValidating
      </code>
    </td>
    
    <td>
      The whole form, this field, or a field nested inside it is being validated.
    </td>
  </tr>
</tbody>
</table>

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('username')"
  >
    <label :for="field.path">Username</label>

    <input
      v-bind="field.events"
      :id="field.path"
      v-model="field.model"
      type="text"
      autocomplete="username"
    >

    <span v-if="field.isValidating">Checking...</span>

    <FieldError :errors="field" />
  </Field>
</template>
```

### Array fields and nested paths

An array field has the same members, with these specifics:

- `isDirty` compares the **whole array**, so editing a nested item makes the array field dirty.
- `isValidating` includes validation of fields nested in its items.
- `errors` and `isValid` refer only to issues at the array's **own** path, such as a minimum item count. They do not include item errors.
- `isTouched` becomes `true` after a submit, or when the array field's own `onBlur` fires. It is not derived from item fields.

To ask whether any item has an error, check the issue list, as described in [Errors](https://notformdocs.vercel.app/docs/guides/errors#show-errors-for-a-section).

## Common patterns

### Unsaved changes warning

```ts
import { onBeforeRouteLeave } from 'vue-router'

onBeforeRouteLeave(() => {
  if (form.isDirty && !confirm('Discard unsaved changes?')) {
    return false
  }
})
```

### Disable Save until something changed

```vue
<template>
  <button
    type="submit"
    :disabled="!form.isDirty || form.isSubmitting"
  >
    Save
  </button>
</template>
```

### Show errors only after interaction

Fields do not validate until the user acts, so errors already appear at the right time. If you add your own early validation, for example with `validateOn: { input: true }`, you can still gate the display on touch:

```vue
<template>
  <FieldError
    v-if="field.isTouched"
    :errors="field"
  />
</template>
```

## Next steps

- [useForm](https://notformdocs.vercel.app/docs/composables/use-form) lists the complete public contract.
- [Field](https://notformdocs.vercel.app/docs/components/field) documents the field members.

---

- **Page:** Form
- **Source:** https://notformdocs.vercel.app/docs/components/form
- **Description:** Render a native form element wired to a useForm instance for submit and reset.

`Form` renders a native `<form>` and connects it to the instance returned by `useForm`. It is a thin wrapper: it adds no validation of its own.

## Usage

```vue
<script setup lang="ts">
import { Form, useForm } from 'notform'
import { z } from 'zod'

const form = useForm({
  initialValues: { email: '' },
  onSubmit: (data) => {
    return console.log(data)
  },
  schema: z.object({ email: z.email() }),
})
</script>

<template>
  <Form
    :form="form"
    novalidate
    class="stack"
  >
    <!-- fields -->
    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      Submit
    </button>

    <button type="reset">
      Reset
    </button>
  </Form>
</template>
```

## Props

<field-group>
<field :required="true" name="form" type="UseFormInstance<TSchema>">

The form instance returned by `useForm`.

</field>
</field-group>

## Slots

<table>
<thead>
  <tr>
    <th>
      Slot
    </th>
    
    <th>
      Props
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      The form's contents. Read state from the <code>
        form
      </code>
      
       instance you created.
    </td>
  </tr>
</tbody>
</table>

## Behavior

<table>
<thead>
  <tr>
    <th>
      Native event
    </th>
    
    <th>
      What <code>
        Form
      </code>
      
       does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        submit
      </code>
    </td>
    
    <td>
      Calls <code>
        form.submit(event)
      </code>
      
      , which prevents the browser's page navigation, validates the whole form, and calls <code>
        onSubmit
      </code>
      
       only when valid.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reset
      </code>
    </td>
    
    <td>
      Prevents the browser's native value reset and calls <code>
        form.reset()
      </code>
      
      , restoring the baseline values and errors.
    </td>
  </tr>
</tbody>
</table>

## Attributes

Attributes such as `id`, `class`, `novalidate`, and `aria-*` are forwarded to the native `<form>` element. Add `novalidate` when you want your schema, not the browser, to produce validation messages.

## Form does not provide context

`Form` does not share the form instance with descendants, and fields do not look it up. Create each field from the instance and pass it explicitly:

```vue
<template>
  <Form :form>
    <Field
      v-slot="{ field }"
      :field="form.field('email')"
    >
      ...
    </Field>

    <ArrayField
      v-slot="{ arrayField }"
      :array-field="form.arrayField('tags')"
    >
      ...
    </ArrayField>
  </Form>
</template>
```

This is what keeps every field fully typed. It also means a field can be created and used anywhere, including outside `Form`.

## Using a plain form element

`Form` is optional. A native `<form>` with two handlers is equivalent:

```vue
<form @submit="form.submit" @reset.prevent="form.reset">
  <!-- fields -->
</form>
```

## Related

- [Submission and reset](https://notformdocs.vercel.app/docs/guides/submission-and-reset)
- [useForm](https://notformdocs.vercel.app/docs/composables/use-form)

---

- **Page:** TypeScript
- **Source:** https://notformdocs.vercel.app/docs/guides/typescript
- **Description:** Use inferred paths and values, name schema types, type wrapper components, and pass forms between components.

NotForm is typed from your schema. In most forms you never write a NotForm type by hand.

## What is inferred

```ts
const schema = z.object({
  address: z.object({
    city: z.string()
  }),
  email: z.string(),
  tags: z.array(z.string()),
})

const form = useForm({
  initialValues: {
    address: { city: '' },
    email: '',
    tags: []
  },
  schema
})

form.field('email') // FieldInstance<string>
form.field('address.city') // FieldInstance<string>
form.field('tags.0') // FieldInstance<string>
form.arrayField('tags') // ArrayFieldInstance<string>
form.field('adress') // type error: path does not exist
form.arrayField('email') // type error: 'email' is not an array
```

Inside a slot, `field` is typed from the path, so `field.model` has the right type.

## Name the schema types

```ts
import type { SchemaInput, SchemaOutput } from 'notform'

type FormValues = SchemaInput<typeof schema>
type SubmitData = SchemaOutput<typeof schema>

async function save(data: SubmitData) {
  // ...
}
```

Use these when a function takes `onSubmit` data, or when you build initial values elsewhere:

```ts
const initialValues: FormValues = {
  address: { city: '' },
  email: '',
  tags: []
}
```

`initialValues` accepts a deep-partial of the input, so you can start with only some keys. Field paths still come from the full input shape.

## Path helpers

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        InputPath<TSchema>
      </code>
    </td>
    
    <td>
      Every valid path into the input. Accepted by <code>
        form.field()
      </code>
      
       and <code>
        form.setValue()
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        InputArrayPath<TSchema>
      </code>
    </td>
    
    <td>
      Paths that point at an array. Accepted by <code>
        form.arrayField()
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        InputPathValue<TSchema, TPath>
      </code>
    </td>
    
    <td>
      The input type at a path.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OutputPath<TSchema>
      </code>
      
       / <code>
        OutputPathValue<TSchema, TPath>
      </code>
    </td>
    
    <td>
      The same, for the output shape.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ArrayItem<TArray>
      </code>
    </td>
    
    <td>
      The item type of an array type.
    </td>
  </tr>
</tbody>
</table>

```ts
import type { InputPath } from 'notform'

type FieldName = InputPath<typeof schema>
```

Path types recurse to a depth of 10. Forms nested deeper than that lose path autocomplete beyond it.

## Type a reusable input component

A wrapper takes a field instance as a prop.

<code-collapse>

```vue
<script setup lang="ts">
import { FieldError, type FieldInstance } from 'notform'

defineProps<{
  field: FieldInstance<string>
  label: string
}>()
</script>

<template>
  <div>
    <label :for="field.path">{{ label }}</label>

    <input
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
    >

    <FieldError :errors="field" />
  </div>
</template>
```

</code-collapse>

```vue
<template>
  <TextField
    :field="form.field('email')"
    label="Email"
  />
</template>
```

Array items are fields too, so `ArrayItemInstance<T>` is also accepted where a `FieldInstance<T>` is expected.

<note>

If your linter reports `vue/no-mutating-props` for `v-model="field.model"`, it is a false positive. A field instance is a reactive object designed to be written through, and you are not replacing the prop.

</note>

## Pass a form to a child component

Type the prop with `UseFormInstance`, using the schema's type.

```vue
<script setup lang="ts">
import type { UseFormInstance } from 'notform'
import type { profileSchema } from './profile-schema'

defineProps<{ form: UseFormInstance<typeof profileSchema> }>()
</script>

<template>
  <button
    type="submit"
    :disabled="form.isSubmitting || !form.isDirty"
  >
    Save
  </button>

  <button
    type="button"
    @click="form.reset()"
  >
    Discard
  </button>
</template>
```

```vue
<template>
  <Form :form="form">
    <FormActions :form="form" />
  </Form>
</template>
```

Put the schema in its own file so both components can import its type. Prefer `UseFormInstance` over `FormInstance`. It is the public contract and excludes methods meant to stay internal.

## Schema requirements

`useForm` accepts a Standard Schema whose input **and** output are objects. This is what lets paths and `form.values` be keyed. A schema such as `z.string()` fails type checking.

## Next steps

- [Types reference](https://notformdocs.vercel.app/docs/reference/types) lists every exported type.

---

- **Page:** Field
- **Source:** https://notformdocs.vercel.app/docs/components/field
- **Description:** Expose a field instance to a renderless slot to bind its model and events to any control.

`Field` renders no element. It passes a field instance to its default slot so you can connect the value and validation events to native inputs or custom components.

## Usage

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('profile.email')"
  >
    <label :for="field.path">Email</label>

    <input
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
      autocomplete="email"
      type="email"
    >

    <FieldError :errors="field" />
  </Field>
</template>
```

`form.field(path)` returns the **same cached field** for the same path. Its `model` reads and writes `form.values`. Its `events` mark interaction and trigger validation according to the field's configuration.

## Props

<field-group>
<field :required="true" name="field" type="FieldInstance<TValue>">

The field created by `form.field(path)`, or an item from `arrayField.items`.

</field>
</field-group>

## Slot props

The default slot receives `field`.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      <code>
        TValue
      </code>
    </td>
    
    <td>
      Two-way value. Assigning writes into <code>
        form.values
      </code>
      
      . Does not validate.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        events
      </code>
    </td>
    
    <td>
      <code>
        { onBlur, onChange, onInput }
      </code>
    </td>
    
    <td>
      Handlers that mark interaction and trigger validation. Spread with <code>
        v-bind
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Current dot-notation path. Follows an array item when its position changes. Use it for <code>
        id
      </code>
      
       and <code>
        for
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        symbol
      </code>
    </td>
    
    <td>
      Stable identity. Safe as a Vue key. Not valid as an HTML <code>
        id
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        errors
      </code>
    </td>
    
    <td>
      <code>
        ValidationIssue[]
      </code>
    </td>
    
    <td>
      Issues reported at exactly this path.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isDirty
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      The value differs from the baseline value at this path.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isTouched
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      The field blurred, or a submit was attempted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isValid
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        errors
      </code>
      
       is empty.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isValidating
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      The whole form, this field, or a field nested inside it is being validated.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validate()
      </code>
    </td>
    
    <td>
      <code>
        () => Promise<ValidationResult<TValue>>
      </code>
    </td>
    
    <td>
      Validate this field now, skipping any pending debounce. Resolves with <code>
        { value }
      </code>
      
       or <code>
        { issues }
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

Extra attributes passed to `Field` arrive as additional slot props. Because `Field` renders no element, attach HTML attributes to the control inside the slot.

## Configure validation

Pass options as the second argument to `form.field(path, config)`. They are read when the field is first created. See [Validation](https://notformdocs.vercel.app/docs/guides/validation#configure-a-field).

```ts
const username = form.field('username', { debounce: 300, validateOn: { input: true } })
```

## Using a field without Field

The component is a convenience. A field instance works directly:

```vue
<script setup lang="ts">
const email = form.field('email')
</script>

<template>
  <div>
    <label :for="email.path">Email</label>

    <input
      :id="email.path"
      v-model="email.model"
      v-bind="email.events"
      autocomplete="email"
      type="email"
    >

    <FieldError :errors="email" />
  </div>
</template>
```

## Related

- [Binding inputs](https://notformdocs.vercel.app/docs/guides/binding-inputs)
- [Custom components](https://notformdocs.vercel.app/docs/integrations/custom-components)
- [Form state](https://notformdocs.vercel.app/docs/guides/form-state#field-state)

---

- **Page:** FieldError
- **Source:** https://notformdocs.vercel.app/docs/components/field-error
- **Description:** Display the first validation message from a field, an array field, or an issue list.

`FieldError` displays the first message from an issue array, or from any object that has an `errors` array, such as a field, an array field, or an array item. It renders **no element** when there is no message.

## Usage

Pass a field directly:

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('email')"
  >
    <label :for="field.path">Email</label>

    <input
      v-bind="field.events"
      :id="field.path"
      v-model="field.model"
      type="email"
    >

    <FieldError :errors="field" />
  </Field>
</template>
```

Or pass an issue array:

```vue
<template>
  <FieldError
    :errors="form.errors"
    as="p"
    role="alert"
  />
</template>
```

## Props

<field-group>
<field name="errors" type="ValidationIssue[] | { readonly errors: ValidationIssue[] }" :required="true">

An issue array, or an object with an `errors` array. Only the first message is displayed.

</field>

<field name="as" type="string | Component">

Element or component that renders the message. Defaults to `span`.

</field>
</field-group>

Attributes other than `errors` and `as` are forwarded to the rendered element or component. Use `class`, `id`, `role`, and `aria-*` to match your styling and accessibility needs.

## Slot

The default slot receives `message`. Use it to wrap or decorate the text.

```vue
<template>
  <FieldError
    :errors="field"
    as="p"
    role="alert"
  >
    <template #default="{ message }">
      <strong>Check this value:</strong> {{ message }}
    </template>
  </FieldError>
</template>
```

When `as` is a component, the message is passed as its default slot content. That component must render its default slot.

## Notes

- Which issues a field shows: exactly those at its own path. An issue on a parent path or without a path is not shown. See [Errors](https://notformdocs.vercel.app/docs/guides/errors).
- To display every message, render `field.errors` yourself.
- Pass `:errors="arrayField"` to show array-level issues such as a minimum item count.

## Related

- [Errors guide](https://notformdocs.vercel.app/docs/guides/errors)

---

- **Page:** ArrayField
- **Source:** https://notformdocs.vercel.app/docs/components/array-field
- **Description:** Render array items with stable identities and mutation methods that keep values, state, and errors aligned.

`ArrayField` renders no element. It exposes an array field instance through its default slot. Create the instance with `form.arrayField(path)`.

## Usage

<code-collapse>

```vue
<template>
  <ArrayField
    v-slot="{ arrayField }"
    :array-field="form.arrayField('tags')"
  >
    <div
      v-for="item in arrayField.items"
      :key="item.id"
    >
      <Field
        v-slot="{ field }"
        :field="item"
      >
        <input
          v-model="field.model"
          v-bind="field.events"
          aria-label="Tag"
        >

        <FieldError :errors="field" />
      </Field>

      <button
        type="button"
        @click="arrayField.remove(item.index)"
      >
        Remove
      </button>
    </div>

    <FieldError :errors="arrayField" />

    <button
      type="button"
      @click="arrayField.append('')"
    >
      Add tag
    </button>
  </ArrayField>
</template>
```

</code-collapse>

<caution>

Use `item.id` as the Vue key. `index` and `path` change with position. `id` does not.

</caution>

## Props

<field-group>
<field :required="true" name="array-field" type="ArrayFieldInstance<TItem>">

The array field created by `form.arrayField(path)`.

</field>
</field-group>

## Slot props

The default slot receives `arrayField`. Extra attributes passed to `ArrayField` arrive as additional slot props.

### Field members

An array field has the regular field members `model`, `events`, `path`, `id`, `errors`, `isDirty`, `isTouched`, `isValid`, `isValidating`, and `validate()`, with these array-specific semantics:

- `errors` and `isValid` refer to issues at the array's **own** path, such as a minimum item count.
- `isDirty` compares the whole array, so nested edits count.
- `isValidating` includes validation of fields nested in its items.

### Array members

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        items
      </code>
    </td>
    
    <td>
      Item instances, in current order.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        append(value)
      </code>
    </td>
    
    <td>
      Add an item at the end.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prepend(value)
      </code>
    </td>
    
    <td>
      Add an item at the start.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        insert(index, value)
      </code>
    </td>
    
    <td>
      Insert at an index. Clamped to <code>
        0..length
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        remove(index)
      </code>
    </td>
    
    <td>
      Remove an item and its state. Ignored if out of range.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        move(from, to)
      </code>
    </td>
    
    <td>
      Move an item. Ignored if either index is out of range.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        swap(indexA, indexB)
      </code>
    </td>
    
    <td>
      Swap two items. Ignored if either index is out of range.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        update(index, value)
      </code>
    </td>
    
    <td>
      Replace an item in place. Keeps its id and touched state, drops its old errors. Ignored if out of range.
    </td>
  </tr>
</tbody>
</table>

### Item members

Each entry in `items` is a field for the item's value. It has every field member listed above, plus:

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        index
      </code>
    </td>
    
    <td>
      The item's current position.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        field(path, config?)
      </code>
    </td>
    
    <td>
      A field nested in the item, with a path relative to the item. Cached, and follows the item when it moves.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arrayField(path, config?)
      </code>
    </td>
    
    <td>
      An array field nested in the item.
    </td>
  </tr>
</tbody>
</table>

## Behavior

- Values passed to `append`, `prepend`, `insert`, and `update` are deep-cloned.
- Every mutation counts as a change event on the array field. By default it re-validates the array's own path.
- Errors inside the array are re-pointed to follow their items on every mutation.
- Reset creates fresh item ids.
- A removed item, and anything created from it, becomes inert: mutations do nothing.

Change the array only through these methods. Direct mutation such as `form.values.tags.push('x')` bypasses identity and error tracking. See [Array fields](https://notformdocs.vercel.app/docs/guides/array-fields).

## Related

- [Array fields guide](https://notformdocs.vercel.app/docs/guides/array-fields)
- [Field](https://notformdocs.vercel.app/docs/components/field)

---

- **Page:** Array fields
- **Source:** https://notformdocs.vercel.app/docs/guides/array-fields
- **Description:** Build repeatable sections with stable item identity. Add, remove, reorder, validate, and nest arrays without losing state or errors.

Use `form.arrayField(path)` for an array of values that users add, remove, or reorder. `ArrayField` exposes the array and its items through a slot.

## Render and bind items

Each item is a field for its own value, with an `id`, an `index`, and `field()` and `arrayField()` for nested values.

<code-collapse>

```vue
<script lang="ts" setup>
import { ArrayField, Field, FieldError, useForm } from 'notform'
import { z } from 'zod'

const itemSchema = z.object({
  email: z.email('Enter a valid email address.')
})

const schema = z.object({
  contacts: z.array(itemSchema)
    .min(1, 'Add at least one contact.'),
})

const form = useForm({
  initialValues: { contacts: [{ email: '' }] },
  schema,
})
</script>

<template>
  <ArrayField
    v-slot="{ arrayField }"
    :array-field="form.arrayField('contacts')"
  >
    <div
      v-for="item in arrayField.items"
      :key="item.id"
    >
      <Field
        v-slot="{ field }"
        :field="item.field('email')"
      >
        <label :for="field.path">Contact email</label>

        <input
          :id="field.path"
          v-model="field.model"
          v-bind="field.events"
          type="email"
        >

        <FieldError :errors="field" />
      </Field>

      <button
        type="button"
        @click="arrayField.remove(item.index)"
      >
        Remove
      </button>
    </div>

    <FieldError :errors="arrayField" />

    <button
      type="button"
      @click="arrayField.append({ email: '' })"
    >
      Add contact
    </button>
  </ArrayField>
</template>
```

</code-collapse>

<caution>

Key the loop with `item.id`, never with the index. After an insertion or reorder, the same item has a different index, and an index key makes Vue reuse the wrong DOM and component state.

</caution>

## What each part shows

- `arrayField.errors` holds issues at the array's own path, such as the minimum count. `<FieldError :errors="arrayField" />` displays the first.
- `item.field('email')` exposes the issues at that item's `email` path. Paths passed to `item.field()` are relative to the item and typed from the item's shape.
- For an array of primitives, pass the item itself to `Field`: `<Field v-slot="{ field }" :field="item">`.

## Mutate through the array field

Use these methods for every structural change. They keep item identity, touched state, and errors aligned with the values.

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Effect
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        append(value)
      </code>
    </td>
    
    <td>
      Add an item at the end.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prepend(value)
      </code>
    </td>
    
    <td>
      Add an item at the start.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        insert(index, value)
      </code>
    </td>
    
    <td>
      Insert at an index. Later items shift. The index is clamped to <code>
        0..length
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        remove(index)
      </code>
    </td>
    
    <td>
      Remove the item and its state. Later items shift down.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        move(from, to)
      </code>
    </td>
    
    <td>
      Move an item to another index.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        swap(indexA, indexB)
      </code>
    </td>
    
    <td>
      Exchange two items.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        update(index, value)
      </code>
    </td>
    
    <td>
      Replace an item in place. It keeps its identity and touched state, and its old errors are dropped.
    </td>
  </tr>
</tbody>
</table>

Details:

- Values passed to `append`, `prepend`, `insert`, and `update` are **deep-cloned**, so two items never share an object.
- An out-of-range index for `remove`, `move`, `swap`, or `update` is ignored.
- If the array does not exist yet, the first insertion creates it.
- Each mutation counts as a **change** event on the array field. By default this re-validates the array's own path, so a "minimum items" error appears or clears immediately. It does not validate the items' fields.

<caution>

Do not change the array's structure with `form.values.contacts.push()`, `splice()`, `sort()`, or by replacing the array. Direct changes bypass the methods that keep item identity and error paths aligned. Item ids are reconciled by length only, so errors and touched state can end up on the wrong items. Writing to a single item's field through its `model` is fine.

</caution>

## Identity, index, and path

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Stable across moves?
    </th>
    
    <th>
      Use it for
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        item.id
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      The <code>
        v-for
      </code>
      
       key.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        item.index
      </code>
    </td>
    
    <td>
      No, follows position
    </td>
    
    <td>
      Passing to <code>
        remove
      </code>
      
      , <code>
        move
      </code>
      
      , and <code>
        swap
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        item.path
      </code>
    </td>
    
    <td>
      No, follows position
    </td>
    
    <td>
      Input ids and labels, such as <code>
        contacts.2.email
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

Fields created from an item, such as `item.field('email')`, follow the item when it moves.

## Reorder with buttons

```vue
<template>
  <div
    v-for="item in arrayField.items"
    :key="item.id"
  >
    <!-- fields -->
    <button
      type="button"
      :disabled="item.index === 0"
      @click="arrayField.move(item.index, item.index - 1)"
    >
      Up
    </button>

    <button
      type="button"
      :disabled="item.index === arrayField.items.length - 1"
      @click="arrayField.move(item.index, item.index + 1)"
    >
      Down
    </button>
  </div>
</template>
```

## Nested arrays

Each item can create nested fields and nested arrays. Paths are relative to the item and follow it as it moves.

<code-collapse>

```vue
<script lang="ts" setup>
import { ArrayField, Field, FieldError, useForm } from 'notform'
import { z } from 'zod'

const membersSchema = z.array(z.object({
  email: z.email('Enter a valid email address.')
}))
  .min(1, 'Add at least one member.')

const itemSchema = z.object({
  members: membersSchema,
  name: z.string().min(1, 'Name the group.'),
})

const schema = z.object({
  groups: z.array(itemSchema).min(1),
})

const form = useForm({
  initialValues: {
    groups: [{ members: [{ email: '' }], name: '' },],
  },
  schema,
})
</script>

<template>
  <ArrayField
    v-slot="{ arrayField: groups }"
    :array-field="form.arrayField('groups')"
  >
    <fieldset
      v-for="group in groups.items"
      :key="group.id"
    >
      <Field
        v-slot="{ field }"
        :field="group.field('name')"
      >
        <input
          v-bind="field.events"
          :id="field.path"
          v-model="field.model"
          aria-label="Group name"
          :name="field.path"
        >

        <FieldError :errors="field" />
      </Field>

      <ArrayField
        v-slot="{ arrayField: members }"
        :array-field="group.arrayField('members')"
      >
        <div
          v-for="member in members.items"
          :key="member.id"
        >
          <Field
            v-slot="{ field }"
            :field="member.field('email')"
          >
            <input
              v-bind="field.events"
              :id="field.path"
              v-model="field.model"
              type="email"
              :name="field.path"
            >

            <FieldError :errors="field" />
          </Field>

          <button
            type="button"
            @click="members.remove(member.index)"
          >
            Remove member
          </button>
        </div>

        <FieldError :errors="members" />

        <button
          type="button"
          @click="members.append({ email: '' })"
        >
          Add member
        </button>
      </ArrayField>

      <button
        type="button"
        @click="groups.remove(group.index)"
      >
        Remove group
      </button>
    </fieldset>

    <button
      type="button"
      @click="groups.append({ name: '', members: [{ email: '' }] })"
    >
      Add group
    </button>
  </ArrayField>
</template>
```

</code-collapse>

When an inner array is removed along with its group, its fields are disposed. A stale reference to a removed item is inert: mutations do nothing and its `items` are empty.

## Errors follow items

When items are inserted, removed, moved, or swapped, existing errors are re-pointed to the item's new index. Removing an item drops its errors. `update` drops the replaced item's old errors. The schema's own array-level rules, such as `.min(1)`, stay on the array path.

## Reset

`form.reset()` restores the baseline array and gives every item a **fresh id**. The keyed list re-renders, so item components are rebuilt. This is expected: reset begins a new editing state from the baseline.

## Next steps

- [ArrayField](https://notformdocs.vercel.app/docs/components/array-field) is the component contract.
- [Validation](https://notformdocs.vercel.app/docs/guides/validation) covers configuring an array field's events.

---

- **Page:** useForm
- **Source:** https://notformdocs.vercel.app/docs/composables/use-form
- **Description:** Create a typed reactive form from a Standard Schema-compatible object schema. Full configuration and instance reference.

`useForm` creates the form instance that owns values, errors, field instances, and submit state. Call it in a Vue setup context (`<script setup>` or `setup()`), so its timers and watchers are cleaned up when the component unmounts.

```ts
import { useForm } from 'notform'
import { z } from 'zod'

const form = useForm({
  initialValues: { displayName: '', email: '' },
  onSubmit(data) {
    console.log(data)
  },
  schema: z.object({
    displayName: z.string().min(1),
    email: z.email(),
  }),
})
```

In Nuxt, `useForm` is auto-imported. See the [Nuxt module guide](https://notformdocs.vercel.app/docs/getting-started/nuxt-module).

## Configuration

<field-group>
<field name="schema" type="MaybeRefOrGetter<TSchema>" :required="true">

A Standard Schema-compatible **object** schema. May be a value, a ref, or a getter. It is read each time validation runs.

</field>

<field name="initialValues" type="DeepPartial<SchemaInput<TSchema>>">

Starting values and the baseline for `isDirty` and `reset()`. May be partial, but provide a value for every bound field.

</field>

<field name="initialErrors" type="ValidationIssue[]">

Issues shown before the first validation. An issue without a `path` is form-level.

</field>

<field name="onSubmit" type="(data: SchemaOutput<TSchema>) => void | Promise<void>">

Called after the whole form validates. The argument is the parsed schema **output**.

</field>
</field-group>

## Returned instance

The returned object is reactive. Read members directly, for example `form.isDirty`.

### State

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        values
      </code>
    </td>
    
    <td>
      <code>
        SchemaInput<TSchema>
      </code>
    </td>
    
    <td>
      Live input values. Editable directly, through <code>
        setValue
      </code>
      
      , or through field models.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        errors
      </code>
    </td>
    
    <td>
      <code>
        ValidationIssue[]
      </code>
    </td>
    
    <td>
      Current issues. Empty when nothing is wrong.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isDirty
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Values differ from the baseline.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isTouched
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      A field blurred or a submit was attempted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isSubmitted
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      At least one submit was attempted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isSubmitting
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Validation or <code>
        onSubmit
      </code>
      
       is running.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isValidating
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      A validation is running.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isValid
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      The error list is empty. Does not validate.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        submitCount
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      Submit attempts since the last reset.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        resetCount
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      Number of resets.
    </td>
  </tr>
</tbody>
</table>

### Fields

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        field(path, config?)
      </code>
    </td>
    
    <td>
      Get or create the cached field for a typed input path.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arrayField(path, config?)
      </code>
    </td>
    
    <td>
      Get or create the cached array field for a typed array path.
    </td>
  </tr>
</tbody>
</table>

The first call for a path creates the field and reads `config`. Later calls return the same instance and ignore any config. See [Validation](https://notformdocs.vercel.app/docs/guides/validation#configure-a-field).

### Actions

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        submit(event?)
      </code>
    </td>
    
    <td>
      Validate the form and call <code>
        onSubmit
      </code>
      
       if it passes. Prevents the event's default action. Ignored while a submit is running. Rejects if <code>
        onSubmit
      </code>
      
       throws.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validate()
      </code>
    </td>
    
    <td>
      Validate the whole form without calling <code>
        onSubmit
      </code>
      
      . Replaces all errors. Resolves with <code>
        { value }
      </code>
      
       or <code>
        { issues }
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reset(values?, errors?)
      </code>
    </td>
    
    <td>
      Restore the baseline, or replace it when arguments are given. Clears touched and submit state.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setError(issue)
      </code>
    </td>
    
    <td>
      With a <code>
        path
      </code>
      
      , replaces errors at that path. Without, appends a form-level error.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setValue(path, value)
      </code>
    </td>
    
    <td>
      Write a typed input value. Does not validate.
    </td>
  </tr>
</tbody>
</table>

## Typed paths and values

Paths use dot notation and are checked against the schema **input**. `form.field('address.city')` targets a nested value, and `form.arrayField('contacts')` targets an array. Values in `form.values` use the input type, and `onSubmit` receives the output type. See [Schema input and output](https://notformdocs.vercel.app/docs/guides/schema-input-output) and [TypeScript](https://notformdocs.vercel.app/docs/guides/typescript).

## Notes

- Call `useForm` once per form. Each call creates an independent form.
- Outside a Vue setup context, cleanup on unmount does not run.
- Changing a reactive `schema` discards in-flight validations but does not re-validate.
- The returned type is `UseFormInstance<TSchema>`, the public contract documented here.

## Related

- [Core concepts](https://notformdocs.vercel.app/docs/getting-started/core-concepts)
- [Form state](https://notformdocs.vercel.app/docs/guides/form-state)
- [Submission and reset](https://notformdocs.vercel.app/docs/guides/submission-and-reset)

---

- **Page:** Types
- **Source:** https://notformdocs.vercel.app/docs/reference/types
- **Description:** Every public type exported by notform, with its shape and where it is used.

All types are exported from `notform` and are available through TypeScript in both Vue and Nuxt projects. In Nuxt, add `notform` as a direct dependency to import them. See [Nuxt module](https://notformdocs.vercel.app/docs/getting-started/nuxt-module#import-types).

## Schema types

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        FormSchema
      </code>
    </td>
    
    <td>
      A Standard Schema whose input and output are both objects. The constraint <code>
        useForm
      </code>
      
       places on <code>
        schema
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SchemaInput<TSchema>
      </code>
    </td>
    
    <td>
      The data the schema accepts: the shape of <code>
        form.values
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SchemaOutput<TSchema>
      </code>
    </td>
    
    <td>
      The data the schema produces: the shape <code>
        onSubmit
      </code>
      
       receives.
    </td>
  </tr>
</tbody>
</table>

## Form types

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        FormConfig<TSchema>
      </code>
    </td>
    
    <td>
      The options object accepted by <code>
        useForm
      </code>
      
      : <code>
        schema
      </code>
      
      , <code>
        initialValues
      </code>
      
      , <code>
        initialErrors
      </code>
      
      , <code>
        onSubmit
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        UseFormInstance<TSchema>
      </code>
    </td>
    
    <td>
      The public form instance returned by <code>
        useForm
      </code>
      
      . Use this to type props and variables that hold a form.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FormInstance<TSchema>
      </code>
    </td>
    
    <td>
      The wider form type, including members that are not part of the public contract. Prefer <code>
        UseFormInstance
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FormProps<TSchema>
      </code>
      
      / <code>
        FormSlots
      </code>
    </td>
    
    <td>
      Props and slots of <code>
        Form
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## Field types

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        FieldConfig
      </code>
    </td>
    
    <td>
      Per-field behavior, passed to <code>
        form.field()
      </code>
      
       and <code>
        form.arrayField()
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FieldEvents
      </code>
    </td>
    
    <td>
      The handlers in <code>
        field.events
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FieldValidationEvent
      </code>
    </td>
    
    <td>
      <code>
        'blur' | 'change' | 'input'
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FieldInstance<TValue>
      </code>
    </td>
    
    <td>
      A field bound to one value.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FieldProps<TValue>
      </code>
      
       / <code>
        FieldSlots<TValue>
      </code>
    </td>
    
    <td>
      Props and slots of <code>
        Field
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FieldErrorProps
      </code>
      
       / <code>
        FieldErrorSlots
      </code>
    </td>
    
    <td>
      Props and slots of <code>
        FieldError
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## Array field types

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ArrayFieldInstance<TItem>
      </code>
    </td>
    
    <td>
      A <code>
        FieldInstance<TItem[]>
      </code>
      
       plus <code>
        items
      </code>
      
      , <code>
        append
      </code>
      
      , <code>
        prepend
      </code>
      
      , <code>
        insert
      </code>
      
      , <code>
        remove
      </code>
      
      , <code>
        move
      </code>
      
      , <code>
        swap
      </code>
      
      , <code>
        update
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ArrayItemInstance<TItem>
      </code>
    </td>
    
    <td>
      One item. A <code>
        FieldInstance<TItem>
      </code>
      
       plus <code>
        index
      </code>
      
      , <code>
        field(path, config?)
      </code>
      
      , and <code>
        arrayField(path, config?)
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ArrayFieldProps<TItem>
      </code>
      
       / <code>
        ArrayFieldSlots<TItem>
      </code>
    </td>
    
    <td>
      Props and slots of <code>
        ArrayField
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ArrayItem<TArray>
      </code>
    </td>
    
    <td>
      The item type of an array type.
    </td>
  </tr>
</tbody>
</table>

## Path types

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        InputPath<TSchema>
      </code>
    </td>
    
    <td>
      Every valid dot-notation path into the input.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        InputArrayPath<TSchema>
      </code>
    </td>
    
    <td>
      Input paths that point at an array.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        InputPathValue<TSchema, TPath>
      </code>
    </td>
    
    <td>
      The input type at a path.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OutputPath<TSchema>
      </code>
    </td>
    
    <td>
      Every valid path into the output.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OutputPathValue<TSchema, TPath>
      </code>
    </td>
    
    <td>
      The output type at a path.
    </td>
  </tr>
</tbody>
</table>

Path types recurse to a depth of 10.

## Validation types

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ValidationIssue
      </code>
    </td>
    
    <td>
      A Standard Schema issue: <code>
        { message: string, path?: ReadonlyArray<PropertyKey | { key: PropertyKey }> }
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ValidationResult<TValue>
      </code>
    </td>
    
    <td>
      <code>
        { value: TValue }
      </code>
      
       on success, <code>
        { issues }
      </code>
      
       on failure. Returned by <code>
        form.validate()
      </code>
      
       and <code>
        field.validate()
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

---

- **Page:** Troubleshooting
- **Source:** https://notformdocs.vercel.app/docs/reference/troubleshooting
- **Description:** Fix the most common NotForm problems; errors that do not show or clear, ignored config, submit that does nothing, array glitches, and Nuxt auto-import issues.

Find the symptom, read the cause, apply the fix.

## Validation and errors

### No error appears while I type

**Cause.** By design. `input` events do not validate until the field already has an error. A field validates when the user leaves it or commits a value.

**Fix.** To validate while typing, set `validateOn: { input: true }` on the field. See [Validation](https://notformdocs.vercel.app/docs/guides/validation#presets).

### An error does not clear after I fix the value

**Cause.** The field is in `validationMode: 'lazy'` and the event that would clear it is not enabled, or the error is not at this field's exact path.

**Fix.** Use the default `eager` mode, or enable the event. Confirm the issue's `path` matches the field: a field shows only issues at its exact path.

### Required fields say "expected string, received undefined"

**Cause.** The field has no entry in `initialValues`, so the schema receives `undefined` and reports its generic type message instead of your custom one.

**Fix.** Provide `''`, `false`, `[]`, or another starting value for every bound field. See [Binding inputs](https://notformdocs.vercel.app/docs/guides/binding-inputs#always-give-initial-values).

### A cross-field error never shows

**Cause.** The issue has no `path`, or the path names a different field. The error is then form-level, or shown by another field.

**Fix.** Report the issue on the field that should display it. See [Cross-field validation](https://notformdocs.vercel.app/docs/recipes/cross-field-validation).

### A form-level error is not displayed anywhere

**Cause.** `FieldError :errors="field"` shows only issues at that field's own path. Issues without a path, or on a parent path, are in `form.errors`.

**Fix.** Render them from `form.errors`. See [Errors](https://notformdocs.vercel.app/docs/guides/errors#show-form-level-errors).

### A server error disappears when I tab away

**Cause.** Validating a field replaces the errors at its path. If the schema finds no problem there, the server error is dropped.

**Fix.** This is intended behavior. See [Server errors](https://notformdocs.vercel.app/docs/recipes/server-errors#how-long-server-errors-last) if you need an error that outlives edits.

### `isValid` is `true` on a form that is clearly invalid

**Cause.** `isValid` means "the error list is empty". Nothing has validated yet.

**Fix.** Call `await form.validate()` or submit. See [Form state](https://notformdocs.vercel.app/docs/guides/form-state#isvalid-describes-errors-not-values).

## Submission

### Submitting does nothing

**Cause.** Validation failed, and the failing field has no visible error. Typical reasons: the field is on another step or is hidden, the issue is form-level, or a required key was never given a value.

**Fix.** Inspect `form.errors`:

```vue
<template>
  <pre>{{ form.errors }}</pre>
</template>
```

### The second click on submit is ignored

**Cause.** A submit is already running. Extra submits are ignored until it finishes.

**Fix.** Disable the button with `form.isSubmitting`.

### My `onSubmit` data does not match `form.values`

**Cause.** `onSubmit` receives the schema **output**, and `form.values` holds the **input**. Transforms, defaults, and coercions make them differ.

**Fix.** See [Schema input and output](https://notformdocs.vercel.app/docs/guides/schema-input-output).

### An error in `onSubmit` shows nothing in the UI

**Cause.** Errors thrown by `onSubmit` are not turned into form errors. They go to Vue's error handler.

**Fix.** Catch expected failures and call `form.setError`. See [Submission and reset](https://notformdocs.vercel.app/docs/guides/submission-and-reset#errors-thrown-in-onsubmit).

### The Reset button does not clear the inputs

**Cause.** Reset restores the **baseline**, not blank values. Or the button is outside `Form`, so no handler is attached.

**Fix.** Keep `type="reset"` inside `<Form>`, or call `form.reset()`. To clear a form that holds loaded data, call `form.reset(blankValues)` with explicit blank values, such as `{ name: '', email: '' }`, which also makes them the new baseline.

## Fields

### My field config is ignored

**Cause.** Fields are cached by path and the config is read on the first call. A call without config, such as one in the template, may have created the field first.

**Fix.** Create each configured field once, in `<script setup>`, and reuse that instance. See [Validation](https://notformdocs.vercel.app/docs/guides/validation#configure-a-field).

### A Vue error says `field` is a required prop or `path` is unknown

**Cause.** You are using v3 syntax, such as `<Field path="email">`, with v4.

**Fix.** Pass an instance: `<Field :field="form.field('email')">`. See the [v3 migration guide](https://notformdocs.vercel.app/docs/migrations/notform-v3).

### Typing a number gives me a string

**Cause.** Native inputs produce strings. `v-model.number` converts, but an empty input produces `''`.

**Fix.** Use `v-model.number` with a number schema, or keep strings in the form and convert in the schema. See [Binding inputs](https://notformdocs.vercel.app/docs/guides/binding-inputs#number).

### `field.id` breaks my HTML `id`

**Cause.** `field.id` is a `symbol` for Vue keys, not a string.

**Fix.** Use `field.path` for HTML ids and labels.

### I get a TypeScript error on `form.field('...')`

**Cause.** The path is not in the schema's **input** shape. Check spelling, nesting, and whether the key is optional or renamed by a transform.

**Fix.** See [TypeScript](https://notformdocs.vercel.app/docs/guides/typescript). The error is NotForm telling you the path does not exist.

## Array fields

### Items lose focus or show the wrong state after reordering

**Cause.** The list is keyed by `index`.

**Fix.** Key by `item.id`. See [Array fields](https://notformdocs.vercel.app/docs/guides/array-fields).

### Errors or touched state land on the wrong item

**Cause.** The array was changed with `push`, `splice`, or `sort` on `form.values` instead of the array methods.

**Fix.** Use `append`, `insert`, `remove`, `move`, `swap`, and `update`.

### Removing the last item leaves an error

**Cause.** The array's schema rule, such as `.min(1)`, reports an issue on the array's own path.

**Fix.** That is intended. Show it with `<FieldError :errors="arrayField" />`.

## Nuxt

### Components or `useForm` are not found

**Cause.** The module is not registered, or the dev server was not restarted, or another component or composable has the same name.

**Fix.** Check `modules: ['@notform/nuxt']`, restart, and add an alias if there is a conflict. See [Nuxt module](https://notformdocs.vercel.app/docs/getting-started/nuxt-module#avoid-name-conflicts).

### I cannot import types from `notform`

**Cause.** Strict package managers do not expose a module's own dependencies.

**Fix.** Add `notform` as a direct dependency.

## Performance

### Validation feels slow, or my API is called too often

**Cause.** Each field validation runs the whole schema, including any async rules.

**Fix.** Add a `debounce` to the field that owns the slow rule, and cache lookups. See [Async validation](https://notformdocs.vercel.app/docs/recipes/async-validation).

## Still stuck?

Open an issue on the [NotForm repository](https://github.com/favorodera/notform/issues). Include your schema, the form setup, and the behavior you see.

---

- **Page:** FAQ
- **Source:** https://notformdocs.vercel.app/docs/reference/faq
- **Description:** Short answers to common questions about NotForm's scope, validators, SSR, multiple forms, and styling.

## Does NotForm include UI components?

No. NotForm is headless. It renders a native `<form>` and passes state to your own markup or your component library. See [Integrations](https://notformdocs.vercel.app/docs/integrations/custom-components).

## Which validators work?

Any library that implements [Standard Schema](https://standardschema.dev) and produces an **object** schema. Zod, Valibot, and ArkType are common choices. NotForm has no validation rules of its own.

## Do I need a schema?

Yes. `schema` is required. It is how NotForm types your values and how validation runs.

## Can I use more than one form on a page?

Yes. Each `useForm` call creates an independent form with its own values, errors, and state.

## Does it work with SSR and Nuxt?

Yes. NotForm creates its state during setup without needing browser APIs. Use [`@notform/nuxt`](https://notformdocs.vercel.app/docs/getting-started/nuxt-module) for auto-imports.

## Which Vue version is required?

Vue 3.5 or later.

## Can the schema change at runtime?

Yes. Pass a ref or a getter as `schema`. See [Validation](https://notformdocs.vercel.app/docs/guides/validation#reactive-schemas).

## Why is the form value a string when my schema outputs a number?

`form.values` holds the schema **input**, which is what the control edits. Your submit handler receives the **output**. See [Schema input and output](https://notformdocs.vercel.app/docs/guides/schema-input-output).

## How do I validate on every keystroke?

Set `validateOn: { input: true }` on the field. See [Validation](https://notformdocs.vercel.app/docs/guides/validation#presets).

## How do I validate only on submit?

Disable blur and change validation and use lazy mode. See the "Validate on submit only" preset in [Validation](https://notformdocs.vercel.app/docs/guides/validation#presets).

## How do I show errors returned by my API?

Call `form.setError({ message, path })`. See [Server errors](https://notformdocs.vercel.app/docs/recipes/server-errors).

## How do I load saved data into a form?

Pass it as `initialValues`, or call `form.reset(values)` when it arrives. See [Editing existing data](https://notformdocs.vercel.app/docs/recipes/editing-existing-data).

## How do I pass a form to a child component?

Type the prop as `UseFormInstance<typeof schema>`. See [TypeScript](https://notformdocs.vercel.app/docs/guides/typescript#pass-a-form-to-a-child-component).

## Can I use it with my component library?

Yes. Map the control's value to `field.model` and its events to `field.events`. See [Custom components](https://notformdocs.vercel.app/docs/integrations/custom-components), [Nuxt UI](https://notformdocs.vercel.app/docs/integrations/nuxt-ui) and [ShadcnVue](https://notformdocs.vercel.app/docs/integrations/shadcn-vue).

## Can I use NotForm with an AI coding assistant?

Yes. See [Working with AI](https://notformdocs.vercel.app/docs/ai/working-with-ai).

---

- **Page:** Server errors
- **Source:** https://notformdocs.vercel.app/docs/recipes/server-errors
- **Description:** Submit to an API and show field-level and form-level errors that the server returns.

Client-side validation cannot know everything. A server may reject an email that is already registered, or fail for reasons unrelated to any field. This recipe turns those responses into errors your form displays.

## The flow

1. Submit. The schema validates first, so `onSubmit` only runs with valid data.
2. Send the data. Inspect the response.
3. For field problems, call `form.setError({ message, path })`.
4. For everything else, call `form.setError({ message })`, which has no `path` and is a form-level error.

## Example

<code-collapse>

```vue
<script setup lang="ts">
import { Field, FieldError, Form, useForm } from 'notform'
import { computed } from 'vue'
import { z } from 'zod'

const form = useForm({
  initialValues: { email: '', username: '' },
  async onSubmit(data) {
    try {
      const response = await fetch('/api/register', {
        body: JSON.stringify(data),
        headers: { 'content-type': 'application/json' },
        method: 'POST',
      })

      if (response.status === 422) {
        // { errors: { email: 'Already in use.', username: '...' } }
        const body = await response.json() as { errors: Record<string, string> }

        for (const [name, message] of Object.entries(body.errors)) {
          form.setError({ message, path: [name] })
        }

        return
      }

      if (!response.ok) {
        form.setError({ message: 'Something went wrong. Please try again.' })
        return
      }

      form.reset()
    } catch {
      form.setError({ message: 'We could not reach the server. Check your connection.' })
    }
  },
  schema: z.object({
    email: z.email('Enter a valid email address.'),
    username: z.string().min(3, 'Use at least 3 characters.'),
  }),
})

const formErrors = computed(() => {
  return form.errors.filter((issue) => {
    return !issue.path?.length
  })
})
</script>

<template>
  <Form
    :form="form"
    novalidate
  >
    <FieldError
      :errors="formErrors"
      as="p"
      role="alert"
    />

    <Field
      v-slot="{ field }"
      :field="form.field('username')"
    >
      <label :for="field.path">Username</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
      >

      <FieldError :errors="field" />
    </Field>

    <Field
      v-slot="{ field }"
      :field="form.field('email')"
    >
      <label :for="field.path">Email</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        type="email"
      >

      <FieldError :errors="field" />
    </Field>

    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      Create account
    </button>
  </Form>
</template>
```

</code-collapse>

## How long server errors last

<table>
<thead>
  <tr>
    <th>
      Error
    </th>
    
    <th>
      Cleared when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      A field error from <code>
        setError({ path })
      </code>
    </td>
    
    <td>
      That field validates again and the schema reports no issue there, for example on blur or when the user edits it. Also on <code>
        reset()
      </code>
      
      , and on the next submit.
    </td>
  </tr>
  
  <tr>
    <td>
      A form-level error from <code>
        setError({ message })
      </code>
    </td>
    
    <td>
      The next submit, a <code>
        form.validate()
      </code>
      
      , or <code>
        reset()
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

Editing a field with a server error therefore removes the error as soon as the schema passes, which is usually right: the server's complaint was about the old value.

To keep a server error visible while the user edits, store it yourself and display it next to `FieldError`.

## Nested and array paths

A path is an array of segments. Use indices for array items.

```ts
form.setError({ message: 'Email already invited.', path: ['contacts', 1, 'email'] })
form.setError({ message: 'Invalid city.', path: ['address', 'city'] })
```

If the server returns dot paths, split them: `path: key.split('.')`. Numeric strings such as `'1'` match array indices.

## Notes

- `setError` with a path **replaces** errors at that path. Without a path it **appends**, so avoid calling it repeatedly for the same message.
- Errors thrown (not returned) from `onSubmit` are not caught by NotForm. Wrap risky calls in `try/catch`, as above. See [Submission and reset](https://notformdocs.vercel.app/docs/guides/submission-and-reset#errors-thrown-in-onsubmit).
- `isSubmitting` stays `true` until `onSubmit` settles, so the button stays disabled during the request.

---

- **Page:** Cross-field validation
- **Source:** https://notformdocs.vercel.app/docs/recipes/cross-field-validation
- **Description:** Validate one field against another, such as confirm password or date ranges, and keep the dependent field's error up to date.

Some rules involve more than one field: a confirmation must match, an end date must follow a start date. NotForm validates with your schema, so you write the rule in the schema and tell it which field should display the error.

## Put the rule on the schema, and set the path

An issue is shown by the field whose path matches the issue's `path`. Report the issue on the field you want to display it.

```ts
import { z } from 'zod'

const schema = z.object({
  confirmPassword: z.string().min(1, 'Confirm your password.'),
  password: z.string().min(8, 'Use at least 8 characters.'),
}).refine((values) => {
  return values.password === values.confirmPassword
}, {
  message: 'Passwords do not match.',
  path: ['confirmPassword'],
})
```

Without `path`, the issue is form-level and no field displays it.

<note>

Some validators skip object-level rules while a field in the object is invalid, so the mismatch error may only appear after the individual fields pass. Check your validator's documentation if the cross-field message does not show when you expect it.

</note>

## Keep the dependent field up to date

Fields validate on their own events. If the user fixes `password` after `confirmPassword` showed an error, `confirmPassword` does not know to re-validate. Watch the source field and re-validate the dependent one.

<code-collapse>

```vue
<script setup lang="ts">
import { watch } from 'vue'

const password = form.field('password')
const confirmPassword = form.field('confirmPassword')

watch(
  () => {
    return password.model
  },
  () => {
  // only after the user has interacted with the confirm field
    if (confirmPassword.isTouched) {
      void confirmPassword.validate()
    }
  }
)
</script>

<template>
  <Form
    :form="form"
    novalidate
  >
    <Field
      v-slot="{ field }"
      :field="password"
    >
      <label :for="field.path">Password</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        type="password"
      >

      <FieldError :errors="field" />
    </Field>

    <Field
      v-slot="{ field }"
      :field="confirmPassword"
    >
      <label :for="field.path">Confirm password</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        type="password"
      >

      <FieldError :errors="field" />
    </Field>
  </Form>
</template>
```

</code-collapse>

Passing the pre-created field instances to `Field` is fine. `Field` accepts any field instance.

## Date ranges

The same pattern applies to any dependent pair.

```ts
const schema = z.object({
  endDate: z.string().min(1, 'Choose an end date.'),
  startDate: z.string().min(1, 'Choose a start date.'),
}).refine((values) => {
  return values.endDate >= values.startDate
}, {
  message: 'End date must be on or after the start date.',
  path: ['endDate'],
})
```

ISO date strings (`2026-11-02`) compare correctly as text. Watch `startDate` and re-validate `endDate`, exactly as above.

## Show a rule for the whole form

For a rule that is not about one field, omit `path` and show it as a form-level error. See [Errors](https://notformdocs.vercel.app/docs/guides/errors#show-form-level-errors).

---

- **Page:** Async validation
- **Source:** https://notformdocs.vercel.app/docs/recipes/async-validation
- **Description:** Check values against a server, such as username availability, with debounce, caching, and loading state.

Validators that support asynchronous rules work with NotForm, because validation is already asynchronous. The thing to design around is cost: **every field validation runs the entire schema**, so an async rule runs whenever any field validates.

## Example: username availability

<code-collapse>

```vue
<script setup lang="ts">
import { Field, FieldError, Form, useForm } from 'notform'
import { z } from 'zod'

// cache the promise per value so unchanged values never hit the network twice
const usernameLookups = new Map<string, Promise<boolean>>()

function isUsernameTaken(username: string): Promise<boolean> {
  let usernameLookup = usernameLookups.get(username)

  if (!usernameLookup) {
    try {
      const response = await fetch(`/api/usernames/${encodeURIComponent(username)}`)
      const responseToJson = await response.json() as { taken: boolean }

      usernameLookup = responseToJson.taken
    } catch {
      // Handle the error as needed
    }

    usernameLookups.set(username, usernameLookup)
  }

  return usernameLookup
}

const schema = z.object({
  email: z.email('Enter a valid email address.'),
  username: z.string()
    .min(3, 'Use at least 3 characters.')
    .refine(async (value) => {
      // skip the request when a cheaper rule already fails
      if (value.length < 3) {
        return true
      }

      const checkIfUsernameIsTaken = await isUsernameTaken(value)
      return !checkIfUsernameIsTaken
    }, 'That username is taken.'),
})

const form = useForm({
  initialValues: { email: '', username: '' },
  schema,
})

const username = form.field('username', {
  debounce: 400,
  validateOn: { input: true },
})
</script>

<template>
  <Form
    :form="form"
    novalidate
  >
    <Field
      v-slot="{ field }"
      :field="username"
    >
      <label :for="field.path">Username</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        autocomplete="username"
      >

      <span
        v-if="field.isValidating"
        role="status"
      >Checking...</span>

      <FieldError :errors="field" />
    </Field>

    <Field
      v-slot="{ field }"
      :field="form.field('email')"
    >
      <label :for="field.path">Email</label>

      <input
        :id="field.path"
        v-model="field.model"
        v-bind="field.events"
        type="email"
      >

      <FieldError :errors="field" />
    </Field>

    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      Create account
    </button>
  </Form>
</template>
```

</code-collapse>

## Why each piece is there

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      Reason
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        debounce: 400
      </code>
    </td>
    
    <td>
      Waits for a pause in typing instead of validating on every keystroke. Blur and submit are never delayed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validateOn: { input: true }
      </code>
    </td>
    
    <td>
      Validates while typing, not only on blur.
    </td>
  </tr>
  
  <tr>
    <td>
      The promise cache
    </td>
    
    <td>
      The email field's validation also runs the username rule. The cache makes that free for unchanged values.
    </td>
  </tr>
  
  <tr>
    <td>
      The early <code>
        return true
      </code>
    </td>
    
    <td>
      Avoids a request for values the cheaper <code>
        min(3)
      </code>
      
       rule already rejects. The <code>
        min
      </code>
      
       message is still reported by that rule.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        field.isValidating
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       while any validation that concerns this field runs. Use it for the spinner.
    </td>
  </tr>
</tbody>
</table>

## Stale results

If the user types again while a lookup is in flight, the old result is discarded and cannot overwrite newer errors. Any value change makes every in-flight validation stale, and the change's own event starts a fresh one. See [Validation](https://notformdocs.vercel.app/docs/guides/validation#stale-results).

## Submit still validates everything

Submitting re-runs the whole schema, including the async rule, so a username that became taken after the last check is still caught. If the cache could hold outdated answers, clear it before submit or key it by time.

## Cache invalidation

The simple `Map` above lives for the component's lifetime. If availability can change during a session, expire entries after a short time, or clear the cache in `onSubmit`'s failure path.

---

- **Page:** Custom components
- **Source:** https://notformdocs.vercel.app/docs/integrations/custom-components
- **Description:** Connect any Vue input component to a NotForm field by mapping its value and events, and build reusable field wrappers.

Any control can work with NotForm. You only need to answer two questions about it:

1. **How does it take and emit its value?** Usually `v-model`.
2. **Which of its events mean "typed", "committed", and "left"?** These map to `onInput`, `onChange`, and `onBlur`.

## Choose the binding

<table>
<thead>
  <tr>
    <th>
      The control...
    </th>
    
    <th>
      Bind it like this
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Forwards native <code>
        input
      </code>
      
      , <code>
        change
      </code>
      
      , and <code>
        blur
      </code>
      
       events
    </td>
    
    <td>
      <code>
        v-model="field.model" v-bind="field.events"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Emits only <code>
        update:modelValue
      </code>
      
       when a value is picked
    </td>
    
    <td>
      <code>
        v-model="field.model" @update:model-value="field.events.onChange"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Emits <code>
        update:modelValue
      </code>
      
       on every keystroke
    </td>
    
    <td>
      <code>
        v-model="field.model" @update:model-value="field.events.onInput"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Emits an event when focus leaves, such as <code>
        blur
      </code>
      
      , <code>
        focusout
      </code>
      
      , or <code>
        close
      </code>
    </td>
    
    <td>
      <code>
        @blur="field.events.onBlur"
      </code>
    </td>
  </tr>
</tbody>
</table>

Use the event names from the component's own documentation.

## Which handler means what

- **onInput**: the value changed while the user is still editing, such as typing. By default it only validates if the field already shows an error.
- **onChange**: the user committed a value, such as selecting an option. It validates by default.
- **onBlur**: focus left the control. It marks the field touched and validates by default.

Pick the handler that matches the interaction. You can change what each one triggers with [`validateOn` and `validationMode`](https://notformdocs.vercel.app/docs/guides/validation#configure-a-field).

<tip>

Keep `v-model` before the event binding. The value has to be written before `onChange` or `onInput` takes its snapshot for validation.

</tip>

## Controls that emit a value

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('country')"
  >
    <CountryPicker
      v-model="field.model"
      :invalid="!field.isValid"
      @update:model-value="field.events.onChange"
      @focusout="field.events.onBlur"
    />

    <FieldError :errors="field" />
  </Field>
</template>
```

## Controls that forward native events

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('displayName')"
  >
    <TextInput
      v-model="field.model"
      v-bind="field.events"
    />

    <FieldError :errors="field" />
  </Field>
</template>
```

`field.events` contains `onBlur`, `onChange`, and `onInput`. If the component does not forward those events, bind the callbacks explicitly, as above.

## Controls that do not use v-model

If a control exposes a value prop and a callback instead, write through `field.model` yourself:

```vue
<template>
  <RatingInput
    :value="field.model"
    @rate="(value) => {
      field.model = value
      field.events.onChange()
    }"
  />
</template>
```

Assign first, then call the event.

## A reusable field wrapper

Most apps wrap label, input, and error once. Accept a field instance as a prop.

```vue
<script setup lang="ts">
import { FieldError, type FieldInstance } from 'notform'

defineProps<{
  field: FieldInstance<string>
  label: string
  type?: string
}>()
</script>

<template>
  <div class="field">
    <label :for="field.path">{{ label }}</label>

    <input
      :id="field.path"
      v-model="field.model"
      v-bind="field.events"
      :type="type ?? 'text'"
      :aria-invalid="!field.isValid"
    >

    <FieldError
      :errors="field"
      class="field-error"
      role="alert"
    />
  </div>
</template>
```

```vue
<template>
  <AppTextField
    :field="form.field('email')"
    label="Email"
    type="email"
  />
</template>
```

The parent keeps the form instance and passes only the field. Array items are fields too, so `<AppTextField :field="item.field('email')" />` works inside `ArrayField`.

## Checklist for a new control

- [ ] Does `field.model` reflect the control's value type? Make sure the schema accepts that type (for example `boolean`, `string[]`, or a number).
- [ ] Does the control have an element that can take focus, so `onBlur` can fire?
- [ ] Does it have an accessible name? Use `field.path` for ids.
- [ ] Does it show `field.isValid` and the error message?

## Related

- [Binding inputs](https://notformdocs.vercel.app/docs/guides/binding-inputs)
- [Field](https://notformdocs.vercel.app/docs/components/field)

---

- **Page:** Editing existing data
- **Source:** https://notformdocs.vercel.app/docs/recipes/editing-existing-data
- **Description:** Load a saved record into a form, track unsaved changes, and make the saved result the new baseline.

An edit form starts from data that already exists. The key idea is the **baseline**: the values `isDirty` compares against and `reset()` returns to. Loaded data should become the baseline.

## When the data is ready before the form

If the record is available when the form is created, pass it as `initialValues`.

```ts
const { data: profile } = await useFetch('/api/profile') // Nuxt

const form = useForm({
  initialValues: profile.value ?? { bio: '', displayName: '' },
  async onSubmit(values) {
    const saved = await $fetch('/api/profile', { body: values, method: 'PUT' })
    form.reset(saved)
  },
  schema: profileSchema,
})
```

In plain Vue, wait to render the form until the data has loaded, then pass it down.

```vue
<template>
  <ProfileForm
    v-if="profile"
    :profile="profile"
  />
</template>
```

## When the data arrives after the form exists

Create the form with defaults and call `reset(values)` once the data arrives. This replaces the baseline, so `isDirty` is `false` right after loading.

```ts
const form = useForm({
  initialValues: { bio: '', displayName: '' },
  async onSubmit(data) {
    const saved = await api.updateProfile(data)
    form.reset(saved)
  },
  schema: profileSchema,
})

onMounted(async () => {
  form.reset(await api.getProfile())
})
```

`reset(values)` also restores errors to the baseline, clears touched state, bumps `resetCount`, and gives array items fresh ids.

## Make the saved data the new baseline

After a successful save, call `form.reset(saved)` with what the server stored. The form then reports `isDirty === false`, and a later plain `reset()` returns to the saved version, not the original.

If the server returns exactly what you sent, `form.reset(data)` inside `onSubmit` is enough. Remember that `data` is the schema **output**. If your schema transforms values, reset with an object in the **input** shape instead.

## Warn about unsaved changes

```vue
<script setup lang="ts">
import { onBeforeUnmount, onMounted } from 'vue'
import { onBeforeRouteLeave } from 'vue-router'

onBeforeRouteLeave(() => {
  if (form.isDirty && !confirm('Discard unsaved changes?')) {
    return false
  }
})

function warnBeforeClosing(event: BeforeUnloadEvent) {
  if (form.isDirty) {
    event.preventDefault()
  }
}

onMounted(async () => {
  window.addEventListener('beforeunload', warnBeforeClosing)
})
onBeforeUnmount(async () => {
  window.removeEventListener('beforeunload', warnBeforeClosing)
})
</script>
```

## Show save state

```vue
<template>
  <button
    type="submit"
    :disabled="!form.isDirty || form.isSubmitting"
  >
    {{ form.isSubmitting ? 'Saving...' : 'Save changes' }}
  </button>

  <button
    type="reset"
    :disabled="!form.isDirty"
  >
    Discard changes
  </button>
</template>
```

## Tips

- Keep every bound field present in the loaded object, using `''`, `false`, or `[]` where the server sends `null`. Missing keys reach the schema as `undefined`.
- Reload the baseline when the underlying record changes. For example,

```ts
watch(profile, (value) => {
  form.reset(value)
})
```

- Input and output shapes can differ. `reset` and `initialValues` always use the **input** shape.

---

- **Page:** Nuxt UI
- **Source:** https://notformdocs.vercel.app/docs/integrations/nuxt-ui
- **Description:** Use NotForm with Nuxt UI inputs and form fields, including text, textarea, select, checkbox, checkbox group, radio group, switch, and array fields.

Nuxt UI provides styled inputs and a `UFormField` wrapper for labels and error text. NotForm owns the form state and validation, and Nuxt UI renders the controls.

## Setup

Install both modules and register them.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/ui', '@notform/nuxt'],
})
```

## Use NotForm's form, not UForm

Wrap your controls in NotForm's `Form`, not Nuxt UI's `UForm`. `UForm` has its own validation and submit pipeline. Using both makes two systems compete over the same state.

`UFormField` is safe to use on its own. It lays out the label, description, and error text.

## Choose the right binding

Bind the model with `v-model:model-value`, then report changes and blur to NotForm yourself. Text inputs report with `onInput`, and the other controls report with `onChange`.

<table>
<thead>
  <tr>
    <th>
      Component
    </th>
    
    <th>
      Binding
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        UInput
      </code>
      
      , <code>
        UTextarea
      </code>
    </td>
    
    <td>
      <code>
        v-model="field.model"
      </code>
      
      , <code>
        @update:model-value="field.events.onInput"
      </code>
      
       and <code>
        @blur="field.events.onBlur"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        USelect
      </code>
      
      , <code>
        UCheckbox
      </code>
      
      , <code>
        UCheckboxGroup
      </code>
      
      , <code>
        URadioGroup
      </code>
      
      , <code>
        USwitch
      </code>
    </td>
    
    <td>
      <code>
        v-model="field.model"
      </code>
      
      , <code>
        @update:model-value="field.events.onChange"
      </code>
      
      and <code>
        @blur="field.events.onBlur"
      </code>
    </td>
  </tr>
</tbody>
</table>

## Show errors

`UFormField` renders error text from its `error` prop, so you do not need `FieldError` here. Pass it the first message of `field.errors` with a small helper:

```ts
import type { ValidationIssue } from 'notform'

function getFirstErrorMessage(errors?: ValidationIssue[]) {
  return errors?.[0]?.message
}
```

Each section below shows the schema and the template it binds to. The snippets assume the `form`, `getFirstErrorMessage` and the items from the [full example](#full-example).

## Text input

```ts
title: z.string().min(5, 'Bug title must be at least 5 characters.')
  .max(32)
```

<code-collapse>

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('title')"
  >
    <UFormField
      label="Bug Title"
      :error="getFirstErrorMessage(field.errors)"
    >
      <UInput
        v-model="field.model"
        placeholder="Login button not working on mobile"
        autocomplete="off"
        class="inline-full"
        @update:model-value="field.events.onInput"
        @blur="field.events.onBlur"
      />
    </UFormField>
  </Field>
</template>
```

</code-collapse>

## Textarea

`UTextarea` takes the same bindings as a text input. Because `field.model` is reactive, you can read it anywhere in the slot, which is how the character counter stays in sync.

```ts
description: z.string().min(20, 'Description must be at least 20 characters.')
  .max(100)
```

<code-collapse>

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('description')"
  >
    <UFormField
      label="Description"
      help="Include steps to reproduce, expected behavior, and what actually happened."
      :error="getFirstErrorMessage(field.errors)"
    >
      <UTextarea
        v-model="field.model"
        :rows="6"
        class="inline-full"
        placeholder="I'm having an issue with the login button on mobile."
        @update:model-value="field.events.onInput"
        @blur="field.events.onBlur"
      />

      <p class="mbs-1 text-xs text-muted tabular-nums">
        {{ field.model?.length || 0 }}/100 characters
      </p>
    </UFormField>
  </Field>
</template>
```

</code-collapse>

## Select

Pass the options through `items`.

```ts
language: z.string().min(1, 'Please select your spoken language.')
```

<code-collapse>

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('language')"
  >
    <UFormField
      label="Spoken Language"
      description="For best results, select the language you speak."
      :error="getFirstErrorMessage(field.errors)"
    >
      <USelect
        v-model="field.model"
        :items="spokenLanguages"
        placeholder="Select"
        class="inline-full"
        @update:model-value="field.events.onChange"
        @blur="field.events.onBlur"
      />
    </UFormField>
  </Field>
</template>
```

</code-collapse>

## Checkbox

```ts
responses: z.literal(true, 'Notifications are mandatory')
```

<code-collapse>

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('responses')"
  >
    <UFormField
      label="Responses"
      description="Get notified for requests that take time."
      :error="getFirstErrorMessage(field.errors)"
    >
      <UCheckbox
        v-model="field.model"
        label="Push notifications"
        @update:model-value="field.events.onChange"
        @blur="field.events.onBlur"
      />
    </UFormField>
  </Field>
</template>
```

</code-collapse>

## Checkbox group

`UCheckboxGroup` binds the array of selected values directly through `v-model:model-value`.

```ts
tasks: z.array(z.string()).min(1, 'Please select at least one notification type.')
```

<code-collapse>

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('tasks')"
  >
    <UFormField :error="getFirstErrorMessage(field.errors)">
      <UCheckboxGroup
        v-model="field.model"
        legend="Tasks"
        :items="tasks"
        @update:model-value="field.events.onChange"
        @blur="field.events.onBlur"
      />
    </UFormField>
  </Field>
</template>
```

</code-collapse>

## Radio group

```ts
plan: z.string().min(1, 'You must select a subscription plan to continue.')
```

<code-collapse>

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('plan')"
  >
    <UFormField
      description="You can upgrade or downgrade your plan at any time."
      :error="getFirstErrorMessage(field.errors)"
    >
      <URadioGroup
        v-model="field.model"
        legend="Plan"
        variant="card"
        indicator="end"
        :items="plans"
        @update:model-value="field.events.onChange"
        @blur="field.events.onBlur"
      />
    </UFormField>
  </Field>
</template>
```

</code-collapse>

## Switch

```ts
twoFactor: z.boolean().refine((value) => {
  return value === true
}, 'It is highly recommended to enable two-factor authentication.')
```

<code-collapse>

```vue
<template>
  <Field
    v-slot="{ field }"
    :field="form.field('twoFactor')"
  >
    <UFormField
      label="Multi-factor authentication"
      description="Enable multi-factor authentication to secure your account."
      :error="getFirstErrorMessage(field.errors)"
    >
      <USwitch
        v-model="field.model"
        @update:model-value="field.events.onChange"
        @blur="field.events.onBlur"
      />
    </UFormField>
  </Field>
</template>
```

</code-collapse>

## Array fields

Use `ArrayField` for lists the user can grow, shrink, and reorder. Each item exposes `item.field('key')`, so you can wrap any of the inputs above in a `Field`.

```ts
emails: z.array(z.object({ address: z.email('Enter a valid email address.') }))
  .min(2, 'Add at least two email addresses.')
  .max(5, 'You can add up to 5 email addresses.')
```

<code-collapse>

```vue
<template>
  <ArrayField
    v-slot="{ arrayField }"
    :array-field="form.arrayField('emails')"
  >
    <UFormField
      label="Email Addresses"
      description="Add up to 5 email addresses where we can contact you."
      :error="getFirstErrorMessage(arrayField.errors)"
    >
      <div class="space-y-3">
        <Field
          v-for="item in arrayField.items"
          :key="item.id"
          v-slot="{ field }"
          :field="item.field('address')"
        >
          <UFormField :error="getFirstErrorMessage(field.errors)">
            <UInput
              v-model="field.model"
              type="email"
              placeholder="name@example.com"
              class="inline-full"
              @update:model-value="field.events.onInput"
              @blur="field.events.onBlur"
            >
              <template
                v-if="arrayField.items.length > 1"
                #trailing
              >
                <UButton
                  icon="i-lucide-chevron-up"
                  color="neutral"
                  variant="ghost"
                  size="xs"
                  :disabled="item.index === 0"
                  @click="arrayField.move(item.index, item.index - 1)"
                />

                <UButton
                  icon="i-lucide-chevron-down"
                  color="neutral"
                  variant="ghost"
                  size="xs"
                  :disabled="item.index === arrayField.items.length - 1"
                  @click="arrayField.move(item.index, item.index + 1)"
                />

                <UButton
                  icon="i-lucide-x"
                  color="neutral"
                  variant="ghost"
                  size="xs"
                  @click="arrayField.remove(item.index)"
                />
              </template>
            </UInput>
          </UFormField>
        </Field>

        <UButton
          color="neutral"
          variant="outline"
          block
          size="sm"
          :disabled="arrayField.items.length >= 5"
          @click="arrayField.append({ address: '' })"
        >
          Add Email Address
        </UButton>
      </div>
    </UFormField>
  </ArrayField>
</template>
```

</code-collapse>

A few things to note:

- `arrayField.items` gives you each item's `id` and `index`. Use `item.id` as the `:key`, not the index, so inputs keep their state when you reorder or remove items.
- `arrayField.append`, `arrayField.remove` and `arrayField.move` change the list.
- Errors for a single item come from its `field`. Errors for the list as a whole, such as the `min` and `max` rules, come from `arrayField.errors`.
- Mirror the schema limits in the UI, as the **Add** button does with `arrayField.items.length >= 5`, so users can't reach an invalid state by clicking.

## Full example

This form combines every input above.

<code-collapse>

```vue
<script setup lang="ts">
import type { ValidationIssue } from 'notform'
import { z } from 'zod'

const spokenLanguages = [
  { label: 'Auto', value: 'auto' },
  { type: 'separator' as const },
  { label: 'English', value: 'en' },
  { label: 'Spanish', value: 'es' },
  { label: 'French', value: 'fr' },
]

const plans = [
  { description: 'For everyday use with basic features.', label: 'Starter (100K tokens/month)', value: 'starter' },
  { description: 'For advanced AI usage with more features.', label: 'Pro (1M tokens/month)', value: 'pro' },
  { description: 'For large teams and heavy usage.', label: 'Enterprise (Unlimited tokens)', value: 'enterprise' },
]

const tasks = [
  { label: 'Push notifications', value: 'push' },
  { label: 'Email notifications', value: 'email' },
]

const schema = z.object({
  description: z.string().min(20, 'Description must be at least 20 characters.')
    .max(100),
  emails: z.array(z.object({ address: z.email('Enter a valid email address.') }))
    .min(2, 'Add at least two email addresses.')
    .max(5, 'You can add up to 5 email addresses.'),
  language: z.string().min(1, 'Please select your spoken language.')
    .refine((value) => {
      return value !== 'auto'
    }, 'Auto-detection is not allowed.'),
  plan: z.string().min(1, 'You must select a subscription plan to continue.'),
  responses: z.literal(true, 'Notifications are mandatory'),
  tasks: z.array(z.string()).min(1, 'Please select at least one notification type.'),
  title: z.string().min(5, 'Bug title must be at least 5 characters.')
    .max(32),
  twoFactor: z.boolean().refine((value) => {
    return value === true
  }, 'It is highly recommended to enable two-factor authentication.'),
})

const form = useForm({
  initialValues: {
    description: '',
    emails: [{ address: '' }, { address: '' }],
    language: '',
    plan: '',
    responses: true,
    tasks: [],
    title: '',
    twoFactor: false,
  },
  onSubmit(data) {
    console.log(data)
  },
  schema,
})

function getFirstErrorMessage(errors?: ValidationIssue[]) {
  return errors?.[0]?.message
}
</script>

<template>
  <UApp>
    <Form
      :form
      class="mx-auto space-y-6 p-8 inline-full max-inline-xl"
    >
      <!-- Text input -->
      <Field
        v-slot="{ field }"
        :field="form.field('title')"
      >
        <UFormField
          label="Bug Title"
          :error="getFirstErrorMessage(field.errors)"
        >
          <UInput
            v-model="field.model"
            placeholder="Login button not working on mobile"
            autocomplete="off"
            class="inline-full"
            @update:model-value="field.events.onInput"
            @blur="field.events.onBlur"
          />
        </UFormField>
      </Field>

      <!-- Textarea -->
      <Field
        v-slot="{ field }"
        :field="form.field('description')"
      >
        <UFormField
          label="Description"
          help="Include steps to reproduce, expected behavior, and what actually happened."
          :error="getFirstErrorMessage(field.errors)"
        >
          <UTextarea
            v-model="field.model"
            :rows="6"
            class="inline-full"
            placeholder="I'm having an issue with the login button on mobile."
            @update:model-value="field.events.onInput"
            @blur="field.events.onBlur"
          />

          <p class="mbs-1 text-xs text-muted tabular-nums">
            {{ field.model?.length || 0 }}/100 characters
          </p>
        </UFormField>
      </Field>

      <!-- Select -->
      <Field
        v-slot="{ field }"
        :field="form.field('language')"
      >
        <UFormField
          label="Spoken Language"
          description="For best results, select the language you speak."
          :error="getFirstErrorMessage(field.errors)"
        >
          <USelect
            v-model="field.model"
            :items="spokenLanguages"
            placeholder="Select"
            class="inline-full"
            @update:model-value="field.events.onChange"
            @blur="field.events.onBlur"
          />
        </UFormField>
      </Field>

      <!-- Checkbox -->
      <Field
        v-slot="{ field }"
        :field="form.field('responses')"
      >
        <UFormField
          label="Responses"
          description="Get notified for requests that take time."
          :error="getFirstErrorMessage(field.errors)"
        >
          <UCheckbox
            v-model="field.model"
            label="Push notifications"
            @update:model-value="field.events.onChange"
            @blur="field.events.onBlur"
          />
        </UFormField>
      </Field>

      <!-- Checkbox group -->
      <Field
        v-slot="{ field }"
        :field="form.field('tasks')"
      >
        <UFormField :error="getFirstErrorMessage(field.errors)">
          <UCheckboxGroup
            v-model="field.model"
            legend="Tasks"
            :items="tasks"
            @update:model-value="field.events.onChange"
            @blur="field.events.onBlur"
          />
        </UFormField>
      </Field>

      <!-- Radio group -->
      <Field
        v-slot="{ field }"
        :field="form.field('plan')"
      >
        <UFormField
          description="You can upgrade or downgrade your plan at any time."
          :error="getFirstErrorMessage(field.errors)"
        >
          <URadioGroup
            v-model="field.model"
            legend="Plan"
            variant="card"
            indicator="end"
            :items="plans"
            @update:model-value="field.events.onChange"
            @blur="field.events.onBlur"
          />
        </UFormField>
      </Field>

      <!-- Switch -->
      <Field
        v-slot="{ field }"
        :field="form.field('twoFactor')"
      >
        <UFormField
          label="Multi-factor authentication"
          description="Enable multi-factor authentication to secure your account."
          :error="getFirstErrorMessage(field.errors)"
        >
          <USwitch
            v-model="field.model"
            @update:model-value="field.events.onChange"
            @blur="field.events.onBlur"
          />
        </UFormField>
      </Field>

      <!-- Array field -->
      <ArrayField
        v-slot="{ arrayField }"
        :array-field="form.arrayField('emails')"
      >
        <UFormField
          label="Email Addresses"
          description="Add up to 5 email addresses where we can contact you."
          :error="getFirstErrorMessage(arrayField.errors)"
        >
          <div class="space-y-3">
            <Field
              v-for="item in arrayField.items"
              :key="item.id"
              v-slot="{ field }"
              :field="item.field('address')"
            >
              <UFormField :error="getFirstErrorMessage(field.errors)">
                <UInput
                  v-model="field.model"
                  type="email"
                  placeholder="name@example.com"
                  class="inline-full"
                  @update:model-value="field.events.onInput"
                  @blur="field.events.onBlur"
                >
                  <template
                    v-if="arrayField.items.length > 1"
                    #trailing
                  >
                    <UButton
                      icon="i-lucide-chevron-up"
                      color="neutral"
                      variant="ghost"
                      size="xs"
                      :disabled="item.index === 0"
                      @click="arrayField.move(item.index, item.index - 1)"
                    />

                    <UButton
                      icon="i-lucide-chevron-down"
                      color="neutral"
                      variant="ghost"
                      size="xs"
                      :disabled="item.index === arrayField.items.length - 1"
                      @click="arrayField.move(item.index, item.index + 1)"
                    />

                    <UButton
                      icon="i-lucide-x"
                      color="neutral"
                      variant="ghost"
                      size="xs"
                      @click="arrayField.remove(item.index)"
                    />
                  </template>
                </UInput>
              </UFormField>
            </Field>

            <UButton
              color="neutral"
              variant="outline"
              block
              size="sm"
              :disabled="arrayField.items.length >= 5"
              @click="arrayField.append({ address: '' })"
            >
              Add Email Address
            </UButton>
          </div>
        </UFormField>
      </ArrayField>

      <div
        class="
          flex gap-2

          *:flex-1 *:justify-center
        "
      >
        <UButton
          type="reset"
          color="neutral"
          variant="outline"
        >
          Reset
        </UButton>

        <UButton type="submit">
          Submit
        </UButton>
      </div>
    </Form>
  </UApp>
</template>
```

</code-collapse>

## Related

- [Custom components](https://notformdocs.vercel.app/docs/integrations/custom-components)
- [Nuxt module](https://notformdocs.vercel.app/docs/getting-started/nuxt-module)

---

- **Page:** Working with AI
- **Source:** https://notformdocs.vercel.app/docs/ai/working-with-ai
- **Description:** Give AI coding assistants accurate NotForm knowledge using llms.txt, per-page Markdown, and the NotForm agent skill.

AI assistants are fast at writing form code, and just as quick to invent APIs that do not exist. NotForm's API is small but specific, so an assistant working from memory will often reach for names from other libraries.

NotForm gives assistants three ways to work from the real documentation.

<table>
<thead>
  <tr>
    <th>
      Resource
    </th>
    
    <th>
      What it is
    </th>
    
    <th>
      Best for
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="/docs/ai/llms-txt">
        <code>
          llms.txt
        </code>
      </a>
    </td>
    
    <td>
      An index of every documentation page with a one-line description
    </td>
    
    <td>
      Letting an assistant discover which pages exist
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/docs/ai/llms-txt#read-a-single-page">
        Page Markdown
      </a>
    </td>
    
    <td>
      Any documentation page as clean Markdown
    </td>
    
    <td>
      Loading exactly the pages a task needs
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/docs/ai/llms-txt#the-full-documentation">
        <code>
          llms-full.txt
        </code>
      </a>
    </td>
    
    <td>
      The whole documentation in one file
    </td>
    
    <td>
      Broad tasks, or tools that cannot follow links
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/docs/ai/agent-skill">
        The agent skill
      </a>
    </td>
    
    <td>
      A short set of instructions that routes an agent to the right pages
    </td>
    
    <td>
      Making the agent do all of the above on its own
    </td>
  </tr>
</tbody>
</table>

## Quick start

1. **Install the skill.** Copy the `notform` skill into your project so your assistant loads it automatically. See [Agent skill](https://notformdocs.vercel.app/docs/ai/agent-skill#install).
2. **Ask for what you need.** Describe the form in plain words. The skill makes the assistant read the matching pages before it writes code.
3. **Review against the docs.** Ask the assistant which pages it used. If something it wrote is not in those pages, it is a guess.

No skill support? Paste `https://notformdocs.vercel.app/llms.txt` into the conversation and ask the assistant to read the pages relevant to your task before writing code.

## What assistants get right and wrong

Assistants do well when the docs are in front of them. These are the mistakes the documentation and skill are designed to prevent:

- using `path` props or form context from NotForm v3 instead of explicit field instances;
- using `index` instead of `item.id` as an array key;
- mutating arrays directly instead of through `ArrayField` methods;
- expecting `form.setValue` or `field.model` writes to validate;
- passing field configuration on every render and expecting it to apply;
- mixing NotForm with another form library on the same form.

## Next steps

- [llms.txt and Markdown pages](https://notformdocs.vercel.app/docs/ai/llms-txt)
- [The NotForm agent skill](https://notformdocs.vercel.app/docs/ai/agent-skill)

---

- **Page:** Migrating from NotForm v3
- **Source:** https://notformdocs.vercel.app/docs/migrations/notform-v3
- **Description:** Update NotForm v3 code to v4: renamed APIs, explicit field instances, moved validation config, and array fields.

NotForm v4 changes the public Vue API. This guide updates forms written with the v3 names `useNotForm`, `NotForm`, `NotField`, `NotArrayField`, and `NotMessage`.

<note>

Check your installed version first. If `notform` in your `package.json` is `3.x`, the rest of these docs describe the version you are migrating to.

</note>

## 1. Rename the APIs

<table>
<thead>
  <tr>
    <th>
      NotForm v3
    </th>
    
    <th>
      NotForm v4
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        useNotForm
      </code>
    </td>
    
    <td>
      <code>
        useForm
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <NotForm>
      </code>
    </td>
    
    <td>
      <code>
        <Form>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <NotField>
      </code>
    </td>
    
    <td>
      <code>
        <Field>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <NotArrayField>
      </code>
    </td>
    
    <td>
      <code>
        <ArrayField>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <NotMessage>
      </code>
    </td>
    
    <td>
      <code>
        <FieldError>
      </code>
    </td>
  </tr>
</tbody>
</table>

The core package is still `notform`. For Nuxt, use `@notform/nuxt`. Older instructions may reference `notform-nuxt`, so replace that dependency. In Vue, update imports from `notform`. In Nuxt, the module auto-imports the v4 names.

Rename everywhere with a project-wide search and replace on whole words, then fix the structural changes below.

## 2. Pass explicit field instances

In v3, `<NotForm>` provided form context to descendants, so a field could be declared with only a `path`. In v4, `Form` renders the native form but provides no context. Create each field on the form instance and pass it to `Field`.

<code-group>

```vue [v3.vue]
<template>
  <NotForm :form="form">
    <NotField
      v-slot="{ events, path }"
      path="email"
    >
      <input
        v-bind="events"
        :id="path"
        v-model="form.values.email"
        type="email"
        :name="path"
      >

      <NotMessage :path="path" />
    </NotField>
  </NotForm>
</template>
```

```vue [v4.vue]
<template>
  <Form :form="form">
    <Field
      v-slot="{ field }"
      :field="form.field('email')"
    >
      <input
        v-bind="field.events"
        :id="field.path"
        v-model="field.model"
        type="email"
        :name="field.path"
      >

      <FieldError :errors="field" />
    </Field>
  </Form>
</template>
```

</code-group>

The v4 `Field` slot exposes one `field` object. Use `field.model`, `field.events`, `field.path`, and `field.errors` instead of the top-level slot props `events`, `path`, and `errors`. Binding `field.model` also replaces writing to `form.values.email` directly, though that still works.

## 3. Move validation config to the field

v3 field components accepted options such as `validateOn`, `validationMode`, and `debounce` as props. In v4, pass a `FieldConfig` as the second argument when the field is first created.

```ts
const username = form.field('username', {
  debounce: 300,
  validateOn: { input: true },
  validationMode: 'lazy',
})
```

The keys of `validateOn` are `blur`, `change`, and `input`. A field is cached by path, so later calls with different options do not replace the first. See [Validation](https://notformdocs.vercel.app/docs/guides/validation#configure-a-field).

## 4. Update array fields

v3 `NotArrayField` was declared by path. In v4, create an explicit array field, and use `item.id` as the key.

<code-collapse>

```vue
<template>
  <ArrayField
    v-slot="{ arrayField }"
    :array-field="form.arrayField('todos')"
  >
    <div
      v-for="item in arrayField.items"
      :key="item.id"
    >
      <Field
        v-slot="{ field }"
        :field="item"
      >
        <input
          v-bind="field.events"
          :id="field.path"
          v-model="field.model"
          type="email"
          :name="field.path"
        >

        <FieldError :errors="field" />
      </Field>

      <button
        type="button"
        @click="arrayField.remove(item.index)"
      >
        Remove
      </button>
    </div>

    <button
      type="button"
      @click="arrayField.append('')"
    >
      Add
    </button>
  </ArrayField>
</template>
```

</code-collapse>

Each item provides `index`, `path`, `field()`, and `arrayField()` for nested values. Mutations are methods on `arrayField`. See [Array fields](https://notformdocs.vercel.app/docs/guides/array-fields).

## 5. Check the rest of the form

- `Form` requires a `form` prop and does not inject it into descendants.
- `FieldError` takes an issue array or a field-like value through `errors`. It no longer resolves a path from form context.
- `onSubmit` remains a `useForm` option, and `Form` handles native submit and reset.
- `useForm` returns the public API in [useForm](https://notformdocs.vercel.app/docs/composables/use-form). Do not rely on instance members that are not listed there.

## Migration checklist

- [ ] Dependencies updated (`notform`, and `@notform/nuxt` instead of `notform-nuxt`).
- [ ] All `useNotForm`, `NotForm`, `NotField`, `NotArrayField`, and `NotMessage` renamed.
- [ ] Every `Field` receives `:field="form.field(path)"` instead of a `path` prop.
- [ ] Slot props switched to `field.model`, `field.events`, `field.path`, and `field.errors`.
- [ ] `FieldError` receives `:errors="field"`.
- [ ] Validation options moved into `form.field(path, config)`.
- [ ] Array fields use `form.arrayField(path)`, `item.id` keys, and array methods.
- [ ] Type check and lint pass. Mistyped paths are now compile errors.

## Next steps

- [Quickstart](https://notformdocs.vercel.app/docs/getting-started/quickstart) shows a complete v4 form.
- [Core concepts](https://notformdocs.vercel.app/docs/getting-started/core-concepts) explains the model that v4 makes explicit.

---

- **Page:** Multi-step forms
- **Source:** https://notformdocs.vercel.app/docs/recipes/multi-step-forms
- **Description:** Split one form into steps, validate each step before continuing, and submit everything at the end.

A multi-step form is one form whose schema changes as the user moves through it. Each step renders a subset of the fields and validates against its own schema. Because values live in the form, they persist as users move between steps.

## Approach

1. Define one schema per step. Each schema extends the previous one, so the last schema describes the whole form.
2. Pick the active schema from the current step index and pass it to `useForm`.
3. Render a `type="submit"` button on every step. Submit validates the active schema, then calls `onSubmit`.
4. In `onSubmit`, advance to the next step. On the final step, send the values instead.

## Example

<code-collapse>

```vue
<script setup lang="ts">
import { Field, FieldError, Form, useForm } from 'notform'
import { computed, ref } from 'vue'
import { z } from 'zod'

const plans = ['free', 'pro'] as const

// Step 1: personal information.
const profileStepSchema = z.object({
  email: z.email('Enter a valid email address.'),
  name: z.string().min(1, 'Enter your name.'),
})

/*
 * Step 2: plan selection.
 * Each step's schema extends the previous one, so the final submit
 * receives every field the user entered, not only the last step's.
 */
const planStepSchema = profileStepSchema.extend({
  plan: z.enum(plans, { error: 'Choose a plan.' }),
})

const stepSchemas = [profileStepSchema, planStepSchema]

const stepIndex = ref(0)
const isFirstStep = computed(() => {
  return stepIndex.value === 0
})
const isLastStep = computed(() => {
  return stepIndex.value === stepSchemas.length - 1
})

// Validate only against the schema of the step the user is on.
const activeSchema = computed(() => {
  return stepSchemas[stepIndex.value]
})

const form = useForm({
  initialValues: { email: '', name: '' },
  schema: activeSchema,

  // Runs only after the active step has passed validation.
  async onSubmit(values) {
    if (!isLastStep.value) {
      stepIndex.value++
      return
    }

    const response = await fetch('/api/sign-up', {
      body: JSON.stringify(values),
      headers: { 'content-type': 'application/json' },
      method: 'POST',
    })

    if (!response.ok) {
      throw new Error('Sign-up failed.')
    }
  },
})

function goToPreviousStep() {
  if (!isFirstStep.value) {
    stepIndex.value--
  }
}
</script>

<template>
  <Form
    :form="form"
    novalidate
  >
    <!-- Step 1: Personal information -->
    <div v-if="stepIndex === 0">
      <Field
        v-slot="{ field }"
        :field="form.field('name')"
      >
        <label :for="field.path">Name</label>

        <input
          :id="field.path"
          v-model="field.model"
          v-bind="field.events"
        >

        <FieldError :errors="field" />
      </Field>

      <Field
        v-slot="{ field }"
        :field="form.field('email')"
      >
        <label :for="field.path">Email</label>

        <input
          :id="field.path"
          v-model="field.model"
          v-bind="field.events"
          type="email"
        >

        <FieldError :errors="field" />
      </Field>
    </div>

    <!-- Step 2: Plan selection -->
    <div v-else-if="stepIndex === 1">
      <Field
        v-slot="{ field }"
        :field="form.field('plan')"
      >
        <fieldset>
          <legend>Plan</legend>

          <label
            v-for="plan in plans"
            :key="plan"
          >
            <input
              v-model="field.model"
              v-bind="field.events"
              type="radio"
              :name="field.path"
              :value="plan"
            >
            {{ plan }}
          </label>
        </fieldset>

        <FieldError :errors="field" />
      </Field>
    </div>

    <!-- Navigation -->
    <button
      v-if="!isFirstStep"
      type="button"
      @click="goToPreviousStep"
    >
      Previous
    </button>

    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      {{ isLastStep ? 'Finish' : 'Next' }}
    </button>
  </Form>
</template>
```

</code-collapse>

## Why this works

- **Values persist.** `form.values` holds every step's data. Fields on hidden steps simply are not rendered, but their values remain.
- **Step validation is scoped.** The form validates against `activeSchema`, so fields from later steps cannot produce errors early.
- **Next needs no validity check.** `onSubmit` runs only after the active schema passes, so advancing the step there is enough.
- **The final submit is authoritative.** The last schema extends every earlier one, so it validates every field and `values` contains everything the user entered. Every field counts as touched.

## Notes

- Give every field a starting value, including steps the user has not reached. `undefined` is correct for a choice with no default, as with `plan`.
- Do not gate navigation on `form.isValid`. It is `true` before any validation has run, and validation is async, so reading it right after a click can let an invalid step through. Let `onSubmit` do the gating, as the example does.
- Next is a submit button, so pressing Enter in a field behaves like clicking Next: it validates the active step and advances. Previous is `type="button"`, so it never submits or validates.
- To keep step state in the URL, store `stepIndex` in a route query. NotForm does not need to know about it.

## With Pinia

The same approach works when the form lives in a Pinia store. Create the form in the store, render each step as its own component, and wrap the active step in `<KeepAlive>` so step components are cached while the user moves between them.

This helps when steps are large enough to live in separate files, or when something outside the form, such as a progress sidebar or a route guard, needs to read the current step.

<code-collapse>
<code-group>

```ts [stores/signup.ts]
import { useForm } from 'notform'
import { defineStore } from 'pinia'
import { computed, ref } from 'vue'

// `profileStepSchema` and `planStepSchema` are the same as above.
const stepSchemas = [profileStepSchema, planStepSchema]

export const useSignUpStore = defineStore('sign-up', () => {
  const stepIndex = ref(0)
  const isFirstStep = computed(() => {
    return stepIndex.value === 0
  })
  const isLastStep = computed(() => {
    return stepIndex.value === stepSchemas.length - 1
  })
  const activeSchema = computed(() => {
    return stepSchemas[stepIndex.value]
  })

  const form = useForm({
    initialValues: { email: '', name: '' },
    async onSubmit(values) {
      if (!isLastStep.value) {
        stepIndex.value++
      }

      // Send `values` to your API.
    },
    schema: activeSchema,
  })

  function goToPreviousStep() {
    if (!isFirstStep.value) {
      stepIndex.value--
    }
  }

  return { form, goToPreviousStep, isFirstStep, isLastStep, stepIndex }
})
```

```vue [components/sign-up-form.vue]
<script setup lang="ts">
import { Form } from 'notform'
import { useSignUpStore } from '../stores/sign-up'
import PlanStep from './PlanStep.vue'
import ProfileStep from './ProfileStep.vue'

const signUp = useSignUpStore()
const steps = [ProfileStep, PlanStep]
</script>

<template>
  <Form
    :form="signUp.form"
    novalidate
  >
    <KeepAlive>
      <component :is="steps[signUp.stepIndex]" />
    </KeepAlive>

    <button
      v-if="!signUp.isFirstStep"
      type="button"
      @click="signUp.goToPreviousStep"
    >
      Previous
    </button>

    <button
      type="submit"
      :disabled="signUp.form.isSubmitting"
    >
      {{ signUp.isLastStep ? 'Finish' : 'Next' }}
    </button>
  </Form>
</template>
```

</code-group>
</code-collapse>

Each step component reads the store and renders its own `Field`s, exactly like the single-file example.

- **Values live in the store, not in KeepAlive.** The form keeps every step's values either way. `KeepAlive` only preserves each step's component state, such as focus, scroll position, and local UI state, and skips re-mounting.
- **KeepAlive takes one child at a time.** Switching with `<component :is>` fits this naturally.
- **The store outlives the page.** Reset the form and `stepIndex` when the wizard finishes or the user leaves, or the next visit starts mid-way.

---

- **Page:** llms.txt and Markdown pages
- **Source:** https://notformdocs.vercel.app/docs/ai/llms-txt
- **Description:** What the NotForm llms.txt, llms-full.txt, and per-page Markdown endpoints contain, and how to use each with an AI tool.

[`llms.txt`](https://llmstxt.org) is a convention for publishing documentation in a form that language models can read. The NotForm docs publish three views.

<table>
<thead>
  <tr>
    <th>
      Resource
    </th>
    
    <th>
      URL
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Index
    </td>
    
    <td>
      <a href="/llms.txt" external="" target="_blank">
        <code>
          https://notformdocs.vercel.app/llms.txt
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Full documentation
    </td>
    
    <td>
      <a href="/llms-full.txt" external="" target="_blank">
        <code>
          https://notformdocs.vercel.app/llms-full.txt
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      A single page
    </td>
    
    <td>
      <code>
        https://notformdocs.vercel.app/docs/<section>/<page>.md
      </code>
    </td>
  </tr>
</tbody>
</table>

## The index

`llms.txt` is a short Markdown file that lists the documentation pages with a short description of each. It is the cheapest way for an assistant to learn what exists, and it is small enough to load at the start of any task.

Typical use: give the URL to an assistant and ask it to pick the pages it needs.

> Read [https://notformdocs.vercel.app/llms.txt](https://notformdocs.vercel.app/llms.txt), then read the pages about array fields and validation, and build a repeatable contacts form.

## Read a single page

Add `.md` to a documentation page's path to get that page as Markdown. Use the section and page names from the URL in your browser.

```text
https://notformdocs.vercel.app/docs/components/field.md
https://notformdocs.vercel.app/docs/guides/validation.md
https://notformdocs.vercel.app/docs/recipes/server-errors.md
```

Loading focused pages keeps the assistant's context small and its answers specific. This is the preferred way to use the docs with an AI tool.

## The full documentation

`llms-full.txt` contains the whole documentation in a single file. Use it when:

- the task spans many sections, such as a migration;
- the tool cannot follow links or fetch several pages; or
- you want to load everything once and ask many questions.

It is large. For a single question, the index plus one or two pages is faster and cheaper.

## Which should I use?

<table>
<thead>
  <tr>
    <th>
      Situation
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Build or fix one feature
    </td>
    
    <td>
      Index, then the relevant pages
    </td>
  </tr>
  
  <tr>
    <td>
      Migrate from NotForm v3
    </td>
    
    <td>
      <a href="/docs/migrations/notform-v3">
        The migration page
      </a>
      
      , then the pages for each API it names
    </td>
  </tr>
  
  <tr>
    <td>
      Tool only accepts one URL or file
    </td>
    
    <td>
      <code>
        llms-full.txt
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      You already know the page
    </td>
    
    <td>
      The page's <code>
        .md
      </code>
      
       URL
    </td>
  </tr>
  
  <tr>
    <td>
      Repeated work in one project
    </td>
    
    <td>
      <a href="/docs/ai/agent-skill">
        The agent skill
      </a>
    </td>
  </tr>
</tbody>
</table>

## Using the files with common tools

- **Chat assistants:** paste the URL into the conversation and ask the assistant to read it.
- **Editors and coding agents:** add the URL as a documentation source in the tool's settings, or reference it in your project's agent instructions.
- **Your own scripts:** fetch the `.md` URLs directly. They are plain Markdown.

## Keep in mind

- The files describe the **latest published** documentation. If your project pins an older NotForm version, check that the API you rely on exists in your installed package.
- The index lists pages, not behavior. Always read the page before writing code against it.

---

- **Page:** ShadcnVue
- **Source:** https://notformdocs.vercel.app/docs/integrations/shadcn-vue
- **Description:** Use NotForm with ShadcnVue inputs, including text, textarea, select, checkbox, radio group, switch, and array fields, and avoid the Field and FieldError naming conflict.

ShadcnVue copies component source into your project, so the exact props depend on the version you installed. The mappings below follow the pattern in [Custom components](https://notformdocs.vercel.app/docs/integrations/custom-components). Check your local component files if a binding differs.

## Resolve the naming conflict

Recent ShadcnVue releases include `Field` and `FieldError` components. NotForm exports components with the same names. Rename one set at the import.

<code-group>

```vue [Vue]
<script setup lang="ts">
import { Form, Field as NotField, FieldError as NotFieldError, useForm } from 'notform'
import { Field, FieldError, FieldLabel } from '@/components/ui/field'
</script>
```

```ts [Nuxt]
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@notform/nuxt', 'shadcn-vue/nuxt'],
  notform: {
    aliases: {
      Field: 'NotField',
      FieldError: 'NotFieldError'
    },
  },
})
```

</code-group>

The examples below use `NotField` for NotForm and `Field` for ShadcnVue.

## Choose the right binding

Every `NotField` slot gives you a `field` with a `model`, a set of `events`, and the validation state (`isValid` and `errors`). How you connect them depends on what the ShadcnVue component emits.

<table>
<thead>
  <tr>
    <th>
      Component
    </th>
    
    <th>
      Binding
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Input
      </code>
      
      , <code>
        Textarea
      </code>
      
      , <code>
        InputGroupInput
      </code>
      
      , <code>
        InputGroupTextarea
      </code>
    </td>
    
    <td>
      <code>
        v-model="field.model"
      </code>
      
       and <code>
        v-bind="field.events"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Select
      </code>
    </td>
    
    <td>
      <code>
        v-model="field.model"
      </code>
      
       and <code>
        @update:model-value="field.events.onChange"
      </code>
      
      , with <code>
        @blur="field.events.onBlur"
      </code>
      
       on <code>
        SelectTrigger
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Checkbox
      </code>
      
      , <code>
        Switch
      </code>
      
      , <code>
        RadioGroup
      </code>
    </td>
    
    <td>
      <code>
        v-model="field.model"
      </code>
      
      , <code>
        @update:model-value="field.events.onChange"
      </code>
      
       and <code>
        @blur="field.events.onBlur"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Checkbox group (array of values)
    </td>
    
    <td>
      <code>
        :model-value
      </code>
      
       and a handler that updates <code>
        field.model
      </code>
      
      , then calls <code>
        field.events.onChange()
      </code>
    </td>
  </tr>
</tbody>
</table>

Components that only emit `update:modelValue` don't fire native `input` or `change` events, so `v-bind="field.events"` does nothing for them. Report changes and blur explicitly instead.

Each section below shows the template and the schema it binds to. The snippets assume the `form` and the imports from the [full example](#full-example).

## Text input

```ts
title: z
  .string()
  .min(5, 'Bug title must be at least 5 characters.')
  .max(32, 'Bug title must be at most 32 characters.')
```

<code-collapse>

```vue
<template>
  <NotField
    v-slot="{ field }"
    :field="form.field('title')"
  >
    <Field :data-invalid="!field.isValid">
      <FieldLabel :for="field.path">
        Bug Title
      </FieldLabel>

      <Input
        :id="field.path"
        v-bind="field.events"
        v-model="field.model"
        placeholder="Login button not working on mobile"
        autocomplete="off"
        :aria-invalid="!field.isValid"
      />

      <FieldError
        v-if="!field.isValid"
        :errors="field.errors"
      />
    </Field>
  </NotField>
</template>
```

</code-collapse>

`field.errors` is an array of issues that each have a `message`, which is the shape ShadcnVue's `FieldError` renders.

## Textarea

Use `InputGroupTextarea` inside an `InputGroup` when you want an addon, such as a character counter. It takes the same bindings as a text input.

```ts
description: z
  .string()
  .min(20, 'Description must be at least 20 characters.')
  .max(100, 'Description must be at most 100 characters.')
```

<code-collapse>

```vue
<template>
  <NotField
    v-slot="{ field }"
    :field="form.field('description')"
  >
    <Field :data-invalid="!field.isValid">
      <FieldLabel :for="field.path">
        Description
      </FieldLabel>

      <InputGroup>
        <InputGroupTextarea
          :id="field.path"
          v-model="field.model"
          v-bind="field.events"
          placeholder="I'm having an issue with the login button on mobile."
          :rows="6"
          class="resize-none min-block-24"
          :aria-invalid="!field.isValid"
        />

        <InputGroupAddon align="block-end">
          <InputGroupText class="tabular-nums">
            {{ field.model?.length || 0 }}/100 characters
          </InputGroupText>
        </InputGroupAddon>
      </InputGroup>

      <FieldDescription>
        Include steps to reproduce, expected behavior, and what actually
        happened.
      </FieldDescription>

      <FieldError
        v-if="!field.isValid"
        :errors="field.errors"
      />
    </Field>
  </NotField>
</template>
```

</code-collapse>

`field.model` is reactive, so you can read it anywhere in the slot, which is how the counter stays in sync.

## Select

The trigger is the focusable element, so put the `id` and report blur from it.

```ts
language: z.string().min(1, 'Please select your spoken language.')
```

<code-collapse>

```vue
<template>
  <NotField
    v-slot="{ field }"
    :field="form.field('language')"
  >
    <Field :data-invalid="!field.isValid">
      <FieldLabel :for="field.path">
        Spoken Language
      </FieldLabel>

      <!-- eslint-disable-next-line vue-a11y/form-control-has-label -->
      <Select
        v-model="field.model"
        @update:model-value="field.events.onChange"
      >
        <SelectTrigger
          :id="field.path"
          :aria-invalid="!field.isValid"
          @blur="field.events.onBlur()"
        >
          <SelectValue placeholder="Select" />
        </SelectTrigger>

        <SelectContent>
          <SelectItem
            v-for="language in spokenLanguages"
            :key="language.value"
            :value="language.value"
          >
            {{ language.label }}
          </SelectItem>
        </SelectContent>
      </Select>

      <FieldError
        v-if="!field.isValid"
        :errors="field.errors"
      />
    </Field>
  </NotField>
</template>
```

</code-collapse>

Keep an empty string as the initial value so the placeholder shows until the user picks something.

## Checkbox

Bind the checkbox with `v-model:model-value`, then report changes and blur to NotForm yourself: call `field.events.onChange` from `update:model-value` and `field.events.onBlur` from `blur`.

```ts
responses: z.literal(true, 'Notifications are mandatory')
```

<code-collapse>

```vue
<template>
  <NotField
    v-slot="{ field }"
    :field="form.field('responses')"
  >
    <Field
      orientation="horizontal"
      :data-invalid="!field.isValid"
    >
      <Checkbox
        :id="field.path"
        v-model="field.model"
        :aria-invalid="!field.isValid"
        @blur="field.events.onBlur"
        @update:model-value="field.events.onChange"
      />

      <FieldLabel
        :for="field.path"
        class="font-normal"
      >
        Push notifications
      </FieldLabel>
    </Field>

    <FieldError
      v-if="!field.isValid"
      :errors="field.errors"
    />
  </NotField>
</template>
```

</code-collapse>

If the checkbox can be in an indeterminate state, its value is not a plain boolean, so your schema must accept that.

## Checkbox group

When several checkboxes share one field, store the selected values in an array. The checkbox doesn't bind to `field.model` directly. Instead, derive its checked state and write the new array back yourself.

```ts
tasks: z
  .array(z.string())
  .min(1, 'Please select at least one notification type.')
```

<code-collapse>

```vue
<template>
  <NotField
    v-slot="{ field }"
    :field="form.field('tasks')"
  >
    <FieldSet :data-invalid="!field.isValid">
      <FieldLegend variant="label">
        Tasks
      </FieldLegend>

      <FieldDescription>
        Get notified when tasks you've created have updates.
      </FieldDescription>

      <FieldGroup data-slot="checkbox-group">
        <Field
          v-for="task in tasks"
          :key="task.id"
          orientation="horizontal"
          :data-invalid="!field.isValid"
        >
          <Checkbox
            :id="`${field.path}-${task.id}`"
            :aria-invalid="!field.isValid"
            :model-value="field.model?.includes(task.id)"
            @blur="field.events.onBlur()"
            @update:model-value="(checked: boolean | 'indeterminate') => {
              field.model = checked === true
                ? [...(field.model ?? []), task.id]
                : (field.model ?? []).filter(value => value !== task.id)

              field.events.onChange()
            }"
          />

          <FieldLabel
            :for="`${field.path}-${task.id}`"
            class="font-normal"
          >
            {{ task.label }}
          </FieldLabel>
        </Field>
      </FieldGroup>

      <FieldError
        v-if="!field.isValid"
        :errors="field.errors"
      />
    </FieldSet>
  </NotField>
</template>
```

</code-collapse>

Give each checkbox a unique `id` by appending the item's id to `field.path`, and call `field.events.onChange()` after you update the model so validation runs against the new value.

## Radio group

Bind the group, not the items. Each `RadioGroupItem` only needs its own `value`.

```ts
plan: z.string().min(1, 'You must select a subscription plan to continue.')
```

<code-collapse>

```vue
<template>
  <NotField
    v-slot="{ field }"
    :field="form.field('plan')"
  >
    <FieldSet :data-invalid="!field.isValid">
      <FieldLegend>Plan</FieldLegend>

      <FieldDescription>
        You can upgrade or downgrade your plan at any time.
      </FieldDescription>

      <RadioGroup
        v-model="field.model"
        :aria-invalid="!field.isValid"
        @blur="field.events.onBlur"
        @update:model-value="field.events.onChange"
      >
        <FieldLabel
          v-for="plan in plans"
          :key="plan.id"
          :for="`${field.path}-${plan.id}`"
        >
          <Field
            orientation="horizontal"
            :data-invalid="!field.isValid"
          >
            <FieldContent>
              <FieldTitle>{{ plan.title }}</FieldTitle>

              <FieldDescription>
                {{ plan.description }}
              </FieldDescription>
            </FieldContent>

            <RadioGroupItem
              :id="`${field.path}-${plan.id}`"
              :value="plan.id"
              :aria-invalid="!field.isValid"
            />
          </Field>
        </FieldLabel>
      </RadioGroup>

      <FieldError
        v-if="!field.isValid"
        :errors="field.errors"
      />
    </FieldSet>
  </NotField>
</template>
```

</code-collapse>

## Switch

`Switch` follows the same pattern as `Checkbox`: a boolean model plus explicit change and blur handlers.

```ts
twoFactor: z.boolean().refine((value) => {
  return value === true
}, 'It is highly recommended to enable two-factor authentication.')
```

<code-collapse>

```vue
<template>
  <NotField
    v-slot="{ field }"
    :field="form.field('twoFactor')"
  >
    <Field
      orientation="horizontal"
      :data-invalid="!field.isValid"
    >
      <FieldContent>
        <FieldLabel :for="field.path">
          Multi-factor authentication
        </FieldLabel>

        <FieldDescription>
          Enable multi-factor authentication to secure your account.
        </FieldDescription>

        <FieldError
          v-if="!field.isValid"
          :errors="field.errors"
        />
      </FieldContent>

      <Switch
        :id="field.path"
        v-model="field.model"
        :aria-invalid="!field.isValid"
        @blur="field.events.onBlur"
        @update:model-value="field.events.onChange"
      />
    </Field>
  </NotField>
</template>
```

</code-collapse>

## Array fields

Use `ArrayField` for lists the user can grow, shrink, and reorder. Each item exposes `item.field('key')`, so you can wrap any of the inputs above in a `NotField`.

```ts
emails: z
  .array(z.object({
    address: z.email('Enter a valid email address.'),
  }))
  .min(2, 'Add at least two email addresses.')
  .max(5, 'You can add up to 5 email addresses.')
```

<code-collapse>

```vue
<template>
  <ArrayField
    v-slot="{ arrayField }"
    :array-field="form.arrayField('emails')"
  >
    <FieldSet :data-invalid="!arrayField.isValid">
      <FieldLegend variant="label">
        Email Addresses
      </FieldLegend>

      <FieldDescription>
        Add up to 5 email addresses where we can contact you.
      </FieldDescription>

      <FieldGroup class="gap-4">
        <NotField
          v-for="item in arrayField.items"
          :key="item.id"
          v-slot="{ field }"
          :field="item.field('address')"
        >
          <Field
            orientation="horizontal"
            :data-invalid="!field.isValid"
          >
            <FieldContent>
              <InputGroup>
                <InputGroupInput
                  :id="field.path"
                  v-model="field.model"
                  v-bind="field.events"
                  :aria-invalid="!field.isValid"
                  placeholder="name@example.com"
                  type="email"
                  autocomplete="email"
                />

                <InputGroupAddon
                  v-if="arrayField.items.length > 1"
                  align="inline-end"
                >
                  <InputGroupButton
                    type="button"
                    variant="ghost"
                    size="icon-xs"
                    :disabled="item.index === 0"
                    :aria-label="`Move email ${item.index + 1} up`"
                    @click="arrayField.move(item.index, item.index - 1)"
                  >
                    <ChevronUp />
                  </InputGroupButton>

                  <InputGroupButton
                    type="button"
                    variant="ghost"
                    size="icon-xs"
                    :disabled="item.index === arrayField.items.length - 1"
                    :aria-label="`Move email ${item.index + 1} down`"
                    @click="arrayField.move(item.index, item.index + 1)"
                  >
                    <ChevronDown />
                  </InputGroupButton>

                  <InputGroupButton
                    type="button"
                    variant="ghost"
                    size="icon-xs"
                    :aria-label="`Remove email ${item.index + 1}`"
                    @click="arrayField.remove(item.index)"
                  >
                    <X />
                  </InputGroupButton>
                </InputGroupAddon>
              </InputGroup>

              <FieldError
                v-if="!field.isValid"
                :errors="field.errors"
              />
            </FieldContent>
          </Field>
        </NotField>

        <Button
          type="button"
          variant="outline"
          size="sm"
          :disabled="arrayField.items.length >= 5"
          @click="arrayField.append({ address: '' })"
        >
          Add Email Address
        </Button>
      </FieldGroup>

      <FieldError
        v-if="!arrayField.isValid"
        :errors="arrayField.errors"
      />
    </FieldSet>
  </ArrayField>
</template>
```

</code-collapse>

A few things to note:

- `arrayField.items` gives you each item's `id` and `index`. Use `item.id` as the `:key`, not the index, so inputs keep their state when you reorder or remove items.
- `arrayField.append`, `arrayField.remove` and `arrayField.move` change the list. Set `type="button"` on every button that calls them so they don't submit the form.
- Errors for a single item come from its `field`. Errors for the list as a whole, such as the `min` and `max` rules, come from `arrayField.errors`.
- Mirror the schema limits in the UI, as the **Add** button does with `arrayField.items.length >= 5`, so users can't reach an invalid state by clicking.

## Full example

This form combines every input above. It assumes `vue`, `zod`, `@lucide/vue` and the ShadcnVue components you've added to your project.

<code-collapse>

```vue
<script setup lang="ts">
import { ChevronDown, ChevronUp, X } from '@lucide/vue'
import { ArrayField, Form, Field as NotField, useForm } from 'notform'
import { z } from 'zod'
import { Button } from '@/components/ui/button'
import { Checkbox } from '@/components/ui/checkbox'
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
  FieldTitle,
} from '@/components/ui/field'
import { Input } from '@/components/ui/input'
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from '@/components/ui/input-group'
import {
  RadioGroup,
  RadioGroupItem,
} from '@/components/ui/radio-group'
import {
  Select,
  SelectContent,
  SelectItem,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from '@/components/ui/select'
import { Switch } from '@/components/ui/switch'

const spokenLanguages = [
  { label: 'English', value: 'en' },
  { label: 'Spanish', value: 'es' },
  { label: 'French', value: 'fr' },
  { label: 'German', value: 'de' },
  { label: 'Italian', value: 'it' },
  { label: 'Chinese', value: 'zh' },
  { label: 'Japanese', value: 'ja' },
] as const

const plans = [
  {
    description: 'For everyday use with basic features.',
    id: 'starter',
    title: 'Starter (100K tokens/month)',
  },
  {
    description: 'For advanced AI usage with more features.',
    id: 'pro',
    title: 'Pro (1M tokens/month)',
  },
  {
    description: 'For large teams and heavy usage.',
    id: 'enterprise',
    title: 'Enterprise (Unlimited tokens)',
  },
] as const

const tasks = [
  {
    id: 'push',
    label: 'Push notifications',
  },
  {
    id: 'email',
    label: 'Email notifications',
  },
] as const

const schema = z.object({
  description: z
    .string()
    .min(20, 'Description must be at least 20 characters.')
    .max(100, 'Description must be at most 100 characters.'),
  emails: z
    .array(z.object({
      address: z.email('Enter a valid email address.'),
    }))
    .min(2, 'Add at least two email addresses.')
    .max(5, 'You can add up to 5 email addresses.'),
  language: z
    .string()
    .min(1, 'Please select your spoken language.')
    .refine((value) => {
      return value !== 'auto'
    }, 'Auto-detection is not allowed. Please select a specific language.'),
  plan: z.string().min(1, 'You must select a subscription plan to continue.'),
  responses: z.literal(true, 'Notifications are mandatory'),
  tasks: z
    .array(z.string())
    .min(1, 'Please select at least one notification type.')
    .refine((value) => {
      return value.every((taskId) => {
        return tasks.some((task) => {
          return task.id === taskId
        })
      })
    }, 'Invalid notification type selected.'),
  title: z
    .string()
    .min(5, 'Bug title must be at least 5 characters.')
    .max(32, 'Bug title must be at most 32 characters.'),
  twoFactor: z.boolean().refine((value) => {
    return value === true
  }, 'It is highly recommended to enable two-factor authentication.'),
})

const form = useForm({
  initialValues: {
    description: '',
    emails: [{ address: '' }, { address: '' }],
    language: '',
    plan: '',
    responses: true,
    tasks: [],
    title: '',
    twoFactor: false,
  },
  onSubmit(data) {
    console.log(data)
  },
  schema,
})
</script>

<template>
  <Form
    :form
    class="
      mx-auto p-8 inline-full

      sm:max-inline-xl
    "
  >
    <FieldGroup>
      <!-- Text input -->
      <NotField
        v-slot="{ field }"
        :field="form.field('title')"
      >
        <Field :data-invalid="!field.isValid">
          <FieldLabel :for="field.path">
            Bug Title
          </FieldLabel>

          <Input
            :id="field.path"
            v-model="field.model"
            v-bind="field.events"
            placeholder="Login button not working on mobile"
            autocomplete="off"
            :aria-invalid="!field.isValid"
          />

          <FieldError
            v-if="!field.isValid"
            :errors="field.errors"
          />
        </Field>
      </NotField>

      <!-- Textarea -->
      <NotField
        v-slot="{ field }"
        :field="form.field('description')"
      >
        <Field :data-invalid="!field.isValid">
          <FieldLabel :for="field.path">
            Description
          </FieldLabel>

          <InputGroup>
            <InputGroupTextarea
              :id="field.path"
              v-model="field.model"
              v-bind="field.events"
              placeholder="I'm having an issue with the login button on mobile."
              :rows="6"
              class="resize-none min-block-24"
              :aria-invalid="!field.isValid"
            />

            <InputGroupAddon align="block-end">
              <InputGroupText class="tabular-nums">
                {{ field.model?.length || 0 }}/100 characters
              </InputGroupText>
            </InputGroupAddon>
          </InputGroup>

          <FieldDescription>
            Include steps to reproduce, expected behavior, and what actually
            happened.
          </FieldDescription>

          <FieldError
            v-if="!field.isValid"
            :errors="field.errors"
          />
        </Field>
      </NotField>

      <!-- Select -->
      <NotField
        v-slot="{ field }"
        :field="form.field('language')"
      >
        <Field :data-invalid="!field.isValid">
          <FieldContent>
            <FieldLabel :for="field.path">
              Spoken Language
            </FieldLabel>

            <FieldDescription>
              For best results, select the language you speak.
            </FieldDescription>

            <FieldError
              v-if="!field.isValid"
              :errors="field.errors"
            />
          </FieldContent>

          <!-- eslint-disable-next-line vue-a11y/form-control-has-label -->
          <Select
            v-model="field.model"
            @update:model-value="field.events.onChange"
          >
            <SelectTrigger
              :id="field.path"
              :aria-invalid="!field.isValid"
              class="min-inline-[120px]"
              @blur="field.events.onBlur()"
            >
              <SelectValue placeholder="Select" />
            </SelectTrigger>

            <SelectContent position="item-aligned">
              <SelectItem value="auto">
                Auto
              </SelectItem>

              <SelectSeparator />

              <SelectItem
                v-for="language in spokenLanguages"
                :key="language.value"
                :value="language.value"
              >
                {{ language.label }}
              </SelectItem>
            </SelectContent>
          </Select>
        </Field>
      </NotField>

      <!-- Checkbox -->
      <NotField
        v-slot="{ field }"
        :field="form.field('responses')"
      >
        <FieldSet :data-invalid="!field.isValid">
          <FieldLegend variant="label">
            Responses
          </FieldLegend>

          <FieldDescription>
            Get notified for requests that take time, like research or image
            generation.
          </FieldDescription>

          <FieldGroup data-slot="checkbox-group">
            <Field orientation="horizontal">
              <Checkbox
                :id="field.path"
                v-model="field.model"
                @blur="field.events.onBlur"
                @update:model-value="field.events.onChange"
              />

              <FieldLabel
                :for="field.path"
                class="font-normal"
              >
                Push notifications
              </FieldLabel>
            </Field>
          </FieldGroup>

          <FieldError
            v-if="!field.isValid"
            :errors="field.errors"
          />
        </FieldSet>
      </NotField>

      <!-- Checkbox group -->
      <NotField
        v-slot="{ field }"
        :field="form.field('tasks')"
      >
        <FieldSet :data-invalid="!field.isValid">
          <FieldLegend variant="label">
            Tasks
          </FieldLegend>

          <FieldDescription>
            Get notified when tasks you've created have updates.
          </FieldDescription>

          <FieldGroup data-slot="checkbox-group">
            <Field
              v-for="task in tasks"
              :key="task.id"
              orientation="horizontal"
              :data-invalid="!field.isValid"
            >
              <Checkbox
                :id="`${field.path}-${task.id}`"
                :aria-invalid="!field.isValid"
                :model-value="field.model?.includes(task.id)"
                @blur="field.events.onBlur()"
                @update:model-value="(checked: boolean | 'indeterminate') => {
                  field.model = checked === true
                    ? [...(field.model ?? []), task.id]
                    : (field.model ?? []).filter(value => value !== task.id)

                  field.events.onChange()
                }"
              />

              <FieldLabel
                :for="`${field.path}-${task.id}`"
                class="font-normal"
              >
                {{ task.label }}
              </FieldLabel>
            </Field>
          </FieldGroup>

          <FieldError
            v-if="!field.isValid"
            :errors="field.errors"
          />
        </FieldSet>
      </NotField>

      <!-- Radio group -->
      <NotField
        v-slot="{ field }"
        :field="form.field('plan')"
      >
        <FieldSet :data-invalid="!field.isValid">
          <FieldLegend>Plan</FieldLegend>

          <FieldDescription>
            You can upgrade or downgrade your plan at any time.
          </FieldDescription>

          <RadioGroup
            v-model="field.model"
            :aria-invalid="!field.isValid"
            @blur="field.events.onBlur"
            @update:model-value="field.events.onChange"
          >
            <FieldLabel
              v-for="plan in plans"
              :key="plan.id"
              :for="`${field.path}-${plan.id}`"
            >
              <Field
                orientation="horizontal"
                :data-invalid="!field.isValid"
              >
                <FieldContent>
                  <FieldTitle>{{ plan.title }}</FieldTitle>

                  <FieldDescription>
                    {{ plan.description }}
                  </FieldDescription>
                </FieldContent>

                <RadioGroupItem
                  :id="`${field.path}-${plan.id}`"
                  :value="plan.id"
                  :aria-invalid="!field.isValid"
                />
              </Field>
            </FieldLabel>
          </RadioGroup>

          <FieldError
            v-if="!field.isValid"
            :errors="field.errors"
          />
        </FieldSet>
      </NotField>

      <!-- Switch -->
      <NotField
        v-slot="{ field }"
        :field="form.field('twoFactor')"
      >
        <Field
          :data-invalid="!field.isValid"
          orientation="horizontal"
        >
          <FieldContent>
            <FieldLabel :for="field.path">
              Multi-factor authentication
            </FieldLabel>

            <FieldDescription>
              Enable multi-factor authentication to secure your account.
            </FieldDescription>

            <FieldError
              v-if="!field.isValid"
              :errors="field.errors"
            />
          </FieldContent>

          <Switch
            :id="field.path"
            v-model="field.model"
            :aria-invalid="!field.isValid"
            @blur="field.events.onBlur"
            @update:model-value="field.events.onChange"
          />
        </Field>
      </NotField>

      <!-- Array field -->
      <ArrayField
        v-slot="{ arrayField }"
        :array-field="form.arrayField('emails')"
      >
        <FieldSet :data-invalid="!arrayField.isValid">
          <FieldLegend variant="label">
            Email Addresses
          </FieldLegend>

          <FieldDescription>
            Add up to 5 email addresses where we can contact you.
          </FieldDescription>

          <FieldGroup class="gap-4">
            <NotField
              v-for="item in arrayField.items"
              :key="item.id"
              v-slot="{ field }"
              :field="item.field('address')"
            >
              <Field
                orientation="horizontal"
                :data-invalid="!field.isValid"
              >
                <FieldContent>
                  <InputGroup>
                    <InputGroupInput
                      :id="field.path"
                      v-model="field.model"
                      v-bind="field.events"
                      :aria-invalid="!field.isValid"
                      placeholder="name@example.com"
                      type="email"
                      autocomplete="email"
                    />

                    <InputGroupAddon
                      v-if="arrayField.items.length > 1"
                      align="inline-end"
                    >
                      <InputGroupButton
                        type="button"
                        variant="ghost"
                        size="icon-xs"
                        :disabled="item.index === 0"
                        :aria-label="`Move email ${item.index + 1} up`"
                        @click="arrayField.move(item.index, item.index - 1)"
                      >
                        <ChevronUp />
                      </InputGroupButton>

                      <InputGroupButton
                        type="button"
                        variant="ghost"
                        size="icon-xs"
                        :disabled="item.index === arrayField.items.length - 1"
                        :aria-label="`Move email ${item.index + 1} down`"
                        @click="arrayField.move(item.index, item.index + 1)"
                      >
                        <ChevronDown />
                      </InputGroupButton>

                      <InputGroupButton
                        type="button"
                        variant="ghost"
                        size="icon-xs"
                        :aria-label="`Remove email ${item.index + 1}`"
                        @click="arrayField.remove(item.index)"
                      >
                        <X />
                      </InputGroupButton>
                    </InputGroupAddon>
                  </InputGroup>

                  <FieldError
                    v-if="!field.isValid"
                    :errors="field.errors"
                  />
                </FieldContent>
              </Field>
            </NotField>

            <Button
              type="button"
              variant="outline"
              size="sm"
              :disabled="arrayField.items.length >= 5"
              @click="arrayField.append({ address: '' })"
            >
              Add Email Address
            </Button>
          </FieldGroup>

          <FieldError
            v-if="!arrayField.isValid"
            :errors="arrayField.errors"
          />
        </FieldSet>
      </ArrayField>

      <Field
        orientation="horizontal"
        class="*:flex-1"
      >
        <Button
          type="reset"
          variant="outline"
        >
          Reset
        </Button>

        <Button type="submit">
          Submit
        </Button>
      </Field>
    </FieldGroup>
  </Form>
</template>
```

</code-collapse>

## Related

- [Custom components](https://notformdocs.vercel.app/docs/integrations/custom-components)
- [Nuxt module aliases](https://notformdocs.vercel.app/docs/getting-started/nuxt-module#avoid-name-conflicts)

---

- **Page:** Agent skill
- **Source:** https://notformdocs.vercel.app/docs/ai/agent-skill
- **Description:** Install and use the NotForm agent skill, which routes AI coding assistants to the right documentation instead of answering from memory.

The NotForm agent skill is a small instruction file for AI coding assistants. It does **not** contain API documentation. Its job is to make the assistant look things up: identify your setup, find the relevant pages, read them, and only then write code.

## Why a skill instead of more docs

A copy of the API inside the skill would go stale and compete with these docs. The skill instead holds the part that does not change: where to look, in what order, and the few rules that assistants break most often. The documentation stays the single source of truth.

## Install

The skill lives in the NotForm repository at [`.agents/skills/notform/SKILL.md`](https://github.com/favorodera/notform/blob/main/.agents/skills/notform/SKILL.md). To use it in your project, copy the `notform` folder into the skills directory your tool reads.

```text
your-project/
└── .agents/
    └── skills/
        └── notform/
            └── SKILL.md
```

Some tools use a different folder. For example, Claude Code reads project skills from `.claude/skills/`. Check your tool's documentation for the location it expects, and place the `notform` folder there.

Commit the folder so everyone working on the project gets the same behavior.

You can also use the [`skills`](https://www.skills.sh/favorodera/notform/notform) CLI to install it. It supports more than 35 agents, including Cursor, Claude Code, Codex, Windsurf, and Cline.

## Use it

The skill activates when you ask an assistant to build, debug, or migrate a NotForm form. It is also user-invocable, so in tools that support slash commands you can run it by name:

```text
/notform
```

Then describe the task:

> Build a registration form with username, email, and a repeatable list of phone numbers. Show server errors under each field.

## What the skill makes the assistant do

1. **Identify your stack and version.** It checks whether the project uses `notform` (Vue) or `@notform/nuxt` (Nuxt), and which version.
2. **Handle v3 first.** If the project is on NotForm 3.x, it reads the [migration guide](https://notformdocs.vercel.app/docs/migrations/notform-v3) before anything else.
3. **Read the index.** It loads [`llms.txt`](https://notformdocs.vercel.app/docs/ai/llms-txt) to see which pages exist.
4. **Load only what the task needs.** It maps the task to pages, for example "validation or errors" to the [Validation](https://notformdocs.vercel.app/docs/guides/validation) and [Errors](https://notformdocs.vercel.app/docs/guides/errors) guides, and fetches those as Markdown.
5. **Write from the pages.** If something is not documented, it says so instead of inventing options.

## Rules the skill reinforces

These are the mistakes assistants make most, and each is explained in the docs.

- Create fields with `form.field(path)` and `form.arrayField(path)`, and pass the instance to `Field` or `ArrayField`. See [Field](https://notformdocs.vercel.app/docs/components/field).
- Bind `field.model` and spread `field.events`, with `v-model` first. See [Binding inputs](https://notformdocs.vercel.app/docs/guides/binding-inputs).
- Schema **input** is what users edit. Schema **output** is what `onSubmit` receives. See [Schema input and output](https://notformdocs.vercel.app/docs/guides/schema-input-output).
- Give `initialValues` for every bound field.
- Use `item.id` as an array key, and change arrays only through their methods. See [Array fields](https://notformdocs.vercel.app/docs/guides/array-fields).
- Writes through `field.model` and `form.setValue` do not validate.
- Field configuration is read once, when the field is created. See [Validation](https://notformdocs.vercel.app/docs/guides/validation#configure-a-field).
- NotForm should be the only owner of a form's state. Do not combine it with another form library on the same form.

## Example prompts

<table>
<thead>
  <tr>
    <th>
      Goal
    </th>
    
    <th>
      Prompt
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      New form
    </td>
    
    <td>
      "Create a checkout form with NotForm and Zod. Validate on blur and show errors with accessible markup."
    </td>
  </tr>
  
  <tr>
    <td>
      Integration
    </td>
    
    <td>
      "Wire this form to our ShadcnVue inputs. Handle the <code>
        Field
      </code>
      
       name conflict."
    </td>
  </tr>
  
  <tr>
    <td>
      Debugging
    </td>
    
    <td>
      "My error message never clears after I fix the input. Find out why using the NotForm docs."
    </td>
  </tr>
  
  <tr>
    <td>
      Migration
    </td>
    
    <td>
      "Migrate this component from NotForm v3 to v4."
    </td>
  </tr>
  
  <tr>
    <td>
      Review
    </td>
    
    <td>
      "Review this form against the NotForm docs and list anything that is guessed."
    </td>
  </tr>
</tbody>
</table>

## Limits

- The skill needs the assistant to be able to fetch URLs. Without network access, it asks you for the relevant pages instead of guessing.
- The skill is a router. If the docs and your installed package disagree, trust the package's public exports and tell the maintainers.

## Related

- [llms.txt and Markdown pages](https://notformdocs.vercel.app/docs/ai/llms-txt)
- [Working with AI](https://notformdocs.vercel.app/docs/ai/working-with-ai)