# Introduction

::note
NotForm is a lightweight form state and validation library built specifically for the Vue 3 Composition API.
::

NotForm handles the parts of a form that are tedious to build by hand — validation, dirty and touched tracking, per-field triggers, and array manipulation — while staying out of the way of your markup and styling.

Most of what NotForm does happens without opinions about your markup. `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} are fully renderless — they render nothing of their own, only exposing reactive state and event handlers through their default slot, so you decide entirely what markup represents a field. `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} do render something — a native `<form>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} element and a small error-message element, respectively — but neither ships any styling, and both let you substitute your own markup: `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} accepts native form attributes directly, and `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}'s `as`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} prop lets you swap in your own element or component.

## Why NotForm?

Building forms in Vue usually means choosing between:

- A UI library that dictates your markup and styling, or
- A validation library that requires a lot of boilerplate to wire into your components

NotForm tries to avoid both trade-offs. It only owns form *state* — values, errors, touched/dirty flags, and validation triggers — and leaves rendering entirely up to you.

::card-group
  :::app-card{icon="tabler:shield-check" title="Schema-agnostic Validation"}
  Drop in any Standard Schema compliant validator — Zod, Valibot, ArkType, and more. Swap libraries without touching your form logic.
  :::

  :::app-card{icon="tabler:pencil" title="Granular State Tracking"}
  Fields are compared against initial values on every keystroke. Touched and dirty states are managed automatically.
  :::

  :::app-card{icon="tabler:list" title="Dynamic Array Fields"}
  Append, prepend, insert, remove, swap, and move array items with stable keys that survive reorders.
  :::

  :::app-card{icon="tabler:braces" title="End-to-End Type Safety"}
  Field paths and their value types are strictly inferred from your schema. Invalid paths trigger compile-time errors.
  :::
::

## Why Standard Schema?

NotForm doesn't implement its own validation language. Rather than inventing another set of validation rules, it validates against any schema that implements the [Standard Schema](https://standardschema.dev){rel="&#x22;nofollow&#x22;"} interface.

A form library needs a consistent way to:

- validate values
- receive validation issues in a predictable shape
- support asynchronous validation, such as checking username availability against an API
- understand a schema's input and output types, since a schema can transform data on the way out (e.g. `z.coerce.number()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})

Standard Schema provides exactly that contract, so NotForm only ever talks to your validator through it. That means:

- The rest of the NotForm API — `form.values`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `form.errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `validate()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `submit()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, field paths, and so on — stays identical no matter which validator you choose.
- You can swap validators later without rewriting your forms.
- Your schema is never mutated or wrapped, so it stays reusable outside of NotForm too.

NotForm works with any Standard Schema-compatible validator, including:

::code-group
```ts [Zod]
import { z } from 'zod'

const schema = z.object({
  age: z.number().min(18, 'Must be 18 or older'),
  email: z.email('Invalid email'),
})
```

```ts [Valibot]
import {
  email,
  minValue,
  number,
  object,
  string,
} from 'valibot'

const schema = object({
  age: number([minValue(18, 'Must be 18 or older')]),
  email: string([email('Invalid email')]),
})
```

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

const schema = type({
  age: 'number>=18',
  email: 'email',
})
```
::

Pass your schema straight to [`useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://notformdocs.vercel.app/docs/composables/use-not-form) and the rest of the NotForm API — values, errors, submission, and field-level typing — is derived from it automatically.

## Next steps

Ready to dive in?

- Try the [Playground](https://notformdocs.vercel.app/playground) for a browser-based example.
- Or continue to [Installation](https://notformdocs.vercel.app/docs/getting-started/installation) to add NotForm to your project.


# Installation

NotForm is distributed as a single npm package, `notform`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, and can be used directly in any Vue 3 application — no build plugin, compiler macro, or bundler configuration required.

::note
If you are using Nuxt, skip ahead to the [Nuxt](https://notformdocs.vercel.app/#nuxt) section below and use the official [Nuxt Module](https://notformdocs.vercel.app/docs/getting-started/nuxt-module) instead of the manual steps here. It handles imports and setup for you.
::

## Install the package

NotForm validates values using [Standard Schema](https://standardschema.dev){rel="&#x22;nofollow&#x22;"} rather than a validation language of its own. This means NotForm doesn't ship a validator — you bring your own compatible library alongside it. Popular options include [Zod](https://zod.dev){rel="&#x22;nofollow&#x22;"}, [Valibot](https://valibot.dev){rel="&#x22;nofollow&#x22;"}, and [ArkType](https://arktype.io){rel="&#x22;nofollow&#x22;"}.

Pick one of these (this guide uses `zod`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} in its examples) and install it together with `notform`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} using your preferred package manager:

::code-group
```bash [pnpm]
pnpm add notform zod
```

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

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

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

::note
You can replace `zod`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} with another Standard Schema-compatible validation library if you prefer. Every code example in these docs uses `zod`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, but nothing about NotForm's API changes based on which validator you choose.
::

## Vue and Vite

NotForm is designed for Vue 3 and works with standard Vue applications out of the box — there is no application-level setup step, plugin installation, or provider component to configure before you can use it.

Once installed, import the components and composables you need directly from `notform`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}:

```vue [App.vue]
<script setup lang="ts">
import { NotField, NotForm, NotMessage, useNotForm } from 'notform'
import { z } from 'zod'

const schema = z.object({
  email: z.email('Invalid email'),
})

const form = useNotForm({
  onSubmit(values) {
    console.log('Form submitted:', values)
  },
  schema,
})
</script>

<template>
  <NotForm
    :form="form"
    @submit="form.submit"
  >
    <!-- form fields go here -->
  </NotForm>
</template>
```

NotForm follows the normal Vue component model: there is no global registration step, and nothing is installed as a Vue plugin. Import only the pieces you actually use — `useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} to create the form instance, `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} to provide it to your fields, and `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} / `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} / `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} for the fields themselves.

The full breakdown of this example — defining a schema, wiring up individual fields, and displaying validation messages — is covered step by step in [Quickstart](https://notformdocs.vercel.app/docs/getting-started/quickstart).

## Nuxt

For Nuxt applications, use the [Nuxt Module](https://notformdocs.vercel.app/docs/getting-started/nuxt-module) rather than manually installing and importing `notform`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} as shown above.

The module installs the package for you, registers every component and composable as a Nuxt auto-import, and wires up type support — so you can start writing `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and `useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} directly in your `.vue`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} files without an `import`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} statement.

## Next steps

NotForm is now installed and ready to use in your project.

Continue to [Quickstart](https://notformdocs.vercel.app/docs/getting-started/quickstart) to build your first form end-to-end: defining a schema, initializing the form, rendering fields, and displaying validation errors.


# Quickstart

This guide walks you through building a simple login form using the `useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} composable and NotForm's headless components.

::tip
Prefer experimenting in your browser with zero setup? You can test ideas directly in the [interactive Playground](https://notformdocs.vercel.app/playground).
::

Here is the login form we will be building. Try submitting the form empty, or typing an invalid email, to see the validation in action.

::code-preview
:demos-native-quickstart

#code
  :::code-collapse
  :docs-demo-code{file="native/quickstart"}
  :::
::

## Step-by-step

::steps{level="3"}
### Define the Schema

First, define your validation schema using a Standard Schema compliant library (this guide uses `zod`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}). The schema describes both fields the login form needs — `email`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `password`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} — along with the rules each must satisfy.

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

const schema = z.object({
  email: z.email('Enter a valid email'),
  password: z.string('Invalid input').min(8, 'At least 8 characters'),
})
```

This schema is the single source of truth for the form: it decides the shape of `form.values`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, drives which field paths are valid to use with `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, and produces the validation messages you'll render later with `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.

### Initialize the Form

Use the `useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} composable to create your form instance. Pass in the `schema`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} you just defined and an `onSubmit`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} handler that runs once validation succeeds.

```ts
const form = useNotForm({
  async onSubmit(data) {
    // `data` is fully typed as { email: string, password: string }
    console.log('Form submitted:', data)
  },
  schema,
})
```

`form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is the reactive object every other piece of this guide plugs into — `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} reads it for context, `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} reads and writes to `form.values`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, and `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} reads validation errors from it.

### Render the Form

Use the `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} component to wrap your form and pass it the `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} instance via the `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} prop. `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} renders a native `<form>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} element and automatically prevents the browser's default `submit`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `reset`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} behavior, so binding `@submit="form.submit"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `@reset="form.reset()"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is all you need — no `event.preventDefault()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} required.

```vue
<template>
  <NotForm
    :form="form"
    @submit="form.submit"
    @reset="form.reset()"
  >
    <!-- Fields will go here -->

    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      Submit
    </button>
  </NotForm>
</template>
```

### Connect the Fields

Wrap each input in a `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} component. Its default slot exposes two things you'll use on every field: `path`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, a stable string ID for that field (handy for `<label for>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, the input's `id`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, and `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}), and `events`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, a set of handlers that track interaction and trigger validation. Spread `events`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} onto the input with `v-bind`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} — by default this wires up validation on blur and on change, so errors appear once the user leaves the field or edits it, not on every keystroke.

Add both fields from the schema — `email`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `password`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} — the same way:

```vue
<template>
  <NotField
    v-slot="{ events, path }"
    path="email"
  >
    <div>
      <label :for="path">Email</label>

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

      <NotMessage :path="path" />
    </div>
  </NotField>

  <NotField
    v-slot="{ events, path }"
    path="password"
  >
    <div>
      <label :for="path">Password</label>

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

      <NotMessage :path="path" />
    </div>
  </NotField>
</template>
```

  :::note
  `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} automatically displays the first active validation error for the given `path`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, and renders nothing when that field has no errors — there's no need to write your own `v-if`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} around it.
  :::
::

## Putting it together

With both fields wired in place of the comment from the [**"Render the Form"**](https://notformdocs.vercel.app/docs/getting-started/quickstart#render-the-form) step, you have a complete, fully typed, validating login form: submitting with empty or invalid values shows inline errors, and submitting with valid values calls `onSubmit`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} with typed, validated data.

## Next Steps

To learn more about how NotForm integrates into your Vue applications, check out the [Components](https://notformdocs.vercel.app/docs/components/not-form) guide for the full API of `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, and `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, or deep dive into [Composables](https://notformdocs.vercel.app/docs/composables/use-not-form) to see everything `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} exposes beyond `submit`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `reset`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.


# Nuxt Module

`notform-nuxt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is the official Nuxt module for NotForm. It wraps the manual installation steps covered in [Installation](https://notformdocs.vercel.app/docs/getting-started/installation) into a single Nuxt module: instead of importing `useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, and `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} yourself in every file, the module registers them as Nuxt auto-imports, injects their types globally, and confirms they work correctly with Nuxt's SSR rendering — all with no extra configuration on your part.

::note
This page assumes you're building a Nuxt application. If you're using plain Vue or Vite instead, follow [Installation](https://notformdocs.vercel.app/docs/getting-started/installation) — `notform-nuxt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is Nuxt-only.
::

## Installation

The module is published to the official Nuxt Modules Registry, so it can be added with a single Nuxt CLI command rather than installing the package and editing `nuxt.config.ts`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} by hand:

::code-group
```bash [npx]
npx nuxi module add notform
```

```bash [pnpm]
pnpm dlx nuxi module add notform
```

```bash [bun]
bunx nuxi module add notform
```

```bash [yarn]
yarn dlx nuxi module add notform
```
::

::note
This command installs `notform-nuxt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and adds it to the `modules`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} array in your `nuxt.config.ts`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} automatically. It does not install a validation library for you — NotForm still validates through [Standard Schema](https://standardschema.dev){rel=""nofollow""}, so you need to add one yourself (e.g. `zod`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}), the same as in the manual [Installation](https://notformdocs.vercel.app/docs/getting-started/installation) guide.
::

::code-group
```bash [npm]
npm install zod
```

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

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

```bash [yarn]
yarn add zod
```
::

## Manual Setup

If you'd rather not use the Nuxt CLI — for example, in a monorepo where you manage `nuxt.config.ts`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} by hand, or in a restricted environment where `nuxi module add`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} can't reach the registry — you can install and register the module yourself.

Add the dependency:

::code-group
```bash [npm]
npm add notform-nuxt
```

```bash [pnpm]
pnpm add notform-nuxt
```

```bash [bun]
bun add notform-nuxt
```

```bash [yarn]
yarn add notform-nuxt
```
::

Then add it to your `nuxt.config.ts`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}:

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

This has the exact same effect as running the CLI command above — the module doesn't behave any differently depending on how it was registered.

## Features

### Auto-imports

Once the module is registered, every core component and composable is available globally in your `.vue`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} files, without an `import`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} statement.

Compare the manual setup from [Installation](https://notformdocs.vercel.app/docs/getting-started/installation):

```vue [WithoutModule.vue]
<script setup lang="ts">
import { NotField, NotForm, NotMessage, useNotForm } from 'notform'
import { z } from 'zod'

const form = useNotForm({ /* ... */ })
</script>
```

to the same file with `notform-nuxt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} installed:

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

const form = useNotForm({ /* ... */ })
</script>
```

`useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, and `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} are all resolved automatically — only your validation library still needs a manual import, since that's a separate package the module doesn't own.

### Type Safety

Auto-imported components and composables still carry their full generic types. `useNotForm<TSchema>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} infers `TSchema`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} from the schema you pass it exactly as it would with a manual import, so `form.values`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is typed to your schema's shape, and field `path`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} props are checked against it — all without a `types`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} array entry or a manual reference to the `notform`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} package in your project.

### Server-side Rendering (SSR)

NotForm works with Nuxt's SSR rendering: the form's initial state is computed consistently on both the server-rendered HTML and the client-side Vue instance that takes over from it, so values and validation state don't flash, reset, or mismatch during hydration.

## Next steps

The Nuxt module changes how NotForm's pieces are imported, but not how they're used. Continue to [Quickstart](https://notformdocs.vercel.app/docs/getting-started/quickstart) to build your first form — every example there works identically whether you installed NotForm manually or through this module, just without the `import`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} line for NotForm itself.


# Playground

::note
Ready to try it right away? Open the [interactive Playground](https://notformdocs.vercel.app/playground).
::

The NotForm Playground is a browser-based Vue 3 REPL for building small forms, experimenting with NotForm, and sharing reproducible examples without creating a local project.

## What's included

The default environment includes:

- Vue 3 with the Vue REPL's Monaco editor and TypeScript support
- NotForm core and Zod through the built-in import map
- The `NotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `NotField`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `NotArrayField`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `NotMessage`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, and `useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} APIs
- Tailwind CSS and shadcn-vue color tokens for quick styling in the live preview
- An editable import map for replacing browser-resolved dependencies
- Shareable state encoded in the URL, with the last local session restored when no shared state is present

The playground starts from a working form example with field validation, submission state, and a dynamic array field.

## Reproduce an issue

Use the playground when an issue can be reduced to a small Vue example:

1. Open the [Playground](https://notformdocs.vercel.app/playground).
2. Reduce the example until only the behavior needed to demonstrate the issue remains.
3. Click **Share** to copy the current playground URL.
4. Include that URL in the issue or pull request.

Because the editor state is part of the URL, the shared link opens the same files and configuration instead of relying on a separate repository or local setup.

::caution
A playground link should be a minimal reproduction. Keep secrets, private API keys, and production data out of examples you share.
::

## Test a pull request

NotForm publishes preview packages for pull requests through [`pkg.pr.new`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://github.com/stackblitz-labs/pkg.pr.new){rel="&#x22;nofollow&#x22;"}. That makes it possible to test a change in the browser before it is merged.

After the preview job finishes, copy the `pkg.pr.new`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} package URL from the pull request comment. For example:

```text
https://pkg.pr.new/notform@[pr-number]
```

The browser playground resolves packages through [`esm.sh`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://esm.sh){rel="&#x22;nofollow&#x22;"}, which supports `pkg.pr.new`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} packages through its `/pr/`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} URL form. Replace the playground's `notform`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} import-map entry with:

```text
https://esm.sh/pr/notform@[pr-number]?external=vue
```

Keep the playground's existing `vue`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} import-map entry unchanged. The `external=vue`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} query leaves Vue as a bare import so the preview package uses the same Vue runtime as the playground.

Then exercise the changed behavior, and share the resulting playground URL with the PR so the exact browser example can be reviewed.

::note
The playground is a manual/browser verification tool. It does not replace the project's Vitest suite, typecheck, lint, build, or other CI checks.
::

## What the playground does not provide

The REPL does not provide a full Node.js or Nuxt environment. Dependencies are resolved through the import map and browser-compatible CDNs, so server-only APIs, filesystem access, and package-manager workflows are outside its scope.

For repository-level changes, keep the source tests and local validation as the source of truth, and use the playground or the [Vue 3](https://stackblitz.com/edit/notform){external="" rel="&#x22;nofollow&#x22;"} and [Nuxt Module](https://stackblitz.com/edit/notform-nuxt){external="" rel="&#x22;nofollow&#x22;"} stackblitz templates when a visual or browser reproduction makes the behavior easier to verify.


# LLMs.txt

NotForm publishes documentation in formats designed for AI assistants. Use the index first, then fetch only the pages relevant to the task.

## Usage

For most requests, point the assistant at [`llms.txt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://notformdocs.vercel.app/llms.txt){external=""}. It lists the NotForm documentation sets and links to the raw Markdown for each page.

```text
https://notformdocs.vercel.app/llms.txt
```

Ask the assistant to follow the links for the APIs it needs. For example, a dynamic array form needs [`<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}](https://notformdocs.vercel.app/raw/docs/components/not-array-field.md){external=""} and [`useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://notformdocs.vercel.app/raw/docs/composables/use-not-form.md){external=""}.

Raw pages use this URL pattern:

```text
https://notformdocs.vercel.app/raw/docs/<section>/<page>.md
```

Focused pages are best when the request concerns one component, composable, or workflow. They keep the assistant's context relevant and make it easier to identify the authoritative API.

### Full Documentation Bundle

Use [`llms-full.txt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://notformdocs.vercel.app/llms-full.txt){external=""} when the assistant cannot follow links or the task spans installation, composables, components, and Nuxt integration.

::note
`llms-full.txt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is large. Prefer `llms.txt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} plus focused raw pages for a single form or component so the assistant does not process unrelated documentation.
::

## Prompt examples

- Focused component task

```text
Read https://notformdocs.vercel.app/llms.txt first. Then fetch the NotArrayField and useNotForm raw pages before implementing a dynamic list of email addresses. Use only the documented APIs and explain any assumption.
```

- Focused composable task

```text
Read https://notformdocs.vercel.app/raw/docs/composables/use-not-form.md before changing this form's validation or reset behavior. Match the existing API and do not invent options.
```

- Broad task

```text
Read https://notformdocs.vercel.app/llms-full.txt before configuring a Nuxt form with server errors, dynamic arrays, and custom field components.
```

## Recommended context flow

Give the assistant the application context after it has read the relevant NotForm pages. Include the schema, framework, package versions, current code, expected behavior, and exact error. Ask it to cite the NotForm page it used and distinguish documented behavior from assumptions.

Do not include credentials, private form submissions, production data, or private endpoints in a prompt or reproduction.


# Agent Skill

The NotForm Agent Skill helps AI coding assistants work with NotForm in Vue and Nuxt applications. It guides agents through setup, forms, components, validation, debugging, and integration, then points to focused references and published documentation for API details.

The skill provides workflow guidance. It complements the NotForm documentation and your project's tests, typechecking, and code review.

## Usage

The skill starts with a task map and links to the matching raw documentation. The intended flow is:

1. Load the relevant reference based on the task.
2. Fetch [`llms.txt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://notformdocs.vercel.app/llms.txt){external=""} or [`llms-full.txt`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://notformdocs.vercel.app/llms-full.txt){external=""} depending on the areas the task touches.
3. Fetch the focused raw page, such as [`<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}](https://notformdocs.vercel.app/raw/docs/components/not-field.md){external=""} or [`useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://notformdocs.vercel.app/raw/docs/composables/use-not-form.md){external=""}.
4. Implement against the documented API, then validate in the user's application.

::tip
Read [working-with-ai/llms-txt](https://notformdocs.vercel.app/docs/working-with-ai/llms-txt) for the full context-loading strategy.
::

### Install the skill

Use the [`skills`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://skills.sh){external="" rel="&#x22;nofollow&#x22;"} CLI to install NotForm's Agent Skill. It supports more than 35 agents, including Cursor, Claude Code, Codex, Windsurf, and Cline.

Run one of these commands in your project:

::code-group
```bash [npm]
npx skills add favorodera/notform
```

```bash [pnpm]
pnpm dlx skills add favorodera/notform
```

```bash [yarn]
yarn dlx skills add favorodera/notform
```

```bash [bun]
bunx skills add favorodera/notform
```
::


# NotForm

`<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} is the root component that wraps your form. It provides the form instance to all descendant field components via Vue's `provide`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}/`inject`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, so you don't need to pass a `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} prop to every `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} individually, and it wires up the native `submit`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `reset`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} events on your behalf.

::note
`<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} is a convenience, not a requirement. Every field component also accepts an explicit `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} prop, which takes priority over `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}'s context and is required if you render fields without a `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} ancestor at all.
::

Under the hood, `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} renders a native `<form>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} element, and it automatically:

- Prevents the browser's default full-page navigation on `submit`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and default field-clearing on `reset`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} — both would otherwise happen before any of your own logic runs, so this hands control back to you.
- Provides the `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} instance to descendant `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} components.

Because the underlying element is native, it does **not** clear validation errors or restore values by itself — that's what `form.reset()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} does. `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} only stops the browser from doing its own, separate reset first. This is why the usage example below still binds `@submit="form.submit"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `@reset="form.reset()"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} explicitly: `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} clears the way for those calls to run, but doesn't make them for you.

Because it's still a real `<form>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} element, other native behavior keeps working as expected:

- Native form attributes like `action`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `method`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, and `enctype`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} can be set directly on `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and pass through.
- Submitting with the keyboard (pressing Enter in a text field) and assistive technology both work the same as with a plain `<form>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.
- Native HTML validation attributes (`required`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `pattern`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `minlength`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, and so on) still trigger the browser's built-in validation UI alongside NotForm's own. If you only want NotForm's validation messages to show, add `novalidate`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} to suppress the browser's.

## Usage

A typical form setup involves passing a form instance to `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} via the `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} prop, then wrapping your fields in its default slot.

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

const schema = z.object({
  email: z.email('Invalid email'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
})

const form = useNotForm({
  onSubmit(values) {
    console.log('Form submitted:', values)
  },
  schema,
})
</script>

<template>
  <NotForm
    :form="form"
    @submit="form.submit"
    @reset="form.reset()"
  >
    <!-- Form fields go here -->
    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      Submit
    </button>

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

## API

### Props

::field-group
  :::field{required name="form" type="NotFormAPI<TSchema>"}
  Form instance provided to descendant field components.

  :br:br

  This is the same instance returned by [`useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://notformdocs.vercel.app/docs/composables/use-not-form). `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} makes it available to every `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} beneath it, without needing to repeat it as a prop on each one.
  :::
::

### Slots

#### `default`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

The default slot for housing your form fields.

```vue
<template>
  <NotForm
    :form="form"
    @submit="form.submit"
    @reset="form.reset()"
  >
    <!-- Form fields go here -->
  </NotForm>
</template>
```

::note
Unlike `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, this slot receives no slot props — there's no `v-slot`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} to bind here. `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} only provides the `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} instance to descendants via context; to read form-level state like `form.isSubmitting`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} or `form.isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} inside the slot, reference the `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} instance directly, as shown in the Usage example above.
::


# NotField

`<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} is a renderless component that connects an individual field to NotForm's validation and state management.

It provides the field's current state, validation errors, and event handlers that can be bound to native inputs or custom form components.

## Usage

A typical field combines the slot props with a form input and `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.

::code-preview
:demos-native-not-field

#code
  :::code-collapse
  :docs-demo-code{file="native/not-field"}
  :::
::

## API

### Props

::field-group
  :::field{required name="path" type="Paths<TSchema>"}
  Dot path of this field. It identifies the value managed by the field.

  :br:br

  Fields on a top-level property use a single property name:

  ```vue
  <template>
    <NotField path="email">
      ...
    </NotField>
  </template>
  ```

  Nested fields use dot notation:

  ```vue
  <template>
    <NotField path="user.email">
      ...
    </NotField>
  </template>
  ```

  The same path is exposed through the default slot and can be used for labels, IDs, messages, and other field-specific elements.
  :::

  :::field{name="form" type="NotFormAPI<TSchema>"}
  Form instance. Overrides `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} inject.

  :br:br

  By default, `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} uses the form instance provided by a surrounding `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.

  :br:br

  You can explicitly provide a form instance when needed:

  ```vue
  <template>
    <NotField
      v-slot="{ events }"
      :form="form"
      path="email"
    >
      <input v-bind="events">
    </NotField>
  </template>
  ```

  An explicit `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} takes priority over the form provided by a `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} ancestor.

  :br:br

  This is also required when using `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} as a standalone field outside of a `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.
  :::

  :::field{name="validateOn" type="Partial<Record<ValidationTrigger, boolean>>"}
  Validation triggers merged over defaults: `{ onBlur: true, onChange: true }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

  :br:br

  This allows individual validation triggers to be overridden for a field.

  :br:br

  Only the triggers you specify are overridden; all other trigger settings remain unchanged.

  ```vue
  <template>
    <NotField
      path="username"
      :validate-on="{ onInput: true }"
    />
  </template>
  ```

  For example, in addition to the defaults, the field above will additionally validate on input.

  :br:br

  `onMount`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is also a valid trigger, even though it has no corresponding entry in `events`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} below — there's no DOM event to bind for "the field just appeared," so instead it's opted into here and runs automatically once, when the field is created. This is useful for surfacing validation issues on a prefilled value without waiting for the user to interact with the field:

  ```vue
  <template>
    <NotField
      path="promoCode"
      :validate-on="{ onMount: true }"
    />
  </template>
  ```
  :::

  :::field{name="validationMode" type="'eager' | 'lazy'"}
  Controls how aggressively a field revalidates after it's been touched: `lazy`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} waits for the next blur or submit, `eager`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} also revalidates as the user types.

  :br:br

  Defaults to `eager`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

  :br:br

  In `eager`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} mode, once a field has an issue, it revalidates on every change/input event (subject to `validateOn`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `debounce`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}) so the error can clear as soon as the user fixes it. Until a field is invalid, change/input events are ignored — validation only starts once blur or submit produces the first issue.

  :br:br

  In `lazy`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} mode, validation only runs on blur and submit, no matter how many issues are present. This produces less noise for fields where feedback on every keystroke isn't wanted.

    ::::note
    `validateOn`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `validationMode`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} control different things: `validateOn`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} decides ***which*** interactions are allowed to trigger validation at all, while `validationMode`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} decides ***how often*** those allowed triggers actually fire once the field already has an issue. Setting `validateOn: { onInput: true }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} with `validationMode="lazy"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, for instance, still won't revalidate on every keystroke — `lazy`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} only revalidates on blur or submit regardless of which triggers `validateOn`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} allows.
    ::::

    ::::code-preview
    :demos-native-validation-modes

    #code
      :::::code-collapse
      :docs-demo-code{file="native/validation-modes"}
      :::::
    ::::
  :::

  :::field{name="debounce" type="number"}
  Delays input- and change-triggered validation until the user stops interacting with the field for the specified number of milliseconds.

  :br:br

  Omit or set to `0`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} to disable.

  :br:br

  This is particularly useful for asynchronous validation, where validating on every keystroke could result in excessive requests.

  ```vue
  <template>
    <NotField
      v-slot="{ events }"
      path="username"
      :debounce="400"
    >
      <input
        v-model="form.values.username"
        v-bind="events"
      >
    </NotField>
  </template>
  ```

    ::::note
    Blur and submit-triggered validation are always run immediately and are never delayed by `debounce`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.
    ::::
  :::
::

### Slots

#### `default`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

The default slot receives the complete field state and event handlers.

```vue
<template>
  <NotField
    v-slot="slotProps"
    path="email"
  >
    ...
  </NotField>
</template>
```

::field-group
  :::field{name="path" type="string"}
  Dot path of this field.

  :br:br

  Useful for labels, inputs, IDs, messages, and other field-specific elements.

  ```vue
  <template>
    <NotField
      v-slot="{ path }"
      path="email"
    >
      <label :for="path">Email</label>

      <input :id="path">
    </NotField>
  </template>
  ```
  :::

  :::field{name="errors" type="Array<Issue>"}
  Validation issues for this field path.

  :br:br

  It contains all validation issues reported for the field during the most recent validation run.

  ```vue
  <template>
    <NotField
      v-slot="{ errors }"
      path="email"
    >
      <input v-model="form.values.email">

      <ul v-if="errors.length > 0">
        <li
          v-for="error in errors"
          :key="error.message"
        >
          {{ error.message }}
        </li>
      </ul>
    </NotField>
  </template>
  ```
  :::

  :::field{name="isValid" type="boolean"}
  Whether this field has no issues.

  :br:br

  It is `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} if the field has no issues and `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} otherwise.

  ```vue
  <template>
    <NotField
      v-slot="{ isValid }"
      path="email"
    >
      <span v-if="isValid">Valid</span>
    </NotField>
  </template>
  ```
  :::

  :::field{name="isTouched" type="boolean"}
  Whether the user has interacted with this field.

  :br:br

  This can be useful for displaying validation feedback only after the user has interacted with the field:

  ```vue
  <template>
    <NotField
      v-slot="{ isTouched, isValid, events }"
      path="email"
    >
      <input
        v-model="form.values.email"
        v-bind="events"
      >

      <p v-if="isTouched && !isValid">
        Please enter a valid email address.
      </p>
    </NotField>
  </template>
  ```
  :::

  :::field{name="isDirty" type="boolean"}
  Whether the value differs from the baseline.

  ```vue
  <template>
    <NotField
      v-slot="{ isDirty }"
      path="email"
    >
      <span v-if="isDirty">Unsaved changes</span>
    </NotField>
  </template>
  ```
  :::

  :::field{name="isValidating" type="boolean"}
  Whether this field is currently validating.

  ```vue
  <template>
    <NotField
      v-slot="{ isValidating }"
      path="username"
    >
      <span v-if="isValidating">
        Checking username...
      </span>
    </NotField>
  </template>
  ```
  :::

  :::field
  ---
  name: events
  type: Record<ExcludeStrict<ValidationTrigger, 'onMount'>, () => void>
  ---
  Handlers to bind to the input.

  :br:br

  These handlers are used to track field interaction and trigger validation.

  :br:br

  `onMount`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is excluded here even though it's a valid `validateOn`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} trigger — see the note on `validateOn`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} above for why.

  - **Binding all events:**

  For native inputs, the simplest approach is to spread the handlers:

  ```vue
  <template>
    <NotField
      v-slot="{ events, path }"
      path="email"
    >
      <label :for="path">Email</label>

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

  - **Binding individual events:**

  For custom components, bind the relevant handlers individually:

  ```vue
  <template>
    <NotField
      v-slot="{ events }"
      path="country"
    >
      <CustomCombobox
        @focusout="events.onBlur"
        @pick="events.onChange"
      />
    </NotField>
  </template>
  ```

    ::::note
    The handlers don't require the original DOM event as an argument. They simply notify `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} that the corresponding interaction occurred.
    ::::
  :::
::


# NotMessage

`<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} is a component for displaying the validation error message for a specific field.

It automatically displays the first active validation error for the field and renders nothing when the field has no validation errors.

::note
Unlike `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}, `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} is not renderless — by default it renders a `<span>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} element containing the error text, and it can be swapped for a different element or component with the `as`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} prop, covered below.

:br:br

**"Renders nothing when there are no errors"** is literal here: the wrapping element itself is not rendered at all while the field has no active error, rather than being rendered empty. There's nothing in the DOM to select or style until there's a message to show.
::

## Usage

The most common usage is alongside a `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}:

```vue
<template>
  <NotField
    v-slot="{ events, path }"
    path="email"
  >
    <label :for="path">Email</label>

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

    <NotMessage :path="path" />
  </NotField>
</template>
```

::tip
When validation fails, `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} displays the first validation error associated with the `email`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} field, and nothing when there are no active validation errors.
::

### Displaying Multiple Errors

`<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} intentionally displays only the first active validation error.

If you need to display every validation issue for a field, use the field's `errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} slot prop instead:

```vue
<template>
  <NotField
    v-slot="{ events, path, errors }"
    path="email"
  >
    <input
      :id="path"
      v-model="form.values.email"
      v-bind="events"
      type="email"
    >

    <div v-if="errors.length > 0">
      <p
        v-for="(error, index) in errors"
        :key="index"
      >
        {{ error.message }}
      </p>
    </div>
  </NotField>
</template>
```

This gives you the complete list of validation issues instead of only the first message.

## API

### Props

::field-group
  :::field{required name="path" type="Paths<TSchema>"}
  Field path whose first error message is shown.

  :br:br

  It supports the same dot-separated paths used by `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}:

  ```vue
  <template>
    <NotMessage path="email" />
  </template>
  ```

  For nested fields:

  ```vue
  <template>
    <NotMessage path="user.email" />
  </template>
  ```
  :::

  :::field{name="form" type="NotFormAPI<TSchema>"}
  Form instance. Overrides `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} inject.

  :br:br

  By default, `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} uses the form instance provided by a surrounding `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.

  :br:br

  You can explicitly provide a form instance when needed:

  ```vue
  <template>
    <NotMessage
      :form="form"
      path="email"
    />
  </template>
  ```

  An explicit `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} takes priority over the form provided by a `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} ancestor.

  :br:br

  This is also required when using `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} as a standalone component outside of a `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.
  :::

  :::field{name="as" type="Component | string"}
  Root element or component used to render the message. Defaults to `'span'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

  :br:br

  Pass a string tag name to change the rendered element:

  ```vue
  <template>
    <NotMessage
      path="email"
      as="p"
    />
  </template>
  ```

  Or pass a component — useful when your application already has a shared component for validation messages:

  ```vue
  <template>
    <NotMessage
      path="email"
      :as="ErrorMessage"
    />
  </template>
  ```

    ::::caution
    When `as`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is a component, the message is passed as **default slot content**, not as a prop. `ErrorMessage`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} in the example above must render its own default `<slot />`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} for the message text to appear — a component that instead expects something like a `message`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} prop will render with no visible text. If you need to reshape the message before it reaches a component like that, use the `default`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} slot documented below instead of `as`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} directly.
    ::::
  :::
::

::note
Any attribute passed to `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} that isn't `path`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, or `as`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is forwarded to the rendered element — the same way native HTML attributes fall through on any Vue component. This is how you'd attach a `class`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, an `id`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, or a `data-*`{lang="text"} attribute for styling:

```vue
<template>
  <NotMessage
    path="email"
    class="text-sm text-red-500"
  />
</template>
```
::

### Slots

#### `default`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

The default slot receives the current error message.

```vue
<template>
  <NotMessage
    v-slot="slotProps"
    path="email"
  >
    ...
  </NotMessage>
</template>
```

::field-group
  :::field{name="message" type="string | undefined"}
  The first active error message for the specified field.

  :br:br

  If no error is present for the field, this value is `undefined`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

  ```vue
  <template>
    <NotMessage
      v-slot="{ message }"
      path="email"
    >
      <span>{{ message }}</span>
    </NotMessage>
  </template>
  ```

    ::::tip
    Because `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} already renders nothing when there's no error, you don't need to guard against `message`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} being `undefined`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} yourself — the slot's content only ever renders while there's a message to show.
    ::::

  Even so, using the slot is useful when you want control over the surrounding markup — for example, adding an icon or custom classes, rather than the plain text `<NotMessage>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} renders by default:

  ```vue
  <template>
    <NotField
      v-slot="{ events, path }"
      path="email"
    >
      <input
        :id="path"
        v-model="form.values.email"
        v-bind="events"
        type="email"
      >

      <NotMessage
        v-slot="{ message }"
        :path="path"
        as="p"
      >
        <span class="flex items-center gap-2">
          <Icon name="tabler:alert-circle" />
          {{ message }}
        </span>
      </NotMessage>
    </NotField>
    /template>
  </template>
  ```
  :::
::


# NotArrayField

`<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} is a renderless component for working with array fields in a form.

It provides the current array items, stable keys and field paths for rendering nested fields, validation state, and methods for adding, removing, updating, inserting, swapping, and moving items.

## Usage

::code-preview
:demos-native-not-array-field

#code
  :::code-collapse
  :docs-demo-code{file="native/not-array-field"}
  :::
::

::caution
Do not use the array index as the key for managing array items:

```vue
<template>
  <NotArrayField
    v-slot="{ items }"
    path="todos"
  >
    <!-- Correct -->
    <NotField
      v-for="item in items"
      :key="item.key"
    >
      ...
    </NotField>

    <!-- Avoid -->
    <NotField
      v-for="item, index in items"
      :key="index"
    >
      ...
    </NotField>
  </NotArrayField>
</template>
```
::

::caution
Always change the array through the slot's mutation methods (`append`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `prepend`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `insert`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `remove`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `swap`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `move`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}), rather than mutating `form.values`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} directly with methods like `.push()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} or `.splice()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}. Each item's stable `key`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is tracked separately from the array's values, and only the mutation methods keep that tracking in sync with structural changes like inserting or removing an item in the middle of the array. A direct mutation still updates the values, but can leave items with the wrong identity, which defeats the purpose of using `item.key`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} in the first place.
::

## API

### Props

::field-group
  :::field{required name="path" type="Paths<TSchema>"}
  Dot path of the array field. It identifies the value managed by `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.

  ```vue
  <template>
    <NotArrayField path="todos">
      ...
    </NotArrayField>
  </template>
  ```

  For nested arrays use dot notation:

  ```vue
  <template>
    <NotArrayField path="user.todos">
      ...
    </NotArrayField>
  </template>
  ```

  The same path is exposed through the default slot and can be used for labels, IDs, messages, and other field-specific elements.
  :::

  :::field{name="form" type="NotFormAPI<TSchema>"}
  Form instance. Overrides `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} inject.

  :br:br

  By default, `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} uses the form instance provided by a surrounding `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.

  :br:br

  You can explicitly provide a form instance when needed:

  ```vue
  <template>
    <NotArrayField
      :form="form"
      path="todos"
    >
      ...
    </NotArrayField>
  </template>
  ```

  An explicit `form`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} takes priority over the form provided by a `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} ancestor.

  :br:br

  This is also required when using `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} as a standalone component outside of a `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.
  :::

  :::field{name="itemSchema" type="TItemSchema"}
  The schema for an array item.

  :br:br

  It is used for type inference only — it is never read at runtime — so that array mutation methods such as `append`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `prepend`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `insert`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, and `update`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} receive the correct types for the values you pass them. It does not itself validate items; validation of array items still happens through the form's main `schema`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, the same as any other field.
  :::
::

### Slots

#### `default`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

The default slot receives the full array state and all available array operations.

```vue
<template>
  <NotArrayField
    v-slot="slotProps"
    path="todos"
  >
    ...
  </NotArrayField>
</template>
```

::field-group
  :::field{name="path" type="string"}
  Dot path of this array field.

  :br:br

  Useful for labels, inputs, IDs, messages, and other field-specific elements.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ path }"
      path="todos"
    >
      <NotMessage :path="path" />
    </NotArrayField>
  </template>
  ```
  :::

  :::field{name="errors" type="Array<Issue>"}
  Validation issues reported directly against the array field's own path.

  :br:br

  It contains all validation issues reported for the array field itself during the most recent validation run — for example, from a `.min()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} or `.max()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} rule on the array as a whole.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ errors }"
      path="todos"
    >
      <input v-model="form.values.todos">

      <ul v-if="errors.length > 0">
        <li
          v-for="error in errors"
          :key="error.message"
        >
          {{ error.message }}
        </li>
      </ul>
    </NotArrayField>
  </template>
  ```

    ::::caution
    `errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} does **not** include issues from individual items — only issues attached to the array field's own path. An item that fails validation (for example, an empty required tag) makes `isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, but does not add anything to this array. To show an individual item's own issues, read `errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} from a `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} or nested `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} scoped to that item's `path`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, as shown in the demo.
    ::::
  :::

  :::field{name="isValid" type="boolean"}
  Whether the array field's own path, and every path nested underneath it, have no issues.

  :br:br

  It is `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} if the array field's own `errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} are empty **and** no issue exists anywhere nested inside the array — an item's own value, a field inside an object item, or an item inside a nested array of its own, at any depth. Unlike `errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} above, this fully recurses.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ isValid }"
      path="todos"
    >
      <span v-if="isValid">Valid</span>
    </NotArrayField>
  </template>
  ```

    ::::tip
    This recursion is genuinely unlimited depth, not just one level. For a `groups`{lang="text"} array where each group has its own nested `name`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `tags`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} array — the pattern from [Nested Arrays](https://notformdocs.vercel.app/#nested-arrays) below — an issue on `groups.0.name`{lang="text"} *or* `groups.0.tags.1`{lang="text"} both make the outer `groups`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} field's `isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, and both also make an inner `<NotArrayField path="groups.0.tags">`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}'s own `isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} where applicable. `errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} on either field, however, always stays empty for a nested issue — only `isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} (and `isTouched`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}/`isDirty`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}/`isValidating`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} below) roll up.
    ::::
  :::

  :::field{name="isTouched" type="boolean"}
  Whether the array field's own path, or any path nested underneath it, has been touched.

  :br:br

  Recurses to any depth, the same way as `isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} above.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ isTouched, isValid }"
      path="tags"
    >
      <p v-if="isTouched && !isValid">
        Please enter valid tags.
      </p>
    </NotArrayField>
  </template>
  ```
  :::

  :::field{name="isDirty" type="boolean"}
  Whether the array field's own path, or any path nested underneath it, differs from the baseline. Recurses to any depth, the same way as `isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} above.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ isDirty }"
      path="todos"
    >
      <span v-if="isDirty">Unsaved changes</span>
    </NotArrayField>
  </template>
  ```
  :::

  :::field{name="isValidating" type="boolean"}
  Whether the array field's own path, or any path nested underneath it, is currently validating. Recurses to any depth, the same way as `isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} above.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ isValidating }"
      path="skills"
    >
      <span v-if="isValidating">
        Checking skills...
      </span>
    </NotArrayField>
  </template>
  ```
  :::

  :::field{name="items" type="Array<NotArrayFieldItem<TSchema>>"}
  Contains metadata for every item in the array.

  :br:br

  Each item has:

    ::::field-group
      :::::field{name="key" type="string"}
      A stable identity for `v-for`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} `:key`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} that remains the same even if the item's position changes.
      :::::

      :::::field{name="path" type="string"}
      The dot path of this item at its **current** index.
      :::::

      :::::field{name="index" type="number"}
      The item's current position in the array.
      :::::
    ::::

    ::::note
    The `key`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} remains stable when items are reordered, while `index`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `path`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} change with the item's current position — as long as the array is only changed through the slot's mutation methods. See the caution above.
    ::::
  :::

  :::field{name="append" type="(value: InferInput<TItemSchema>) => void"}
  Appends a value to the end of the array.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ append }"
      path="items"
    >
      <button
        type="button"
        @click="append({ name: 'New Item' })"
      >
        Add Item
      </button>
    </NotArrayField>
  </template>
  ```
  :::

  :::field{name="prepend" type="(value: InferInput<TItemSchema>) => void"}
  Inserts a value at the beginning of the array, shifting every existing item's touched, dirty, and error state — at any depth underneath that item — forward by one position along with it.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ prepend }"
      path="items"
    >
      <button
        type="button"
        @click="prepend({ name: 'New Item' })"
      >
        Add to Start
      </button>
    </NotArrayField>
  </template>
  ```
  :::

  :::field
  ---
  name: insert
  type: "(index: number, value: InferInput<TItemSchema>) => void"
  ---
  Inserts a value at the specified index, shifting later items — and their touched, dirty, and error state, at any depth underneath them — back by one position.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ insert }"
      path="items"
    >
      <button
        type="button"
        @click="insert(2, { name: 'Inserted Item' })"
      >
        Insert at index 2
      </button>
    </NotArrayField>
  </template>
  ```
  :::

  :::field{name="remove" type="(index: number) => void"}
  Removes the item at the specified index from the array.

  :br:br

  Its touched, dirty, and error state — at any depth underneath that item — is discarded along with it, rather than passed to whichever item ends up at that index afterward. Every later item's own state shifts back by one position to follow it to its new index.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ remove }"
      path="items"
    >
      <button
        type="button"
        @click="remove(1)"
      >
        Remove item at index 1
      </button>
    </NotArrayField>
  </template>
  ```
  :::

  :::field
  ---
  name: update
  type: "(index: number, value: InferInput<TItemSchema>) => void"
  ---
  Replaces the item at the specified index with a new value without changing its key.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ update }"
      path="items"
    >
      <button
        type="button"
        @click="update(1, { name: 'Updated Item' })"
      >
        Update item at index 1
      </button>
    </NotArrayField>
  </template>
  ```
  :::

  :::field{name="swap" type="(indexA: number, indexB: number) => void"}
  Swaps the positions of two items in the array, moving keys and form state — at any depth underneath each item — with them.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ swap }"
      path="items"
    >
      <button
        type="button"
        @click="swap(0, 1)"
      >
        Swap items at index 0 and 1
      </button>
    </NotArrayField>
  </template>
  ```
  :::

  :::field{name="move" type="(from: number, to: number) => void"}
  Moves an item from one index to another, shifting the items in between and moving keys and form state — at any depth underneath each item — with them.

  ```vue
  <template>
    <NotArrayField
      v-slot="{ move }"
      path="items"
    >
      <button
        type="button"
        @click="move(0, 2)"
      >
        Move item from index 0 to 2
      </button>
    </NotArrayField>
  </template>
  ```
  :::
::


# useNotForm

`useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is the core composable for creating and managing a NotForm instance.

It connects a Standard Schema-compatible validator to a deeply reactive form state and provides everything needed to manage values, validation, field interaction, errors, submission, and reset behavior.

The returned form instance can be used directly or provided to [`<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://notformdocs.vercel.app/docs/components/not-form) for use by descendant field components.

## API

### Signature

```ts
function useNotForm<TSchema extends ObjectSchema>(
  config: UseNotFormConfig<TSchema>
): NotFormAPI<TSchema>
```

### Parameters

::field-group
  :::field{required name="config" type="UseNotFormConfig<TSchema>"}
  Schema, initial values/errors, and submit handler configuration.

  :br:br
  The configuration options are:

    ::::field-group
      :::::field{required name="schema" type="MaybeRefOrGetter<TSchema>"}
      Schema used to parse and validate values.

      :br:br

      It can be provided directly, as a ref to a schema or as a function that returns a schema.

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

      const schema = z.object({
        email: z.email(),
      })

      const form = useNotForm({
        schema,
      })
      ```

        ::::::caution
        The schema must be Standard Schema compatible whose input is an object.
        ::::::
      :::::

      :::::field{name="initialValues" type="DeepPartial<InferInput<TSchema>>"}
      Starting or initial values for the form.

      :br:br

      The supplied values become the form's initial baseline for form values and are used for:

      - populating `form.values`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
      - dirty state comparisons
      - `form.reset()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

      ```ts
      const form = useNotForm({
        schema,
        initialValues: {
          email: 'user@example.com',
          profile: {
            name: 'Jane',
          },
        },
      })
      ```

        ::::::note
        When `initialValues`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is omitted, the form starts from an empty object.
        ::::::
      :::::

      :::::field{name="initialErrors" type="Array<Issue>"}
      Issues shown before the first validation run.

      :br:br

      This is useful when a form needs to start with errors returned from another source, such as previously persisted validation state.

      :br:br

      The supplied values become the form's initial baseline for validation errors and are used for:

      - populating `form.errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
      - dirty state comparisons
      - `form.reset()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

      ```ts
      const form = useNotForm({
        schema,
        initialValues: {
          email: 'user@example.com',
        },
        initialErrors: [{ message: 'Email already taken', path: 'email' }],
      })
      ```

        ::::::note
        When `initialErrors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is omitted, the form starts with no issues.
        ::::::
      :::::

      :::::field
      ---
      name: onSubmit
      type: "(data: InferOutput<TSchema>) => Promise<void> | void"
      ---
      Callback function that is called after a successful submit validation.

      ```ts
      const form = useNotForm({
        schema,
        initialValues: {
          email: 'user@example.com',
        },
        onSubmit(values) {
          console.log(values)
        },
      })
      ```
      :::::
    ::::
  :::
::

### Return Value

`useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} returns a `NotFormAPI<TSchema>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} object, which is a reactive form instance with the following properties:

::field-group
  :::field{name="errors" type="Array<Issue>"}
  Issues from the last validation that wrote errors.

  :br:br

  Each issue contains the path and message supplied by the validation schema.
  :::

  :::field{name="getFieldErrors" type="(path: Paths<TSchema>) => Array<Issue>"}
  Returns all active validation issues whose path exactly equals `path`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} — not issues nested underneath it. `getFieldErrors('groups.0')`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} won't include an issue reported at `groups.0.name`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}. See [NotArrayField](https://notformdocs.vercel.app/docs/components/not-array-field) for how `isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} accounts for that instead, by aggregating recursively rather than doing an exact match.
  :::

  :::field{name="isDirty" type="boolean"}
  Indicates if the form values have been changed since the form was initialized.

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

  :::field{name="isSubmitting" type="boolean"}
  Indicates if the form is currently submitting.

  ```vue
  <template>
    <button
      type="submit"
      :disabled="form.isSubmitting"
    >
      {{ form.isSubmitting ? 'Submitting...' : 'Submit' }}
    </button>
  </template>
  ```
  :::

  :::field{name="isTouched" type="boolean"}
  Indicates if any form field has been touched.

  ```vue
  <template>
    <div>
      <p v-if="form.isTouched">
        You have interacted with at least one field.
      </p>
    </div>
  </template>
  ```
  :::

  :::field{name="isValid" type="boolean"}
  Indicates if the form currently has no active validation errors.

  ```vue
  <template>
    <button
      type="submit"
      :disabled="!form.isValid"
    >
      Submit
    </button>
  </template>
  ```

    ::::note
    `isValid`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is based on the current `errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} collection. It does not independently execute validation.
    ::::
  :::

  :::field{name="isValidating" type="boolean"}
  Indicates if the form is currently being validated.

  ```vue
  <template>
    <div>
      <p v-if="form.isValidating">
        Validating...
      </p>
    </div>
  </template>
  ```
  :::

  :::field
  ---
  name: reset
  type: "(values?: DeepPartial<InferInput<TSchema>>, errors?: Array<Issue>) => void"
  ---
  Restores values/errors to the baseline. Optional arguments become the new baseline.

  :br:br

  This also resets the dirty, validation, and touch states.

  - **Reset with new values:**

  ```ts
  form.reset({
    email: 'jane@example.com',
    name: 'Jane',
  })
  ```

  - **Reset with new errors:**

  ```ts
  form.reset(
    undefined,
    [
      {
        message: 'Email requires verification.',
        path: ['email'],
      },
    ]
  )
  ```

  - **Reset with both new values and errors:**

  ```ts
  form.reset(
    {
      email: 'jane@example.com',
      name: 'Jane',
    },
    [
      {
        message: 'Email requires verification.',
        path: ['email'],
      },
    ]
  )
  ```

  - **Reset without new values and errors:**

  ```ts
  form.reset()
  ```

    ::::note
    Calling `form.reset()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} restores the form to its current baseline. If that baseline has since been updated, `reset()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} restores to the updated values and errors. Otherwise, it falls back to the original `initialValues`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `initialErrors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, or to an empty state if neither was provided.
    ::::

    ::::caution
    Passing `values`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}/`errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} fully **replaces** the previous baseline — it isn't merged with it. Any key present in the old baseline but missing from the new `values`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is simply gone afterward, the same way `initialValues`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} passed to `useNotForm`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} becomes the literal starting shape rather than a set of defaults layered under something else.
    ::::
  :::

  :::field{name="setError" type="(error: Issue) => void"}
  Upserts an issue at the same path, or appends it.

  :br:br

  Use this when you need to manually manage validation issues for a field, for example, after a server-side validation.

    ::::code-preview
    :demos-native-server-errors

    #code
      :::::code-collapse
      :docs-demo-code{file="native/server-errors"}
      :::::
    ::::
  :::

  :::field
  ---
  name: setValue
  type: "<TPath extends Paths<TSchema>>(path: TPath, value:
    Get<InferInput<TSchema>, TPath, { strict: false }>) => void"
  ---
  Sets a field value by path.

  :br:br

  Use this when you need to manually set the value of a field, for example, after a server-side update or custom inputs.

  ```ts
  form.setValue('email', 'jane@example.com')
  ```

    ::::note
    Calling `setValue()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} updates the field's value and recomputes `isDirty`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} by comparing the new value against the current baseline.
    ::::

    ::::caution
    `setValue()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} does not trigger validation on its own. Validation still runs only through the field's configured interaction handlers (e.g. `onChange`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `onBlur`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}), so call `validate()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} manually if you need to validate right after a programmatic `setValue()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} call.
    ::::
  :::

  :::field{name="submit" type="(event?: SubmitEvent) => Promise<void>"}
  Marks all fields as touched and dirty, validates the complete form, then runs `onSubmit`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} when valid.

  :br:br

  - **Bind it directly to `<NotForm>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}**:

  ```vue
  <template>
    <NotForm
      :form="form"
      @submit="form.submit"
    >
      <input v-model="form.values.email">

      <button
        type="submit"
        :disabled="form.isSubmitting"
      >
        {{ form.isSubmitting ? 'Submitting...' : 'Submit' }}
      </button>
    </NotForm>
  </template>
  ```

  - **Or call programmatically:**

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

    ::::note
    When called with an `event`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `event.preventDefault()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is called immediately — before checking whether a submission is already in flight, and before validation runs. This is why binding `@submit="form.submit"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} is enough on its own to stop the browser's default full-page submission; see [NotForm](https://notformdocs.vercel.app/docs/components/not-form) for the full distinction between how `submit`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and `reset`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} are each prevented.
    ::::

    ::::note
    If no `onSubmit`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} callback was provided, the form still runs validation on submit but has no callback to execute when it succeeds.
    ::::
  :::

  :::field
  ---
  name: validate
  type: () => Promise<StandardSchemaV1.Result<InferOutput<TSchema>>>
  ---
  Validates the entire form against the current schema.

  :br:br

  On success, the form's errors are cleared and the schema's validated (typed) output is returned. On failure, the returned result contains the validation issues, and those same issues replace the form's current errors.

    ::::note
    Concurrent calls are last-write-wins: each call still resolves with its own result, but only the most recently started call gets to write its issues to `form.errors`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} — an older call that resolves later has its result silently discarded from shared state.
    ::::
  :::

  :::field
  ---
  name: validateField
  type: "(path: Paths<TSchema>) =>
    Promise<StandardSchemaV1.Result<InferOutput<TSchema>>>"
  ---
  Validates a specific field against the current schema.

  :br:br

  On success, the field's validated (typed) output is returned. On failure, the returned result contains the validation issues, and those same issues are added to the form's current errors.

  :br:br

  `path`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} can be any granularity — a leaf field, an entire array field, or a specific item inside one. This is useful when building custom inputs that need to validate themselves without validating the entire form; `<NotField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} and `<NotArrayField>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} both call this internally with their own `path`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.
  :::

  :::field{name="values" type="InferInput<TSchema>"}
  Deeply reactive object containing the live form values.

  :br:br

  It can be accessed directly:

  ```ts
  console.log(form.values.email)
  ```

  Or used for two-way binding with v-model:

  ```vue
  <template>
    <input v-model="form.values.email">
  </template>
  ```

  ```vue
  <template>
    <input v-model="form.values.address.city">
  </template>
  ```
  :::
::