# Attaform documentation

> The full text of every Attaform documentation page, concatenated for AI agents. Regenerated from the docs on every build. The curated index lives at https://attaform.dev/llms.txt.

---

# Introduction

> One Zod schema, one Attaform, one source of truth.

Attaform reads a Zod schema and hands back the form, ready to play: reactive `values`, per-field `errors`, a `meta` aggregate, and a `v-register` directive that binds every native input shape. **Your schema is the form.** The schema is the validator. The schema is the API contract.

Type-safe end to end. Errors surface at compile time, and the runtime keeps every value matched to what your schema declared. Server errors flow back through the same reactive surface, persistence opts in per field, SSR hydrates without flashes, and the panel inside Nuxt DevTools shows every form on the page.

## How these docs read

The sidebar walks top to bottom as a learning narrative: install, schema, bind, validate, submit, persist. Drop in anywhere. Every concept is its own URL, its own definition, its own demo.

If you're new, start with the [Quick start](/docs/getting-started/quick-start). If you want our philosophy first, read [Why Attaform](/docs/getting-started/why-attaform); if you want the receipts, [Benchmarks](/docs/comparison/benchmarks) measures Attaform against the Vue form-library field in a real browser. If you're hunting a specific surface, the sidebar's last category, **Reference**, is alphabetical and indexed.

Reading with a coding assistant? These docs are machine-readable too. Point it at [`llms.txt`](/llms.txt) for the whole index, or install the [Agent Skill](/docs/reference/ai-agents) so it writes idiomatic Attaform from the first try. The [AI agents](/docs/reference/ai-agents) page lays out every option.

_Source: https://attaform.dev/docs/getting-started/introduction_

---

# Why Attaform

> Five marks of a great form library. Attaform's North star, top to bottom.

Forms look simple from the outside. Inside, they're a thicket of subtle details: blank-value tracking, persistence, sensitive-name protection, SSR, async validation, nested objects and discriminated unions, efficient DOM tracking, errors flowing from validators and your server into one reactive form API. A great library handles every one for you, without making you reach for the type plumbing or wire up the side-channels yourself.

These five convictions guide Attaform's design:

1. **Telepathically accurate type safety.** Types flow from your schema into every surface: values, errors, paths, write shapes, etc. We don't do `any`.
2. **A tiny, predictable API that just works.** Small surface, no surprises. If you can't learn the core API in five minutes, it's not good enough.
3. **Stays out of your markup.** One directive, `v-register`, does the heavy lifting. Your `<input>` stays a native `<input>`; nothing sits between the DOM and the form.
4. **Vue conventions, end to end.** Composables, reactivity, directives: the shapes you already know.
5. **The schema drives everything.** Data shape, defaults, validation, errors, and types. All from one Zod schema.

Why? Because at the end of the day, Vue and Nuxt devs deserve nice things too.

## One source of truth: your schema

Write a Zod schema. That's the source of truth for:

- **Types.** Every path, value, error, and write shape is inferred. No `any`, no manual generics, no reaching for the type plumbing whenever you add a field.
- **Defaults.** Attaform reads the schema's slim shape (`''` for strings, `0` for numbers, `false` for booleans) and uses it as the storage default. Override per field; don't repeat what the schema already says.
- **Validation.** Refinements run synchronously by default; async refinements await before submit dispatches.
- **Errors.** Each one lands at the offending path. `form.errors.email` is reactive end-to-end.
- **Metadata.** Labels, descriptions, placeholders, and free-form meta attach to schema fields and surface on `form.fields.<path>`.

One schema in, full reactive surface out.

## Type-safe end to end

Every part of the public surface is typed against your schema:

```ts
const schema = z.object({
  email: z.email(),
  age: z.number().int().min(13),
})

const form = useForm({ schema })

form.setValue('age', 21) // ok
form.setValue('age', 'twenty-one') // type error
```

`form.fields.<path>` knows the exact set of paths in the schema. `form.errors.<path>` is reactive, typed, narrowable.

The types follow the form through every state. While the user is typing, `form.values` is wide enough to hold whatever they have put there so far: incomplete fields, undecided discriminators, rehydrated half-filled draft state from yesterday's session. Inside `handleSubmit`, the same data flows through the schema and emerges with literals narrowed, refinements honored, and discriminated unions discriminating. Wide where reality is wide, tight where the schema guarantees it. [Type safety](/docs/reading-the-form/type-safety) walks through the trade.

## Native inputs, Vue directive

`v-register` is a Vue directive, not a wrapper component. Your `<input>` stays a native `<input>`; there's no field-component overhead between the DOM and the form.

```vue
<input v-register="form.register('email')" />
```

That's the whole binding. A11y attributes, value sync, focus state, blank tracking. All native.

## Live, layered validation

- Per-field on `change`, `blur`, or `submit`. Your call, per form.
- Sync refinements fire on the keystroke; async refinements await.
- A form's `meta.valid` is _gated_. It only flips true after every active path has resolved at least one validation pass, including the async ones. No flash-of-valid window for users with a slow uniqueness check.
- Server-side errors map back into the same reactive form API. The render surface is the same whether the error came from Zod or your API.

## SSR-first, hydration-clean

Forms render server-side and hydrate without a flash. Nuxt is zero-config; bare Vue 3 plus `@vue/server-renderer` takes two one-liner helpers. The form your server rendered _is_ the form your client picks up.

## Built into the core

These ship with the core, typed and orchestrated as first-class features:

- Field arrays with stable keys and per-item validation.
- Undo / redo with bounded history, opt-in per form.
- Persistence with per-field opt-in, local / session / IndexedDB / custom backends, and sensitive-name guards out of the box.
- Discriminated unions with variant memory across discriminator switches.
- A DevTools panel that surfaces every form on the page: values, errors, history, persistence drafts.

## Where to next

- [Quick start](/docs/getting-started/quick-start): your first form, end-to-end.
- [The form](/docs/reading-the-form/the-form): the full reactive surface returned by `useForm`.
- [Type safety](/docs/reading-the-form/type-safety): wide while typing, tight inside `handleSubmit`, by design.
- [When validation runs](/docs/validation/when-validation-runs): the moment errors appear.
- [The `v-register` directive](/docs/binding-inputs/v-register): how Attaform binds inputs.
- [Benchmarks](/docs/comparison/benchmarks): how Attaform measures up across the Vue form-library field, in a real browser.

_Source: https://attaform.dev/docs/getting-started/why-attaform_

---

# Installation

> One command. Attaform bootstraps itself.

Install Attaform and Zod, and you're set.


That's it for most apps. `useForm` and the `v-register` directive are ready to use as soon as the package is installed. Everything below this section is opt-in.

## Optional: Nuxt module

If you're on Nuxt, we recommend installing the module:

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

What this gets you: the form composables as auto-imports (`useForm`, `useWizard`, `injectForm`, `injectWizard`, `fieldMeta`, `withMeta`, `lazy`; see [Auto-imports](#auto-imports)), the SSR hydration plumbing, the Vite plugin, and the Attaform tab inside Nuxt DevTools.

## Optional: Vue 3 plugin

For app-wide defaults (`validateOn`, `debounceMs`, etc.) or explicit control over plugin registration on bare Vue 3, install the plugin in your app entry:

```ts
import { createApp } from 'vue'
import { createAttaform } from 'attaform'
import App from './App.vue'

createApp(App)
  .use(createAttaform({ defaults: { debounceMs: 100 } }))
  .mount('#app')
```

What this gets you: `createAttaform({ defaults })` for app-wide settings that every `useForm` call inherits.

## Optional: Vite plugin

If you're on bare Vue 3 + Vite (not Nuxt), add the plugin to `vite.config.ts`:

```ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { attaform } from 'attaform/vite'

export default defineConfig({
  plugins: [vue(), attaform()],
})
```

What this gets you: SSR-rendered `v-register` bindings that match the client-rendered output on initial HTML (no flicker between server paint and hydration), and a leaner production bundle (one Zod adapter shipped instead of both).

## Auto-imports

Both the Nuxt module and the Vite plugin can register Attaform's form composables as auto-imports, so a component reaches for them inside `<script setup>` with no `import` line. The set is the same either way: `useForm`, `useWizard`, `injectForm`, `injectWizard`, `fieldMeta`, `withMeta`, and `lazy`.

Under Nuxt, the module registers them for you. Toggle the whole set with the `autoImports` option:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['attaform/nuxt'],
  attaform: {
    autoImports: true, // default; set false to import the composables yourself
  },
})
```

On bare Vue 3 + Vite, feed the same manifest to `unplugin-auto-import`. `attaform/vite` re-exports it as `attaformAutoImportsMap`, ready to drop into the plugin's `imports` array:

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
import vue from '@vitejs/plugin-vue'
import { attaform, attaformAutoImportsMap } from 'attaform/vite'

export default defineConfig({
  plugins: [AutoImport({ imports: ['vue', attaformAutoImportsMap] }), vue(), attaform()],
})
```

Everything outside that set stays an explicit import: the plugin (`createAttaform`), the custom-input composable (`useRegister`), and the bring-your-own-adapter `useAbstractForm` from `attaform/abstract`. A registered auto-import always loses to an explicit or local binding of the same name, so opting out is only needed when you'd rather keep the names out of global scope entirely.

## Optional: Agent skill

Building with an AI coding assistant? Attaform ships an [Agent Skill](/docs/reference/ai-agents) that teaches it to write idiomatic Attaform: reach for `useForm`, bind with `v-register`, submit through `handleSubmit`. One command drops it into your project:

```sh
npx attaform skill
```

The skill travels inside the package, so it stays in lockstep with the version you have installed. That same page also covers the machine-readable [`llms.txt`](/llms.txt) index and the full-text [`llms-full.txt`](/llms-full.txt) dump you can hand an agent directly.

## Where to next

- [Quick start](/docs/getting-started/quick-start): your first form, end-to-end.
- [Your first schema](/docs/getting-started/your-first-schema): what Attaform reads from a Zod definition.
- [AI agents](/docs/reference/ai-agents): the skill, `llms.txt`, and the full-text docs dump for coding assistants.

_Source: https://attaform.dev/docs/getting-started/installation_

---

# Quick start

> A typed schema, validated inputs, a submit handler. The minimum viable form in five minutes.


Try the form below: clear the password and submit to watch focus pull to the broken field; submit with valid values to see the alert fire. Every behavior on screen comes from the Zod schema in code, which you'll see in the [Build a form](#build-a-form) section next.


## Build a form

Hand `useForm` a Zod schema and the reactive form comes back ready. This page reaches for three properties on the returned form: `register` for the input binding, `handleSubmit` for the submit gate, and `fields` for per-field error reads.

<!-- @generated-start:quick-start-script -->

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

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

const form = useForm({ schema })

const onSubmit = form.handleSubmit(async (values) => {
  await fetch('/api/sign-in', { method: 'POST', body: JSON.stringify(values) })
})
```

<!-- @generated-end:quick-start-script -->

Bind inputs to schema paths with `v-register`:

<!-- @generated-start:quick-start-template -->

```vue
<template>
  <form @submit="onSubmit">
    <label>
      Email
      <input v-register="form.register('email')" autocomplete="email" />
      <em v-if="form.fields.email.showErrors">{{ form.fields.email.firstError?.message }}</em>
    </label>
    <label>
      Password
      <input v-register="form.register('password')" type="password" autocomplete="off" />
      <em v-if="form.fields.password.showErrors">{{ form.fields.password.firstError?.message }}</em>
    </label>
    <button :disabled="form.meta.submitting" type="submit">Sign in</button>
  </form>
</template>
```

<!-- @generated-end:quick-start-template -->

`form.register('email')` returns what the `v-register` directive binds to. The directive handles the value read, the write, the coercion, and focus on invalid submit. Errors render via `form.fields.<path>.firstError?.message`, gated by `form.fields.<path>.showErrors` so the form doesn't yell on first paint.

## What's next

- [Your first schema](/docs/getting-started/your-first-schema): what Attaform reads from a Zod definition.
- [The form](/docs/reading-the-form/the-form): the full reactive surface returned by `useForm`.
- [When validation runs](/docs/validation/when-validation-runs): the moment errors appear.

_Source: https://attaform.dev/docs/getting-started/quick-start_

---

# Your first schema

> Any Zod schema becomes a typed, reactive Attaform.


Type into any of the demo's four inputs (`email`, `password`, `displayName`, `age`) and watch the live `form.values` JSON below the form update in real time. `form.values` is the reactive view of the form data that `useForm` returns, paths and types straight from the schema you handed in. The [What Attaform reads](#what-attaform-reads) section below traces each Zod construct in the demo to its form behavior.


## What Attaform reads

`useForm` is Attaform's entry point. Hand it a Zod schema and it returns a reactive form carrying every helper a template needs: a per-input binding factory, a per-field state map, and the live parsed values. Save the return value and reach for the pieces by name:

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

const schema = z.object({
  email: z.email(),
  password: z.string().min(8),
  displayName: z.string().min(2).optional(),
  age: z.number().int().min(13),
})

const form = useForm({ schema })
```

Object fields become reactive paths on `form.values`; nested objects become nested paths; refinements become per-field validators surfaced through `form.fields`.

The schema above covers most of what a real signup form needs:

- `email` and `password` are **required strings**. Attaform stores `''` as the default, so `form.values.email` starts as `''` and updates as the user types.
- `displayName` is **optional**. Storage still starts at `''`; the `.optional()` flag lets the field's empty string pass schema parsing at submit time.
- `age` is a **required number**. Storage starts at `0`; the `min(13)` refinement runs every time the field validates and shows up on `form.fields.age.errors`.

## Defaults from the schema

You don't redeclare defaults when you call `useForm`. Attaform reads them from the schema: `''` for strings, `0` for numbers, `false` for booleans, `[]` for arrays, `{}` for objects. Override per field with `defaultValues`:

```ts
const form = useForm({
  schema,
  defaultValues: {
    age: 18,
    displayName: 'Anonymous',
  },
})
```

Overrides are partial. Fields you don't mention pick up the schema's own default.

## Where to next

- [From schema to inputs](/docs/getting-started/from-schema-to-inputs): bind the schema to native inputs with `register` + `v-register`.
- [The form](/docs/reading-the-form/the-form): every property `useForm` returns.

_Source: https://attaform.dev/docs/getting-started/your-first-schema_

---

# From schema to inputs

> One directive binds any schema path to any native input. Attaform handles the read, the write, and the coercion.


The demo binds five native inputs (a text input for `fullName`, a numeric `age`, a country `<select>`, a `newsletter` checkbox, a `bio` textarea) against a single Zod schema. Type into any of them and the live `form.values` JSON below the form updates with the right type: the number input lands as a `number`, the checkbox as a `boolean`, the select as its enum literal. One directive handles every shape; the [register / v-register pair](#the-register-v-register-pair) section unpacks why.


## Setting up the form

`useForm` is the entry point. Hand it a Zod schema; it returns a reactive form carrying every binding helper this page uses. Save the return value and reach for the pieces by name:

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

const schema = z.object({
  fullName: z.string().min(2),
  age: z.number().int().min(13),
  country: z.string(),
  newsletter: z.boolean(),
  bio: z.string().optional(),
})

const form = useForm({ schema })
```

- `form.register(path)` is the per-input binding factory. The template hands its return value to `v-register`.
- `form.fields` is the reactive map of per-field state (errors, focus, touched, etc).
- `form.values` is the reactive parsed values, paths and types straight from the schema.

The rest of this page reaches for these three off the same `form` handle. The demo above does the same.

## The register / v-register pair

`form.register('email')` returns a small binding object the `v-register` directive consumes. Hand it off in the template:

```vue
<input v-register="form.register('email')" />
```

That's the whole binding. The directive:

- Reads from `form.values.email` and writes the current value into the DOM input.
- Writes back to `form.values.email` on every `input` event (or `change` / `blur` with directive modifiers).
- Coerces values per the schema, so `type="number"` lands in `form.values.age` as a number, not a string.
- Tracks per-field interaction state on `form.fields.email` (focused, touched, blurred, blank, plus errors and a few more). The [`fields` page](/docs/reading-the-form/fields) names every bit.

## Native inputs, native types

The directive works on every input shape Vue exposes. The schema dictates the value type; the input attribute dictates the DOM control:

```vue
<input v-register="form.register('fullName')" />
<input v-register="form.register('age')" type="number" />
<input v-register="form.register('newsletter')" type="checkbox" />
<select v-register="form.register('country')">…</select>
<textarea v-register="form.register('bio')" />
```

No wrapper component, no per-type binding logic. Your `<input>` stays a native `<input>`; Attaform sits at the directive layer.

## Where to next

- [From inputs to submit](/docs/getting-started/from-inputs-to-submit): close the loop with `handleSubmit`, the helper that gates dispatch on validation.
- [The `v-register` directive](/docs/binding-inputs/v-register): the full directive surface (modifiers, transforms, custom assigners).

_Source: https://attaform.dev/docs/getting-started/from-schema-to-inputs_

---

# From inputs to submit

> `handleSubmit` waits for validation, hands you parsed values, and reports submission state through `meta.submitting`.


The demo binds two inputs (an `email` and a `newsletter` checkbox) and wires a submit handler that runs a 1.2-second simulated API call. Submit with a valid email and the button label switches to "Subscribing…" while the call runs, then a toast confirms the payload. Submit with an invalid email and focus pulls to the broken field automatically. The [submit handler](#the-submit-handler) section below walks through the gating contract that produces that behavior.


## Setting up the form

This page focuses on two helpers off the form: `handleSubmit` (the submit-wrapping factory) and `meta` (the form's reactive status board). Hoist the schema and save the form:

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

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

const form = useForm({ schema })
```

The same `form` carries every helper from earlier pages (`register`, `fields`, `values`). Only `handleSubmit` and `meta` are new here.

## The submit handler

`handleSubmit(onSubmit, onError?)` returns a function you bind to `<form @submit>`. The wrapper calls `preventDefault` internally, so the `.prevent` modifier on the template is unnecessary. When the wrapped handler fires, it:

- Runs sync and async validation on every active path.
- Waits for pending async refinements before dispatching.
- Calls `onSubmit(values)` only if validation passes. `values` is the parsed Zod output, fully typed.
- Calls `onError(errors)` if validation fails. By default, focus moves to the first invalid field.

```ts
const onSubmit = form.handleSubmit(
  async (values) => {
    await api.signup(values)
  },
  (errors) => {
    console.log('Validation failed', errors)
  }
)
```

```vue
<form @submit="onSubmit">…</form>
```

## form.meta.submitting

While `onSubmit` is running, `form.meta.submitting` is `true`. Use it to disable the submit button or surface a spinner:

```vue
<button :disabled="form.meta.submitting" type="submit">
  {{ form.meta.submitting ? 'Saving…' : 'Save' }}
</button>
```

`submitting` flips back to `false` when the callback resolves or rejects (`handleSubmit` catches the rejection and routes the failure to its error hook). The full `meta` surface (`submissionAttempts`, `submitError`, `submitted`, and the 22 inherited FieldState bits) lives on [the `meta` page](/docs/reading-the-form/meta).

## Where to next

- [`handleSubmit`](/docs/submitting/handle-submit): the full submit surface, including error handlers and event semantics.
- [The form](/docs/reading-the-form/the-form): every method and property `useForm` returns.

_Source: https://attaform.dev/docs/getting-started/from-inputs-to-submit_

---

# Benchmarks

> How Attaform holds up across the Vue form-library field on the same demanding forms, measured in a real browser. Bundle size, supply-chain health, and per-scenario runtime, with every number traced to the run that produced it.


This page is an honest scoreboard. The numbers come from `apps/bench-arena`, a self-contained harness that drives every library through identical scenarios in real Chromium via Playwright, then writes one provenance-stamped `results.json` that this page renders directly. Nothing is hand-entered. Where Attaform leads, the run says so; where it pays a cost, the run says that too. Both ship from the same green run.

## How to read this

A fair cross-library comparison has to account for the fact that these libraries do different amounts of work. The harness handles that with a few rules:

- **Layers are the fairness axis.** Form-state libraries (Attaform among them) own reactive values, validation, and input binding. Validation-only libraries own validation against state you wire yourself. A batteries-included library renders its own inputs. Each row is labeled with its layer, so a validation-only engine mounting faster than a full form-state library is read as owning less, not as winning.
- **The DOM is held constant.** Every headless library drives the same bare `<input>` markup over the same field count and the same schema, so a runtime number reflects the library's own machinery, not its choice of components.
- **Every library runs in its fastest idiomatic configuration.** Debounces are neutralized, validation triggers are normalized, and array and union primitives use each library's native fast path. Attaform is measured on its shipping default, strict mode, never a relaxed setting.
- **Real builds, pinned validators.** Attaform is consumed as its published `dist`, the same artifact an installer gets, minified in the same build as every other library. Zod v3 is pinned across the Zod-capable cohort.
- **Numbers normalize two ways.** A _ratio_ compares each library to Attaform at the same size. A _slope_ compares a library to itself at the scenario's smallest size, so the shape of growth survives a change of machine.

The harness, every adapter, and the scenario generators live in [`apps/bench-arena`](https://github.com/attaform/Attaform/tree/main/apps/bench-arena). Found a fairer configuration for a library? The adapters are small and the README invites a pull request.

## What it costs to adopt

Before any runtime number, three figures decide whether a library is worth reaching for: what it can express, what it adds to your bundle, and how its supply chain scores.

### Capability coverage

What each library expresses as a first-class primitive versus composes by hand. A gap here becomes honest expressiveness data, never a rigged timing loss: a shape a library cannot express idiomatically is left out of its runtime rows rather than forced into a slow number.


### Bundle size

Attaform is the heaviest in the cohort. That is the cost of shipping reactive form state, schema validation binding, persistence, undo and redo, and a multi-step wizard in one zero-dependency package, and it is the honest price of admission. The figure is the full bundle; an app that route-splits its forms pulls less on a first paint.


### Supply-chain health

The [OpenSSF Scorecard](https://scorecard.dev) rates a project's adoption of supply-chain practices: branch protection, signed releases, pinned dependencies, CI hardening, and more. For a form library headed into an audited setting, that posture is part of the cost of adoption, so the benchmark stamps each project's current score alongside the size and runtime figures.


## Typing into a form

### Keystroke latency

The headline interaction. A keystroke runs the value write, validation, and the re-render it triggers. On a flat form Attaform clears a 60 fps frame budget with room to spare.


At five thousand fields the picture tightens. The harness reports where Attaform lands plainly, and it is a scenario worth a future look.


### Re-render scope

Editing one cell of a large grid should re-render one field, not the form. Configured optimally, the modern headless cohort all reaches that bound, and there is no lower number to beat.


## Standing up a form

### Mounting a large form

Building a two-thousand-field form from scratch is where the form-state libraries separate. Attaform mounts the whole reactive tree, validation wiring included, every value and validation path live before the first paint.


### Memory

Retained heap after mount, the library's reactive and validation state at scenario size. Churn is the per-cycle allocation pressure, and leak is the residual across mount and teardown cycles. The sparkline traces retained heap across the measured cycles.


## Working the harder shapes

### Validation throughput

A full-form validation pass over a massive form, the cost of a submit on the largest shape in the suite.


### Discriminated unions

Writing into and flipping between variants of a discriminated union. Attaform walks only the active branch, so a variant flip touches the branch in play rather than every alternative.


### Dynamic arrays

Appending and reordering rows in a growing list. Attaform's array helpers copy the target array before mutating, which keeps reads fast and identity stable but shows up as real cost on a reorder at a hundred rows. It is an honest line on the board.



### Multi-step wizard

Most of the cohort has no wizard primitive and composes a multi-step flow by hand, so this is an expressiveness comparison as much as a timing one. Where a comparable step transition exists, here is its cost; Attaform's `useWizard` ships the flow as a first-class shape.


## Caveats

The methodology is only as good as what it admits.

- **FormKit owns its inputs.** It cannot drive the shared bare field, so its re-render figure is a DOM-mutation proxy, marked in the tables, and its mount and memory figures include its own component tree. It is labeled batteries-included throughout and never placed silently beside bare-input libraries.
- **Heap is Chromium-quantized.** `usedJSHeapSize` reports rounded magnitudes, not byte-exact values, so memory figures show whole kilobytes and the slope across sizes carries more signal than any single number.
- **Every cell shares one time budget.** Each measured cell gets the same per-cell ceiling on the CI runner, identical for every library. A cell that cannot settle to a stable median inside it (a single mount of thousands of fields, or a full-form validation at the largest sizes on the heaviest libraries) is recorded as "did not finish" rather than dropped or estimated. The ceiling is uniform across the cohort, so it marks where a shape outgrows one measurement window, never a verdict on a library.
- **Bundle is total, not first-paint.** Every figure is the full minified and gzipped cost with the validator weighed in. Vue is external, since every app ships it once. Code-splitting changes what a first paint actually pulls.
- **An absent score has two distinct meanings.** "Not published" means a project has not opted into a Scorecard, which is a choice and not a deficiency. "Unavailable" means the lookup did not complete on that run, a network gap on our side and never a statement about the project. The viewer linked on each row shows the live result either way, and scores are point-in-time.
- **Local versus CI.** The committed numbers come from CI on a fixed runner. A figure stamped "local run" is illustrative shape data from a developer machine, superseded the next time CI refreshes the page.

## Reproduce it yourself

The harness is meant to be run by hand. Clone the repo, build Attaform's real `dist` with `pnpm prepack`, then from `apps/bench-arena` install the browser and run the arena. The full instructions live in the [bench-arena README](https://github.com/attaform/Attaform/tree/main/apps/bench-arena). Every adapter mounts by query parameter, so you can also open a single library and scenario in a browser and watch it work.

## Where to next

- [Performance](/docs/server-and-ssr/performance): Attaform's own hot-path numbers, measured against a per-PR regression gate.
- [How values are stored](/docs/schemas/storage-shape): the slim write shape behind the keystroke and validation figures.
- [Field-array mutations](/docs/writing-and-mutating/field-arrays): the array-helper characteristics behind the dynamic-array rows.

_Source: https://attaform.dev/docs/comparison/benchmarks_

---

# The schema contract

> A schema declares a value's shape, types, constraints, and transformations. One declaration drives validation, type inference, defaults, and metadata, all from the same source.


This page is the mental model for what a schema is and what it lets you do. The rest of the Schemas cluster takes each capability one at a time with side-by-side schema-and-result demos.

## What a schema is

A schema is a declarative description of data. It states what keys exist, what types they hold, how they nest, which values are valid, and which transformations apply on the way in or out. A single declaration carries the answer to every question about the data's shape.

Different schema libraries take different approaches: parser-combinators, classes, descriptor objects, type-only signatures. Attaform is schema-agnostic at its core, consuming any object that implements the [`AbstractSchema`](#schema-agnostic-core) contract. Out of the box, [Zod](https://zod.dev) is the canonical adapter. Zod v4 is the default; Zod v3 is one import away.

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

const schema = z.object({
  email: z.email(),
  age: z.number().int().min(13),
})
```

That schema is the artifact every dimension below describes. Attaform reads it once and derives validation, defaults, types, and reactive surfaces from it.

## What a schema declares

A schema covers six dimensions. Each one stands on its own; the rest of the Schemas cluster takes each in depth.

### Shape

The structural skeleton: which keys exist, what types they hold, how they nest. Zod composes shape through `z.object`, `z.array`, `z.tuple`, `z.record`, `z.discriminatedUnion`, `z.enum`, and the primitives (`z.string`, `z.number`, `z.boolean`, `z.date`, `z.bigint`).

```ts
const schema = z.object({
  profile: z.object({
    name: z.string(),
    interests: z.array(z.string()),
  }),
  notify: z.discriminatedUnion('channel', [
    z.object({ channel: z.literal('email'), address: z.email() }),
    z.object({ channel: z.literal('sms'), phone: z.string() }),
  ]),
})
```

Shape is the substrate every other dimension builds on. The per-construct deep dives live at [Nested objects](/docs/schemas/nested-objects), [Arrays & tuples](/docs/schemas/arrays-and-tuples), [Records & maps](/docs/schemas/records), and [Discriminated unions](/docs/schemas/discriminated-unions).

### Type safety

Every key, every leaf, every nested path carries a TypeScript type derived from the declaration. The schema is the single thing the type system reads; inference flows outward from there.

```ts
type Account = z.infer<typeof schema>
// { profile: { name: string; interests: string[] }, notify: ... }
```

No manual generics, no `any`, no reaching for plumbing whenever a field is added or renamed.

### Validation

Refinements declare which values are valid. A predicate runs against a parsed value and either passes or attaches an error.

```ts
const password = z
  .string()
  .min(8, 'At least 8 characters')
  .refine((s) => /[A-Z]/.test(s), 'Needs an uppercase letter')
```

Refinements can be asynchronous. `z.string().refine(async (v) => await api.isAvailable(v))` awaits the predicate before parsing settles. Synchronous predicates run eagerly; asynchronous ones await before submit dispatches. [When validation runs](/docs/validation/when-validation-runs) covers the timing model.

### Transformation

Two stages within parse can transform a value. `z.preprocess(fn, T)` normalizes the input before the inner schema sees it. `.transform(fn)` converts the validated value to the wire format.

```ts
z.preprocess((v) => (typeof v === 'string' ? v.trim() : v), z.string())

z.string().transform((s) => s.toLowerCase())
```

Both fire at parse time (`handleSubmit`, `validate`, `validateAsync`); storage holds the consumer's raw input verbatim. [How values are stored](/docs/schemas/storage-shape) walks the implications.

### Metadata

Labels, descriptions, placeholders, and free-form annotations live on the schema itself. `withMeta` attaches them at any node.

```ts
import { withMeta } from 'attaform'

const schema = z.object({
  email: withMeta(z.email(), {
    label: 'Email address',
    description: "We'll only use it for receipts.",
    placeholder: 'you@example.com',
  }),
})
```

Metadata travels with the schema; UI that consumes it reads from the declaration directly.

### Defaults

`.default(x)` declares the value a field takes when no input is supplied. `.catch(x)` declares a fallback for parse failures.

```ts
const schema = z.object({
  priority: z.string().default('normal'),
  remember: z.boolean().default(true),
})
```

[Defaults from the schema](/docs/schemas/defaults) covers how declared defaults seed initial values and which operations re-apply them.

## Zod adapters

`attaform` is the canonical import for new projects. `useForm` here takes a Zod schema, walks it once at construction, caches structural metadata, and implements `AbstractSchema` against Zod's runtime. It auto-detects the installed Zod major (v4 by default, v3 when that's what's installed) and routes to the matching adapter.

```ts
import { useForm } from 'attaform'
```

`attaform/zod` is the same surface named explicitly, and `attaform/zod-v3` / `attaform/zod-v4` pin one adapter with no detection. For projects still on Zod v3, `attaform/zod-v3` is the pin. The consumer-facing surface is identical across all four; the parsing engine and metadata walker differ to match each major's internals.

## Schema-agnostic core

Underneath the Zod entries, the core doesn't know about Zod at all. It consumes any object that implements `AbstractSchema`, a small contract covering identity, defaults, shape introspection, and validation. `attaform/abstract` exposes that core directly through `useAbstractForm`, which takes an `AbstractSchema` adapter instead of a Zod schema. The Zod adapters cover the bulk of real-world schemas; reach for [`AbstractSchema`](/docs/schemas/abstract-schema) and `attaform/abstract` when you're wiring Valibot, ArkType, Effect Schema, or a hand-rolled validator.

## Refinements vs. transforms

Refinements and transforms look adjacent but answer different questions.

```ts
// Refinement: runs at validate, doesn't change the value
z.string().refine((s) => /[a-z]/.test(s), 'Needs a lowercase letter')

// Transform: runs at parse, changes the value
z.string().transform((s) => s.toLowerCase())
```

Refinements ask "is this value acceptable?" Transforms ask "given this value, what should the next stage see?" Schemas stack both in any order; the order matters at validate / parse time.

The split is intentional. Refinements drive live feedback as users type; transforms shape the wire format on the way out.

## Fingerprinting

Every schema carries a structural fingerprint: a short string that changes when the shape changes (adding or removing a field, changing a leaf type, restructuring nesting) but stays stable under refinement, transform, or metadata tweaks. The fingerprint surfaces in two places:

- Persistence keys (a schema change auto-invalidates stale drafts).
- Shared-key form mismatches in dev (two `useForm({ key: 'x' })` calls with different schemas warn).

`schema.fingerprint()` lives on the adapter; the runtime calls it when needed.

## Where to next

- [Defaults from the schema](/docs/schemas/defaults): how `.default()` declarations flow into initial values.
- [How values are stored](/docs/schemas/storage-shape): the per-wrapper read-shape policy.
- [Optional, nullable, defaulted](/docs/schemas/optional-nullable): three modifiers, three different meanings.

_Source: https://attaform.dev/docs/schemas/contract_

---

# Defaults from the schema

> Schema `.default()` declarations seed `form.values` at mount and re-seed on `reset()`. The per-form `defaultValues` option overlays the schema's defaults. Same semantics, different scope.


The demo below shows the same schema mounted three ways: bare (defaults from the schema), with a `defaultValues` overlay (per-form override), and with `unset` (a specific leaf opted back to blank). Each form starts from the same declaration; the option drives the initial state.


## Schema-declared defaults

```ts
const schema = z.object({
  notify: z.boolean().default(true),
  count: z.number().default(10),
  tag: z.string().default('untitled'),
})

const form = useForm({ schema })

form.values.notify // true
form.values.count // 10
form.values.tag // 'untitled'
```

At mount, the adapter resolves the schema's declared defaults into a complete initial value tree. `form.values.<path>` reads concrete types: no `undefined`, no manual checks for "did the schema run yet?"

The same defaults re-seed on `reset()`:

```ts
form.setValue('count', 99)
form.values.count // 99
form.reset()
form.values.count // 10, back to the schema's default
```

## Per-form `defaultValues` overlay

When you pass `defaultValues` to `useForm`, the overlay sits on top of the schema's defaults:

```ts
const form = useForm({
  schema,
  defaultValues: { count: 42 },
})

form.values.notify // true        ← schema default
form.values.count // 42         ← overlay wins
form.values.tag // 'untitled'  ← schema default
```

The overlay is a `DeepPartial` of the form's input shape. Supply only the leaves you want to override; missing leaves fall back to the schema's declared default.

This is the right place for environment-specific defaults: a "remember me" toggle defaulting to true on a desktop app vs. false on a kiosk, a discount-rate default that flows from a feature flag, etc.

## Three patterns for `defaultValues`

```ts
import { unset } from 'attaform'

// 1. Plain values: explicit defaults flow into storage
useForm({ schema, defaultValues: { email: 'me@example.com', count: 10 } })

// 2. Omit defaultValues entirely: numeric leaves auto-mark blank,
//    strings and booleans take their schema default
useForm({ schema })

// 3. Mark any path as `unset`: leaf, container, or the whole form.
//    The runtime writes the schema's slim value and flags every
//    primitive descendant in form.blankPaths.
useForm({ schema, defaultValues: { email: unset, count: 10 } })
useForm({ schema, defaultValues: { profile: unset } }) // whole container
useForm({ schema, defaultValues: unset }) // every primitive leaf
```

The third pattern uses `unset` as a sentinel that lands at any path. Required schemas under the unset path surface a `code: 'atta:no-value-supplied'` error reactively. See [the `unset` page](/docs/writing-and-mutating/unset) for the position-by-position contract and [the `blank` field-state bit](/docs/validation/blank) for the storage / display divergence story.

## Per-mount sync defaults

`defaultValues` accepts a function as well as a plain value. The sync function form runs once per `useForm` call (on a microtask after construction) and captures whatever's in scope at that moment. Use it when the defaults are cheap to compute but need to read live state at mount time, e.g. a per-instance session ID, the current timestamp, or a value pulled from a sync store:

```ts
const sessionCounter = ref(0)

const form = useForm({
  schema,
  defaultValues: () => ({
    sessionId: `sess-${++sessionCounter.value}`,
    createdAt: new Date().toISOString(),
    topic: '',
  }),
})
```

Each call to `form.rehydrate()` re-fires the captured factory, so a "new session" button is one method call away. The factory's closure picks up whatever the outer scope holds right now, which is the value over a plain frozen `defaultValues` object.


`form.hydrating` does flip `true` for a microtask while the sync factory runs, then back to `false`. Templates that read it usually won't see the brief flicker; the flag is mostly relevant for the async form below.

## Loading defaults asynchronously

When the defaults need a network round-trip, return a `Promise`:

```ts
const form = useForm({
  schema,
  defaultValues: async () => api.fetchDraft(userId),
})
```

The form is fully usable while the factory is in flight; it holds the schema's slim defaults and exposes the load state through `form.hydrating`:

```vue
<form :aria-busy="form.hydrating">
  <input v-register="form.register('email')" :disabled="form.hydrating" />
</form>
```

When the promise resolves the payload overlays onto storage, the same way a plain `defaultValues` object would; `hydrating` flips back to `false`.

If the factory throws or rejects, the error lands on `form.hydrateError` as a `ValidationError` (`code: 'atta:hydration-failed'`). The same entry also surfaces through `form.meta.errors`, so error UI can render off either surface. The form stays usable with the slim defaults; call `form.rehydrate()` to refire the captured factory, e.g. wired to a retry button.


Under SSR the factory fires via `onServerPrefetch`, so the resolved payload bakes into the hydration transfer state; the client never re-fetches on hydrate.

## Numeric leaves auto-mark blank

Numeric primitives (`number`, `bigint`) are special: when no explicit value is supplied, the leaf auto-marks as blank because storage's slim default (`0`, `0n`) differs from what the DOM shows (an empty `<input type="number">`).

```ts
// schema: z.object({ age: z.number(), title: z.string() })
useForm({ schema })

form.values.age // 0       ← storage slim default
form.fields.age.blank // true    ← auto-marked
form.errors.age // [{ code: 'atta:no-value-supplied', … }]

form.values.title // ''      ← storage slim default
form.fields.title.blank // false   ← NOT auto-marked (matches DOM)
form.errors.title // undefined  (z.string() accepts '')
```

Strings and booleans don't auto-mark because their slim defaults match what the DOM natively shows. The schema is the authority on whether `''` / `false` is acceptable; numerics need the side-channel to disambiguate "user typed `0`" from "user supplied nothing." See [the `blank` field-state bit](/docs/validation/blank) for the full lifecycle.

## `.default(x)` vs. `.prefault(x)` vs. `.catch(x)`

Zod offers three wrappers that influence the initial value:

```ts
z.string().default('foo') // pre-parse: used when input is undefined
z.string().prefault('foo') // same as default in Zod v4 (alias)
z.string().catch('foo') // post-parse fallback: used when parse fails
```

For form defaults, you usually want `.default(x)`; it fills the slot before any user input lands. `.catch(x)` is for recovery: if the schema would otherwise raise an error, fall back to `x`. The adapter recognizes all three and feeds the initial value into `form.values` the same way; the difference shows up at parse time.

## `reset()` vs. `clear()`

The two operations look adjacent but mean different things:

```ts
const schema = z.object({
  notify: z.boolean().default(true),
  count: z.number().default(5),
})
const form = useForm({ schema })

form.reset() // notify → true,  count → 5  (declared defaults)
form.clear() // notify → false, count → 0  (falsy-for-type)
```

`reset` re-applies the schema's declared `.default()` values; `clear` ignores them and writes the type's falsy concrete instead. Both accept a path argument: `resetField(path)` re-seeds one leaf, `clear(path?)` wipes one or the whole form.

For "wipe to blank state" UX, prefer `clear`. For "back to the form's starting state" UX, prefer `reset`.

## Where to next

- [How values are stored](/docs/schemas/storage-shape): the slim write shape and the read vs. write vs. submit distinction.
- [Optional, nullable, defaulted](/docs/schemas/optional-nullable): what each missing-ness modifier means for the initial value.
- [`reset` & `resetField`](/docs/writing-and-mutating/reset): the imperative surface that re-applies defaults.

_Source: https://attaform.dev/docs/schemas/defaults_

---

# How values are stored

> A single mental model for what `form.values` returns. Defaults are pre-resolved, optional / nullable keep their wrappers, and schema-side normalizers (preprocess, coerce, transforms) only fire at parse time. Storage holds the consumer's input verbatim.


The demo below shows the same schema across all three views: what `form.values` returns at runtime, what `setValue` accepts, and what `handleSubmit`'s callback sees. The phone field is the giveaway: storage keeps the raw digits the user typed, and the preprocess formatter's output only surfaces inside `handleSubmit`'s callback. Preprocess itself runs every time validation does (each keystroke under `validateOn: 'change'`, each blur under `'blur'`, only at submit under `'submit'`), but its output never lands in storage.


## The three shapes

A schema produces three different views of its data, each with a distinct surface:

| Surface                         | Shape      | What it answers                                          |
| ------------------------------- | ---------- | -------------------------------------------------------- |
| `form.values` / `form.fields`   | **read**   | What does storage hold now? (`StorageShape<Schema>`)     |
| `setValue` / `defaultValues`    | **write**  | What may the consumer pass in? (`z.input<Schema>`)       |
| `handleSubmit` / `form.parse()` | **submit** | What does a successful parse yield? (`z.output<Schema>`) |

The same schema produces all three; the surface determines which one you're holding.

```ts
const formatPhone = (v: unknown): unknown => {
  if (typeof v !== 'string') return v
  const digits = v.replace(/\D/g, '')
  return digits.length === 10
    ? `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`
    : v
}

const schema = z.object({
  flag: z.boolean().default(true),
  count: z.coerce.number(),
  phone: z.preprocess(formatPhone, z.string()),
  ratio: z.string().transform((v) => Number(v) / 100),
})

const form = useForm({ schema })

// READ: storage holds the concrete, resolved type
form.values.flag // boolean       ← .default(true) peeled
form.values.count // unknown        ← z.coerce.X() input is unknown
form.values.phone // unknown        ← preprocess input is unknown
form.values.ratio // string        ← transform deferred to parse

// WRITE: anything goes at preprocess / coerce leaves; defaulted leaves accept undefined
form.setValue('flag', undefined) // OK; default fills the gap
form.setValue('count', '42') // OK; raw string lands in storage as-is
form.setValue('phone', '1231231234') // OK; raw digits land in storage as-is

// SUBMIT: schema-side normalizers fire here
form.handleSubmit((data) => {
  data.count // number ← z.coerce.number() converted at parse
  data.phone // string ← preprocess formatted at parse
  data.ratio // number ← .transform() produced this
})
```

## Two layers of mutation

Two distinct surfaces can change what lands in storage. They sit at different boundaries, and `form.values` reflects only one of them.

| Layer                                              | Mutates storage? | When                       |
| -------------------------------------------------- | ---------------- | -------------------------- |
| `v-register` modifiers and register `transforms`   | yes              | at the user-input boundary |
| `z.preprocess` / `z.coerce.X()` / `.transform(fn)` | no               | at parse / submit          |

The directive layer owns write-time mutation: `v-register.trim` strips whitespace as the user blurs, `v-register.number` casts the DOM string to a number, and `register({ transforms: [...] })` runs consumer-supplied functions on every commit. Anything those produce ends up in storage.

Schema-side normalizers do their work later, inside `safeParse`. The consumer's verbatim write lands in storage; `handleSubmit`, `validate`, and `validateAsync` re-parse storage through the schema and surface the typed result. There is no schema shape that mutates storage at the write boundary.

## Per-wrapper read-shape policy

`StorageShape<Schema>` walks each field and applies one of these rules:

| Wrapper               | Field key | Field type at the key          | Rationale                                                                                           |
| --------------------- | --------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
| `.default(x)`         | required  | inner type (no `\| undefined`) | Storage always holds `x` or a write; never empty.                                                   |
| `.prefault(x)`        | required  | inner type                     | Same as `.default(x)`.                                                                              |
| `.catch(x)`           | required  | inner type                     | Catch wraps a fallback; storage holds a value.                                                      |
| `.optional()`         | optional  | `inner \| undefined`           | Genuinely optional; `undefined` is the wrapper's marker.                                            |
| `.nullable()`         | required  | `inner \| null`                | `null` is the wrapper's "explicit empty".                                                           |
| `.readonly()`         | required  | inner type                     | Read-only is type-only; the read shape is its inner.                                                |
| `z.preprocess(fn, T)` | required  | `unknown`                      | Schema-side normalizer; runs at parse, not at the write boundary. Storage holds raw input.          |
| `z.coerce.X()`        | required  | `unknown`                      | Same as `z.preprocess`: coerce fires inside `safeParse`. Storage holds whatever the consumer wrote. |
| `.transform(fn)`      | required  | source input shape             | Transforms run at parse, not read; storage holds the pre-transform value.                           |
| (plain / fallthrough) | required  | `z.input<T>`                   | Default for anything else.                                                                          |

Reads at every nested level get the same treatment recursively.

## Blank-path synthesis

Required leaves that haven't been written to aren't `undefined`. The runtime fills them with the type's falsy concrete at mount:

| Schema at path    | Initial `form.values.<path>`                          |
| ----------------- | ----------------------------------------------------- |
| `z.string()`      | `''`                                                  |
| `z.number()`      | `0`                                                   |
| `z.boolean()`     | `false`                                               |
| `z.bigint()`      | `0n`                                                  |
| `z.date()`        | `new Date(0)`                                         |
| `z.array(...)`    | `[]`                                                  |
| `z.set(...)`      | `new Set()`                                           |
| `z.record(...)`   | `{}`                                                  |
| `z.object({...})` | recursive: every required property gets its own falsy |

The runtime tracks which paths are still "blank" through the same field-state bit `field.blank` covers; see [the `blank` field-state bit](/docs/validation/blank) for the storage / display divergence story.

## Three edges the invariant doesn't promise to flatten

These read as honest `T | undefined` / `T | null` / `T | undefined` respectively: documented edges, not bugs.

### `.optional()` (no default): `T | undefined`

```ts
const schema = z.object({ bio: z.string().optional() })
const form = useForm({ schema })

form.values.bio // string | undefined
```

The wrapper's whole point is "this slot may be absent." Storage respects it.

### `.nullable()`: `T | null`

```ts
const schema = z.object({ ref: z.string().nullable() })
form.values.ref // string | null
```

`null` is the wrapper's "explicit empty" signal, distinct from `undefined` and from `''`.

### Array element past `length`: `T | undefined`

```ts
const schema = z.object({ tags: z.array(z.string()) })
form.values.tags[0] // string | undefined
```

The `| undefined` taint comes from TypeScript's `noUncheckedIndexedAccess` (which strict configs set), not from the storage invariant. Iteration (`for (const tag of form.values.tags)`) keeps the strict `string` element type; only direct numeric indexing is tainted.

## When to reach for which surface

```ts
const form = useForm({ schema })

// READ: anywhere you need the current value
form.values.email // primary path
form.fields.email.value // same value, plus per-field state
form.toRef('email') // ref-shaped interop for external composables

// WRITE: anywhere you set a value
form.setValue('email', 'a@b.c') // single path
form.setValue({ email: 'a@b.c' }) // whole-form merge
form.clear('email') // wipe to falsy-for-type
form.reset() // re-seed from declared defaults

// SUBMIT: once on form submission
form.handleSubmit((data) => apiPost(data)) // `data` is the post-transform output
const result = await form.parse() // imperative one-shot parse
```

Each surface uses the shape that's correct for its purpose. The mental discipline: **don't reach across surfaces.** If you want post-transform output, go through submit. If you want the raw input, go through `form.values`. If you want to write, go through `setValue` or `clear`; `form.values` is read-only on purpose.

## Where to next

- [Defaults from the schema](/docs/schemas/defaults): how `.default()` flows into the read shape.
- [Optional, nullable, defaulted](/docs/schemas/optional-nullable): the three missing-ness modifiers, side by side.
- [URL availability check](/docs/validation/url-availability-check): a worked example threading `z.preprocess` and async `.refine` against the storage contract.
- [The validation lifecycle](/docs/validation/lifecycle): `parse()` returns the submit shape, parsed.

_Source: https://attaform.dev/docs/schemas/storage-shape_

---

# Optional, nullable, defaulted

> Three modifiers that look similar and mean three different things: `.optional()` lets the slot stay absent, `.nullable()` makes `null` a valid value, `.default(x)` fills the slot when input is missing.


The demo runs the same field through all three modifiers side by side. Watch how each one reports its value when nothing has been typed, and how each one validates when you do start typing.


## The trichotomy at a glance

```ts
const schema = z.object({
  optional: z.string().optional(), // string | undefined
  nullable: z.string().nullable(), // string | null
  defaulted: z.string().default('seed'), // string
})

const form = useForm({ schema })

form.values.optional // undefined (slot may be absent)
form.values.nullable // '' (synthesized falsy: string default '')
form.values.defaulted // 'seed' (schema-declared default applied)
```

Each modifier sends a different signal at validate time:

| Modifier      | Empty case is valid? | Empty case looks like |
| ------------- | -------------------- | --------------------- |
| `.optional()` | yes                  | `undefined`           |
| `.nullable()` | yes                  | `null`                |
| `.default(x)` | yes                  | `x`                   |
| (plain)       | no                   | `''` / `0` / `false`  |

## `.optional()`: "this slot may be absent"

```ts
z.object({ bio: z.string().optional() })
```

`form.values.bio` reads `string | undefined`. The schema accepts both:

- The slot being absent (the field never gets a value).
- A typed string.

Use `.optional()` when _not filling the field is a valid choice_: a "tell us more about yourself" prompt that's genuinely skippable.

### The empty-input cycle

When a user clears an `.optional()` input via `v-register`, storage returns to `undefined` rather than `''`. The schema's "absent" path stays reachable through the DOM after any interaction, which closes a real validation hole: typing invalid text into an optional field with a strict inner check (e.g. `z.url().optional()`) and then clearing the input also clears the validation error. Without this contract, `''` would land in storage and parse would fail forever (`''` is neither `undefined` nor a valid URL), leaving the user stuck.


Required string leaves keep `''` on clear, because `''` IS a valid string and the schema can decide what to do with it (accept, fail `min(1)`, etc.). The optional escape only fires when the schema admits `undefined` at that leaf.

## `.nullable()`: "`null` is an explicit signal"

```ts
z.object({ assignedTo: z.string().nullable() })
```

`form.values.assignedTo` reads `string | null`. The schema accepts:

- `null`, meaning "explicitly unassigned."
- A typed string.

But NOT `undefined`. The slot is required to hold _some_ value; `null` is the signal you've decided "no value here on purpose."

Use `.nullable()` when _unassigned is a meaningful state_ that the data model needs to distinguish from "not yet decided" or "empty string."

## `.default(x)`: "fill the slot with `x` when input is missing"

```ts
z.object({ priority: z.string().default('normal') })
```

`form.values.priority` reads `string`: no union, no `null`, no `undefined`. The schema:

- Applies `'normal'` when no input is supplied.
- Otherwise uses whatever the caller passed.

Use `.default(x)` when _every record needs a value and you have a sensible starting point_: the "Priority" dropdown that should start at "Normal," the "Notifications" toggle that should start on.

## Stacking modifiers

The modifiers compose, but the order changes the meaning:

```ts
z.string().optional().default('seed') // (string | undefined).default → string
z.string().default('seed').optional() // string.optional → string | undefined
z.string().nullable().default(null) // (string | null).default → string | null
```

For form ergonomics, `.default(x)` last is the usual move; it peels the optionality back off, so `form.values.<path>` reads as a concrete type.

## What `form.errors.<path>` does for each

```ts
const schema = z.object({
  optional: z.string().optional(),
  nullable: z.string().nullable(),
  defaulted: z.string().default('seed'),
  required: z.string().min(1, 'Name is required'),
})
const form = useForm({ schema })

// Before any user input
form.errors.optional // undefined (empty slot is valid)
form.errors.nullable // undefined ('' satisfies z.string())
form.errors.defaulted // undefined ('seed' satisfies z.string())
form.errors.required // [...] (z.string().min(1) rejects '')
```

The errors flow from the schema; the modifiers shape what counts as empty. A required `z.string()` with no modifier sees `''` and accepts it (an empty string _is_ a string). Add `.min(1, …)` to require a non-empty string; that's the schema speaking, not a side-channel.

## When to reach for `unset` instead

`.optional()` and `.nullable()` are schema-level; they declare that the empty case is type-valid. Sometimes you want a leaf that's _type-required_ but starts in a deliberate "no value yet" state without changing the schema. That's `unset`:

```ts
import { unset } from 'attaform'

const schema = z.object({ pickup: z.string().min(1, 'Required') })
const form = useForm({ schema, defaultValues: { pickup: unset } })

form.fields.pickup.blank // true
form.errors.pickup // [{ code: 'atta:no-value-supplied', … }]
```

`unset` joins the path to `form.blankPaths`, which surfaces `atta:no-value-supplied` reactively when the schema is required. The schema stays strict; the consumer signals intent at the call site. The same sentinel works at containers, arrays, records, discriminated unions, wrappers, and the root: `defaultValues: { profile: unset }` recursively marks every primitive descendant. See [`unset`](/docs/writing-and-mutating/unset) for the full contract and [the `blank` field-state bit](/docs/validation/blank) for the lifecycle.

## Where to next

- [Defaults from the schema](/docs/schemas/defaults): `.default(x)` is the most common case; per-form `defaultValues` overlays it.
- [How values are stored](/docs/schemas/storage-shape): the per-wrapper read-shape policy in full.
- [The `blank` field-state bit](/docs/validation/blank): the storage / display side-channel that handles "user supplied nothing" without lying about the value.

_Source: https://attaform.dev/docs/schemas/optional-nullable_

---

# Discriminated unions

> Schemas that branch on a discriminator key get first-class runtime handling: switching the discriminator reshapes storage to the new variant's slim default, and `form.errors.<path>` is automatically variant-filtered.


Pick a notify channel (Email, SMS, or Push) and watch the field below the radios swap to the variant's typed shape. The schema's discriminated union drives both the conditional render and the underlying storage reshape; whatever the inactive variant held gets purged from `form.values`, and the new variant's slim default seeds.


## The schema

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

const schema = z.object({
  notify: z.discriminatedUnion('channel', [
    z.object({ channel: z.literal('email'), address: z.email() }),
    z.object({ channel: z.literal('sms'), phone: z.string() }),
    z.object({ channel: z.literal('push'), deviceId: z.string() }),
  ]),
})
const form = useForm({ schema })
```

Three variants, one discriminator (`channel`). Each variant is a regular `z.object`; refinements, defaults, transforms, nested objects all work the way they do anywhere else.

## What happens on a switch

```ts
form.setValue('notify.channel', 'email')
form.setValue('notify.address', 'a@b.com')
// storage: { notify: { channel: 'email', address: 'a@b.com' } }

form.setValue('notify.channel', 'sms')
// storage: { notify: { channel: 'sms', phone: '' } }
//   (email's `address` is purged; sms's `phone` is seeded)

form.setValue('notify.channel', 'email')
// storage: { notify: { channel: 'email', address: 'a@b.com' } }
//   (`address` restored from variant memory)
```

Writing the discriminator triggers a structural reshape:

1. The outgoing variant's keys are purged from storage.
2. The new variant's keys are seeded from the schema's slim defaults.
3. The structural-completeness invariant runs before any subsequent reads: missing variant keys get filled even if the write was the discriminator only.

The reshape fires for every variant write: `setValue('notify', { channel: 'sms', phone: '' })` reshapes the same way as `setValue('notify.channel', 'sms')`.

## Variant memory

Switching back to a previously-visited variant restores its prior typed subtree by default; `rememberVariants: true` is Attaform's default. The "memory" lives in-memory only (not persisted across reloads); each discriminated union at every nesting depth memorizes independently.

Opt out per-form:

```ts
useForm({ schema, rememberVariants: false })
```

With `false`, every switch drops the outgoing variant's typed state. See [Variant memory](/docs/writing-and-mutating/variant-memory) for the full discussion.

## Template rendering

Branch on the discriminator value with `v-if` / `v-else-if`:

```vue
<template>
  <label v-if="form.values.notify.channel === 'email'">
    <input v-register="form.register('notify.address')" />
    <em v-if="form.fields.notify.address.showErrors">
      {{ form.fields.notify.address.firstError?.message }}
    </em>
  </label>

  <label v-else-if="form.values.notify.channel === 'sms'">
    <input v-register="form.register('notify.phone')" type="tel" />
  </label>
</template>
```

Vue's template narrowing follows the discriminator: autocomplete on `form.values.notify.address` only suggests when the branch matches the literal type. The `form.fields.<variant-path>` access works regardless of the active variant, but `showErrors` only fires when the path is reachable (so an inactive variant's stale field state stays silent).

## Errors are variant-filtered

`form.errors.<path>` (the per-leaf view) filters by active variant: only errors on the active variant's path show up. Inline field rendering doesn't need any extra guards:

```vue
<small v-if="form.errors.notify.address?.[0]">
  <!-- only renders when notify.channel === 'email' -->
  {{ form.errors.notify.address[0].message }}
</small>
```

The form-level `form.meta.errors` aggregate is **NOT** variant-filtered; errors for the inactive variant's fields stay in the array. A "show all" wizard summary iterating `meta.errors` will surface stale errors for the variant the user left. For wizard-wide summaries, prefer per-path reads or filter the aggregate manually.

## Invalid discriminator values

If the user types a discriminator value that doesn't match any variant (`channel: 'fax'` against `'email' | 'sms' | 'push'`), the reshape is skipped; the variant fields stay as they were, and the schema surfaces a refinement error on the discriminator itself. Template variant-conditional rendering can branch on the schema's kind rather than relying on the runtime to "guess" a variant.

When the whole form is one of several shapes rather than a field nested inside one, reach for a [variant form](/docs/schemas/variant-forms): the `z.discriminatedUnion` becomes the schema root, `form.values` reads the active variant at the top level, and variant fields bind by their own key.

## Where to next

- [Variant forms](/docs/schemas/variant-forms): a `z.discriminatedUnion` schema as the form root, not just a field inside an object.
- [Variant memory](/docs/writing-and-mutating/variant-memory): when to keep the prior typed subtree, when to drop it.
- [`setValue` patterns](/docs/writing-and-mutating/set-value): programmatic writes that drive the same reshape.
- [`errors`](/docs/reading-the-form/errors): the variant-filtered per-leaf view vs. the un-filtered aggregate.

_Source: https://attaform.dev/docs/schemas/discriminated-unions_

---

# Variant forms

> When the form _is_ one of several shapes, make the union the root. A `z.discriminatedUnion` schema at the top level gives you a variant form: `form.values` reads the active variant, and writing the discriminator reshapes the whole form.


The demo is a checkout payment method. A payment is exactly one of card, bank transfer, or invoice, each with its own fields, so the schema root is a `z.discriminatedUnion('method', …)`. Switch the method and the form reshapes to that variant; the readout below tracks the change.


## The schema

A variant form declares a `z.discriminatedUnion` schema as the root, not nested under a key. One discriminator (`method`) picks the variant; each variant is a regular Zod schema:

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

const schema = z.discriminatedUnion('method', [
  z.object({ method: z.literal('card'), cardNumber: z.string(), cvc: z.string() }),
  z.object({ method: z.literal('bank'), iban: z.string() }),
  z.object({ method: z.literal('invoice'), poNumber: z.string(), netDays: z.number() }),
])

const form = useForm({ schema })
```

There is no wrapper key. The discriminator and every variant's fields sit at the top level of the form.

## Reading the active variant

Because the union is the root, `form.values` reads the variant directly. Every variant's keys are reachable at the top level, so a field read works without narrowing first:

```ts
form.values.method // the discriminator: string while editing
form.values.cardNumber // string | undefined (present on the card variant)
form.values.iban // string | undefined (present on the bank variant)
```

A per-variant field reads as `T | undefined` because it is present only while its variant is active, matching the runtime, where reading a key from another variant returns `undefined`. The discriminator reads as `string` while editing, since the user may be mid-switch. Inside [`handleSubmit`](/docs/submitting/handle-submit) the parsed value is the true narrowed union, so you branch on it with full type narrowing:

```ts
const onSubmit = form.handleSubmit((payment) => {
  if (payment.method === 'card') {
    payment.cardNumber // string, narrowed to the card variant
  }
})
```

## Binding the discriminator and variant fields

The discriminator is an ordinary field: bind it to a `<select>` or a set of radios, and each variant's fields bind by their own key, no wrapper prefix. Branch the template on `form.values.method`:

```vue
<template>
  <label>
    Payment method
    <select v-register="form.register('method')">
      <option value="card">Card</option>
      <option value="bank">Bank transfer</option>
      <option value="invoice">Invoice</option>
    </select>
  </label>

  <template v-if="form.values.method === 'card'">
    <input v-register="form.register('cardNumber')" />
    <em v-if="form.fields.cardNumber?.showErrors">{{
      form.fields.cardNumber?.firstError?.message
    }}</em>
  </template>

  <template v-else-if="form.values.method === 'bank'">
    <input v-register="form.register('iban')" />
  </template>
</template>
```

A variant field's node is absent while its variant is inactive, so reach it through `?.`: `form.fields.cardNumber?.showErrors`. The same chaining applies to [`form.errors`](/docs/reading-the-form/errors), which is variant-filtered, so an inactive variant's errors stay silent.

## Switching variants reshapes the form

Writing the discriminator reshapes storage to the new variant: the outgoing variant's keys are purged, and the new variant's keys seed from the schema's slim defaults. At the root, the reshape is the whole form:

```ts
form.setValue('method', 'bank')
// form.values() : { method: 'bank', iban: '' }
//   (card's cardNumber / cvc purged; bank's iban seeded)
```

This is the same engine that drives a nested discriminated union, run at the root path. Variant memory (restoring a variant's values when you switch back to it) is on by default. The full reshape and memory semantics live on [Discriminated unions](/docs/schemas/discriminated-unions), which covers the same feature as a field inside an object form.

## Defaults

A bare variant root defaults to the first variant, with its fields at their slim defaults:

```ts
const form = useForm({ schema })
form.values() // { method: 'card', cardNumber: '', cvc: '' }
```

Start on a different variant, or seed its fields, with `defaultValues`. Pass one complete variant:

```ts
const form = useForm({
  schema,
  defaultValues: { method: 'invoice', poNumber: 'PO-1', netDays: 30 },
})
```

## When the shape is fixed, reach for an object

Variant forms are for a value that is genuinely one of several shapes. When every field is always present, a `z.object` root is the better fit. The two compose freely: an object form can hold a discriminated-union field (see [Discriminated unions](/docs/schemas/discriminated-unions)), and a variant's schema can be any Zod schema, including nested objects, arrays, and records.

## Where to next

- [Discriminated unions](/docs/schemas/discriminated-unions): the same feature as a field inside an object form, with the full reshape and error-filtering detail.
- [Variant memory](/docs/writing-and-mutating/variant-memory): when to keep a variant's values on switch-back, when to drop them.
- [Dictionary forms](/docs/schemas/dictionary-forms): the other non-object root, a `z.record` map.
- [`handleSubmit`](/docs/submitting/handle-submit): where the parsed value narrows to the active variant.

_Source: https://attaform.dev/docs/schemas/variant-forms_

---

# Arrays & tuples

> Two container shapes, one binding pattern. Numeric segments in the path point to elements, and the field-array helpers cover every mutation a list-shaped input needs.


The demo binds an array of objects (todo items) and a fixed-length tuple (a date range with exactly two endpoints). Both flow through the same `register('path.index.subpath')` shape; the schema's array-ness is what unlocks `append` / `remove` / `swap`.


## `z.array(elem)`: variable length

```ts
const schema = z.object({
  todos: z.array(
    z.object({
      title: z.string().min(1, 'Title is required'),
      done: z.boolean().default(false),
    })
  ),
})

const form = useForm({ schema, defaultValues: { todos: [] } })
```

Each element gets a numeric segment in its path:

```ts
form.values.todos[0].title // string
form.values.todos[2].done // boolean
form.register('todos.3.title') // path autocomplete works
form.errors.todos[1]?.title // ValidationError[] | undefined
```

Templates iterate with `v-for`:

```vue
<template>
  <div v-for="(_, i) in form.values.todos" :key="i" class="row">
    <input v-register="form.register(`todos.${i}.title`)" />
    <input v-register="form.register(`todos.${i}.done`)" type="checkbox" />
    <button type="button" @click="form.remove('todos', i)">−</button>
  </div>
  <button type="button" @click="form.append('todos', { title: '', done: false })">Add todo</button>
</template>
```

The `i` keyed loop pattern is fine for static lists. For lists where items can reorder, use a stable per-row identifier instead; see [Performance](/docs/server-and-ssr/performance) for the keying discussion.

## Field-array helpers

Seven helpers cover the common mutations:

| Method                                | What it does                    |
| ------------------------------------- | ------------------------------- |
| `form.append('path', element)`        | Push to the end.                |
| `form.prepend('path', element)`       | Unshift to the front.           |
| `form.insert('path', index, element)` | Insert at a specific index.     |
| `form.remove('path', index)`          | Remove at an index.             |
| `form.swap('path', i, j)`             | Swap two positions.             |
| `form.move('path', from, to)`         | Move an element to a new index. |
| `form.replace('path', elements[])`    | Replace the whole array.        |

All seven preserve sibling state where applicable (touched, focused, errors), reorder field-state to follow the items, and record one undo position per call; see [Field-array mutations](/docs/writing-and-mutating/field-arrays) for the full reference.

## `z.tuple([a, b, c])`: fixed length

```ts
const schema = z.object({
  dateRange: z.tuple([z.date(), z.date()]),
})

const form = useForm({
  schema,
  defaultValues: { dateRange: [new Date(), new Date()] },
})
```

Each position is its own slot with its own type:

```ts
form.values.dateRange[0] // Date
form.values.dateRange[1] // Date
form.register('dateRange.0') // path autocomplete narrows to position 0
form.register('dateRange.1') // position 1
form.register('dateRange.2') // type error (tuple has only 2 positions)
```

Tuples don't expose the field-array helpers; `form.append('dateRange', new Date())` is a type error because the tuple has a fixed shape. For mixed-shape sequences (a `[string, number, boolean]`), tuples are how you say "exactly this layout, in this order."

## When to pick which

- **Array**: when the list grows and shrinks at runtime, and every element has the same shape. Todos, tags, line items, attachments.
- **Tuple**: when the sequence has a fixed length and the positions may differ in type or meaning. Date ranges, coordinate pairs, RGB color triples, [latitude, longitude] tuples.

If you find yourself reaching for `z.array(z.union([a, b]))` to mean "exactly one of A followed by exactly one of B," reach for a tuple instead; `z.tuple([a, b])` says the same thing, more precisely.

## Errors land where the schema expects

Errors per element:

```ts
form.errors.todos[0]?.title // ValidationError[] for todos[0].title
form.errors.dateRange[1] // ValidationError[] for dateRange[1]
```

The aggregate `form.meta.errors` flattens every leaf's errors into a single list. Cross-element refinements (a `.refine` on the whole array) land on the array path itself rather than a specific element. `form.errors.todos[0]` (note the `[0]` index after the `.errors.todos` access) reads the first error attached to the array, which is the cross-element one.

## Async element-level refinements

Element-level async refinements work the way you'd expect. Each element validates independently:

```ts
const schema = z.object({
  skus: z.array(
    z.string().refine(async (sku) => await api.checkSku(sku), {
      message: 'Unknown SKU',
    })
  ),
})

// form.errors.skus[2]: pending until the async refinement settles
// for that element
```

See [Async refinements](/docs/validation/async-refinements) for cancellation semantics and the "pending" state.

## Where to next

- [Field-array mutations](/docs/writing-and-mutating/field-arrays): the seven helpers in depth, with element keying patterns.
- [Records & maps](/docs/schemas/records): when the keys aren't numeric indices.
- [Nested objects](/docs/schemas/nested-objects): fixed-shape composition vs. variable-length sequences.

_Source: https://attaform.dev/docs/schemas/arrays-and-tuples_

---

# Records & maps

> Dictionaries when the keys aren't known at schema-write time: `z.record` for the common case, `z.map` when you need the `Map<K, V>` primitive and structured-clone fidelity.


The demo binds a record of per-user preferences. The keys are user IDs you don't know at compile time, so the schema declares `z.record(z.string(), z.boolean())`, a string-keyed dictionary of booleans. Each key binds dynamically via `register(\`prefs.${userId}\`)`.


## `z.record(keySchema, valueSchema)`

```ts
const schema = z.object({
  prefs: z.record(z.string(), z.boolean()),
  scores: z.record(z.string(), z.number()),
})

const form = useForm({
  schema,
  defaultValues: { prefs: {}, scores: {} },
})
```

Each value gets a dynamic-key path segment:

```ts
form.values.prefs['user-42'] // boolean | undefined
form.register('prefs.user-42') // path autocomplete; the key segment is dynamic
form.errors.prefs['user-99'] // ValidationError[] (empty when no errors)
```

The key schema constrains what's valid; the value schema validates each entry:

```ts
// String keys are the common case
z.record(z.string(), z.boolean())

// Constrained keys
z.record(z.enum(['admin', 'editor', 'viewer']), z.boolean())

// Number-valued
z.record(z.string(), z.number().min(0).max(100))
```

`form.values.prefs[key]` reads `boolean | undefined`; the `| undefined` comes from `noUncheckedIndexedAccess`, the same way array index reads do. Reach for `??` defaults at the call site:

```ts
const checked = form.values.prefs[userId] ?? false
```

## Mutating records

Records don't expose field-array helpers (`append` / `remove` / etc.); they're keyed dictionaries, not ordered sequences. Mutate them via `setValue` directly:

```ts
form.setValue(`prefs.${userId}`, true) // set / overwrite one entry
form.setValue('prefs', { ...form.values.prefs, [userId]: true }) // whole-record merge
```

To flag a record entry blank, reach for `unset`:

```ts
import { unset } from 'attaform'
form.setValue(`prefs.${userId}`, unset)
```

`unset` at a record entry writes the value schema's slim default at the path and adds the path to `form.blankPaths`. The bound input renders empty, and a required value schema surfaces `atta:no-value-supplied` reactively. To clear the whole record back to `{}`, pass `unset` at the record container: `form.setValue('prefs', unset)`.

## `z.map(keySchema, valueSchema)`

Map is the primitive `Map<K, V>`, distinct from records (which are plain JS objects):

```ts
const schema = z.object({
  scoresByUser: z.map(z.string(), z.number()),
})

const form = useForm({
  schema,
  defaultValues: { scoresByUser: new Map() },
})

form.values.scoresByUser // Map<string, number>
form.values.scoresByUser.get('user-42') // number | undefined
```

The runtime treats `Map` as a leaf container; `form.values.scoresByUser` returns the live `Map`, and you call its methods directly. Use map (over record) when:

- You need `Map`-specific semantics: insertion order, key types beyond strings, or `.size` as an O(1) read.
- The form persists to `'indexeddb'` and you want structured-clone fidelity. `JSON.stringify` flattens a `Map` to `{}`; structured clone preserves it.

Records are the right call for serialization-friendly dictionaries; maps are right when you need the primitive.

## Iterating in templates

For records, iterate over `Object.entries`:

```vue
<template>
  <label v-for="[userId, enabled] in Object.entries(form.values.prefs)" :key="userId">
    <input v-register="form.register(`prefs.${userId}`)" type="checkbox" :checked="enabled" />
    {{ userId }}
  </label>
</template>
```

For maps, iterate the `Map` directly:

```vue
<template>
  <div v-for="[userId, score] in form.values.scoresByUser" :key="userId" class="row">
    <span>{{ userId }}</span>
    <input v-register="form.register(`scoresByUser.${userId}`)" type="number" />
  </div>
</template>
```

The template renders re-run when the underlying record / map updates because `form.values` proxies through the reactivity layer.

## Errors per entry

Errors land at the keyed path, the same as array elements:

```ts
form.errors.prefs['user-42'] // ValidationError[] (empty when no errors)
form.errors.scoresByUser['user-99'] // (works for maps too)
```

The aggregate `form.meta.errors` flattens every entry's errors into one list, in path order.

## When to pick which

- **`z.record(z.string(), V)`**: string-keyed dictionaries serialized as JSON. The default choice.
- **`z.record(z.enum([...]), V)`**: keys constrained to a small set. Compile-time autocomplete on the keys.
- **`z.map(K, V)`**: when you need `Map`'s insertion order, non-string keys, or structured-clone fidelity for IndexedDB persistence.
- **`z.object({ … })`**: when the keys are fixed and known at schema-write time. Records are for the dynamic case.

When the record is the entire form rather than a field inside one, reach for a [dictionary form](/docs/schemas/dictionary-forms): the `z.record` becomes the schema root, `form.values` is the map itself, and `form.record()` iterates it.

## Where to next

- [Dictionary forms](/docs/schemas/dictionary-forms): a `z.record` schema as the form root, not just a field inside an object.
- [Arrays & tuples](/docs/schemas/arrays-and-tuples): numeric-keyed sequences; the other half of the "many-items" picture.
- [Nested objects](/docs/schemas/nested-objects): fixed-shape composition; the alternative when keys are known.
- [`unset`, the blank-anywhere sentinel](/docs/writing-and-mutating/unset): how to flag a single record entry blank, or wipe the whole record back to `{}`.

_Source: https://attaform.dev/docs/schemas/records_

---

# Dictionary forms

> When the form _is_ a map, make the map the root. A `z.record` schema at the top level gives you a dictionary form: `form.values` is the map itself, and `form.record()` iterates its entries.


The demo is a team roster keyed by member id. The ids are data you only learn at run time, so the schema root is a `z.record(z.string(), …)`, a string-keyed dictionary of members. The whole form is that map: edit a member, add one, drop one, and watch `form.values` track it below.


## The schema

A dictionary form declares a `z.record` schema as the root, not nested under a key. The key schema constrains what counts as a valid key; the value schema validates each entry:

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

const schema = z.record(
  z.string(),
  z.object({ role: z.enum(['admin', 'editor', 'viewer']), tier: z.number() })
)

const form = useForm({ schema })
```

There is no wrapper key. `form.values` reads as `Record<string, { role: 'admin' | 'editor' | 'viewer'; tier: number }>`, the map itself.

## `form.values` is the dictionary

Because the record is the root, `form.values` is the whole map, and entries bind through their own key:

```ts
form.values() // the whole map: Record<string, { role; tier }>
form.values()['ada'] // one entry, or undefined
form.register('ada.role') // bind an entry sub-field
form.errors['ada']?.['tier'] // ValidationError[] for that entry's tier
```

The `| undefined` on an entry read comes from `noUncheckedIndexedAccess`, the same way a record field reads anywhere else. Reach for `??` defaults at the call site when you need one.

## Iterating with `form.record()`

`form.record()` with no argument is the root entry view: one [`FieldState`](/docs/reading-the-form/fields) per entry, keyed by the entry's own key. It is the root counterpart of [`form.record(path)`](/docs/reading-the-form/record), which views a nested record. The keys come from the form, so you render whatever entries exist without keeping a parallel list of your own:

```vue
<template>
  <div v-for="(member, id) in form.record()" :key="id">
    <label>{{ id }}</label>
    <input v-register="form.register(`${id}.tier`)" type="number" />
    <small v-if="member.showErrors">{{ member.firstError?.message }}</small>
  </div>
</template>
```

Each `member` is a live `FieldState`, the same surface [`form.fields`](/docs/reading-the-form/fields) exposes, so every read stays current as the user types. Binding still flows through [`form.register`](/docs/binding-inputs/v-register) with the entry path, which the key supplies.

## Adding, editing, and removing entries

A dictionary form carries its own keys, so you grow and shrink it through [`setValue`](/docs/writing-and-mutating/set-value). Editing and adding are ordinary path writes:

```ts
form.setValue('ada.tier', 4) // edit one entry's field
form.setValue('mae', { role: 'viewer', tier: 1 }) // add a key that isn't there yet
```

Removing is the one case the root changes. A nested record drops a key by rewriting its container path; a record root has no container path, so you rewrite the form itself. Passing a single argument to `setValue` is a whole-form write, and for a dictionary form the whole form is the map:

```ts
const next = { ...form.values() }
delete next['ada']
form.setValue(next) // write the map back without that key
```

Surviving entries keep their field states and component instances across the write; only the dropped row unmounts.

## Defaults

A bare record root defaults to an empty map, ready to grow:

```ts
const form = useForm({ schema })
form.values() // {}
```

Seed initial entries with `defaultValues`, the same shape as the form value:

```ts
const form = useForm({
  schema,
  defaultValues: { ada: { role: 'admin', tier: 3 } },
})
```

## When the keys are fixed, reach for an object

Dictionary forms are for keys you learn at run time. When the keys are known at schema-write time, a `z.object` root is the better fit: fixed keys, a distinct type per field, and compile-time autocomplete on each one. The two compose freely. An object form can hold a `z.record` field (see [Records & maps](/docs/schemas/records)), and a dictionary form's value schema can be any Zod schema, including objects, arrays, and nested records.

## Where to next

- [Records & maps](/docs/schemas/records): `z.record` as a field inside an object form, plus the `z.map` primitive.
- [`record`](/docs/reading-the-form/record): the entry view, `form.record(path)` for a nested record and `form.record()` for the root.
- [`setValue`](/docs/writing-and-mutating/set-value): the writes that grow, edit, and shrink a dictionary.
- [Nested objects](/docs/schemas/nested-objects): fixed-shape composition, the alternative when the keys are known.

_Source: https://attaform.dev/docs/schemas/dictionary-forms_

---

# Nested objects

> Schemas compose by nesting: one `z.object` inside another. The proxy descends through dot-paths so `form.values.profile.name`, `form.errors.profile.name`, and `register('profile.name')` all work the way you'd expect.


This page is code-only; every other demo in the docs already nests objects. The shape, the proxy, and the path semantics are best understood through the snippets below; reach for a real demo on [Arrays & tuples](/docs/schemas/arrays-and-tuples) (which composes arrays of nested objects) or [Discriminated unions](/docs/schemas/discriminated-unions) (which nests variant objects inside the outer union) when you want to see it live.

## The shape

```ts
const schema = z.object({
  profile: z.object({
    name: z.string().min(1, 'Name is required'),
    bio: z.string().optional(),
  }),
  address: z.object({
    line1: z.string().min(1, 'Street is required'),
    city: z.string(),
    postalCode: z.string(),
  }),
})

const form = useForm({ schema })
```

Each leaf gets its own path:

```ts
form.values.profile.name // string
form.values.address.city // string
form.register('profile.name') // path autocomplete narrows the union
form.errors.address.postalCode // readonly ValidationError[]
```

## The proxy descends transparently

`form.values`, `form.errors`, and `form.fields` are all proxies; `form.values.profile.name` resolves through one descend per dot segment. The reactivity tracks at the path level, not the leaf level: re-running templates only fires for paths whose values changed.

```vue
<template>
  <fieldset>
    <legend>Profile</legend>
    <label>
      Name
      <input v-register="form.register('profile.name')" />
      <em v-if="form.fields.profile.name.showErrors">
        {{ form.fields.profile.name.firstError?.message }}
      </em>
    </label>
    <label>
      Bio
      <textarea v-register="form.register('profile.bio')" rows="3" />
    </label>
  </fieldset>
</template>
```

The pattern scales to arbitrary depth. `register('a.b.c.d.e')` works; the type inference walks the schema's shape one segment at a time and narrows along the way.

## Object-level vs. leaf-level errors

```ts
const schema = z
  .object({
    password: z.string().min(8),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: 'Passwords must match',
    path: ['confirm'],
  })
const form = useForm({ schema })
```

A `.refine` on the outer object attaches its error to whatever `path` you specify. With no `path`, the error lands on the object root, accessible at `form.errors.<object-path>` directly. With a `path`, it lands on the named leaf, usually preferable for inline display, since the field component reads from `form.errors.confirm` either way.

For cross-field validations (password confirmation, address-postal-code matching, conditional-required dependencies), the `.refine` + `path: ['leafName']` pattern is the canonical move.

When a no-path refine lands on a nested object's own bucket, isolate it from the fieldset's child errors with the own-bucket accessor on its FieldState:

```vue
<em v-if="form.fields.profile.firstOwnError">
  {{ form.fields.profile.firstOwnError.message }}
</em>
```

`form.fields.profile.errors` rolls up the whole subtree (the object's own error plus every child's); `form.fields.profile.ownErrors` is the object's own bucket alone. See [reading FieldState](/docs/reading-the-form/fields) for the full own-versus-subtree axis.

## Per-nested defaults

Each nested object can have its own `.default()`:

```ts
const schema = z.object({
  ui: z
    .object({
      theme: z.string().default('light'),
      density: z.string().default('comfortable'),
    })
    .default({ theme: 'light', density: 'comfortable' }),
})

const form = useForm({ schema })

form.values.ui.theme // 'light' (inner default applied)
form.values.ui.density // 'comfortable'
```

The outer `.default({...})` is the fallback when the whole object is missing; the inner `.default()` calls fire per-leaf if the outer default is absent. In practice, defaulting at the leaves is enough; the runtime's slim-default synthesis handles missing objects.

## Resetting a subtree

`resetField` walks the path and re-seeds the subtree from the schema:

```ts
form.resetField('profile') // re-seed profile.name + profile.bio from schema
form.resetField('profile.name') // re-seed just one leaf
```

The cleared subtree's field state (touched, focused, etc.) reverts to the post-mount baseline; cross-subtree state (sibling paths) stays where it is.

## Subtree-scoped operations

Most operations accept a path argument that scopes them to a subtree:

```ts
form.validate('profile') // validate just profile.* leaves
form.validateAsync('address') // async-validate the address subtree
form.resetField('profile') // re-seed just the profile subtree
form.history.undo() // global to the whole form (no subtree variant)
```

Subtree-scoping keeps "Save section" / "Validate this step" wizard patterns cheap: no full-form re-traversal when you only care about one branch.

## When deeply nested objects feel wrong

If a schema reaches four or five levels deep and feels unwieldy, two patterns to consider:

- **Flatten the schema.** `address.line1` could become `addressLine1` if the grouping was structural rather than semantic. The binding code stays the same shape.
- **Split into sub-forms.** Two `useForm` calls with separate keys, composed via [`injectForm`](/docs/cross-cutting-state/inject-form) or [`useWizard`](/docs/multistep/use-wizard). Per-form history and validation; one parent component coordinating.

Both are escape hatches; the proxy doesn't have a depth limit, and the type inference holds at every level. But deeply-nested schemas often signal a structural-vs.-semantic mismatch worth a second look.

## Where to next

- [Arrays & tuples](/docs/schemas/arrays-and-tuples): variable-length composition; the natural counterpart to nested objects.
- [Records & maps](/docs/schemas/records): when the nested keys are dynamic, not fixed at schema-write time.
- [`injectForm`](/docs/cross-cutting-state/inject-form): when nested-object sub-trees outgrow one component and want to live as sub-forms.

_Source: https://attaform.dev/docs/schemas/nested-objects_

---

# AbstractSchema

> Attaform is schema-agnostic at the core. Wire any schema library (Valibot, ArkType, Effect-Schema, a hand-rolled validator) into the runtime by implementing the `AbstractSchema` contract.


This page is the contract reference. The Zod adapters under `attaform/zod` and `attaform/zod-v3` are reference implementations; read their source when you need a concrete example of any of the methods below.

## The contract

```ts
type AbstractSchema<Form, GetValueFormType = Form> = {
  // Identity
  fingerprint(): string

  // Defaults
  getDefaultValues(config): DefaultValuesResponse<Form>
  getDefaultAtPath(path: Path): unknown

  // Shape introspection
  arrayShapeAtPath(path: Path): number | null | undefined
  isLeafAtPath(path: Path): boolean
  isRequiredAtPath(path: Path): boolean
  getSchemasAtPath(path: Path): AbstractSchema<unknown, GetValueFormType>[]
  getSlimPrimitiveTypesAtPath(path: Path): Set<SlimPrimitiveKind>
  getUnionDiscriminatorAtPath(path: Path): UnionDiscriminatorContext | undefined

  // Validation
  validateAtPath(
    data: unknown,
    path: Path | undefined,
    options?: ValidateOptions
  ): MaybePromise<ValidationResponse<Form>>

  // Optional hooks
  getFieldMetaAtPath?(path: Path): ResolvedFieldMeta
  needsAsyncValidation?(): boolean
}
```

Twelve required methods. Two optional hooks. The runtime fills in sensible fallbacks for the optional hooks, so omit them when your library doesn't model the feature.

## Identity

### `fingerprint()`

Structural signature of the schema. Two schemas with the same shape return the same string; different shapes return different strings. Used to:

- Catch shared-key mismatches in dev (two `useForm({ key: 'x' })` calls with different schemas warn).
- Key persisted drafts so schema changes auto-invalidate stale drafts.

Must NOT throw. If it does, Attaform catches the exception, logs it via `console.error` in dev, and skips the shared-key mismatch check for that call. An opaque stable string (`'custom-adapter:v1'`) is a valid fallback; opaque fingerprints disable schema-change auto-invalidation for persisted drafts (the key never changes), so prefer a real structural hash if your library exposes the metadata.

## Defaults

### `getDefaultValues(config): DefaultValuesResponse<Form>`

Returns `{ data, errors, success, formKey }`. Called at form creation and on `reset()`. The `config` argument carries `useDefaultSchemaValues`, `constraints`, and `strict` flags.

### `getDefaultAtPath(path: Path): unknown`

Returns the schema-prescribed default at a structured path. The runtime calls this on every `setValue` to fill structural gaps:

- Empty path → whole-form default.
- Object property → property's default.
- Array index → element default.
- Tuple position → position's default.
- Optional / nullable around a structural inner → inner default.
- Optional / nullable around a primitive → `undefined` / `null` (preserve the wrapper's semantic).
- `.default(x)` wrapper → `x`.

Return `undefined` for paths that don't exist in the schema. Must NOT throw; the runtime skips filling on `undefined`.

## Shape introspection

### `arrayShapeAtPath(path: Path): number | null | undefined`

- `number`: tuple's fixed length.
- `null`: unbounded array.
- `undefined`: non-array path.

The runtime caches the answer to skip per-write probe loops on array writes.

### `isLeafAtPath(path: Path): boolean`

`true` for primitive paths, `false` for object / array / map / set containers. Drives the proxy's descend-vs-terminate decision; reserved leaf-prop names (`dirty`, `errors`, `valid`, `label`, …) inject only at the FieldState terminal.

### `isRequiredAtPath(path: Path): boolean`

`true` when the leaf is required (no `.optional()` / `.nullable()` / `.default()` / `.catch()` wrapper around it). Used by the blank validation augmentation to raise `'No value supplied'` for unfilled required fields.

### `getSchemasAtPath(path: Path): AbstractSchema[]`

List of candidate sub-schemas at `path`. Multiple results are expected for discriminated-union branches. `path` is a canonical `Segment[]`. Return `[]` if your library doesn't model union-style multi-candidates.

### `getSlimPrimitiveTypesAtPath(path: Path): Set<SlimPrimitiveKind>`

Set of primitive `typeof`-style kinds the path's leaf accepts at write time (`'string'`, `'number'`, `'boolean'`, `'bigint'`, …). Drives the slim-primitive write gate. Return a permissive fallback (`new Set(['string', 'number', 'boolean', 'bigint', 'symbol', 'date', 'undefined', 'null'])`) for paths the schema doesn't declare; over-rejecting writes breaks dynamic / SSR rehydration.

### `getUnionDiscriminatorAtPath(path: Path): UnionDiscriminatorContext | undefined`

For discriminated-union containers, return `{ discriminatorKey, getVariantDefault }`. Used by the variant-reshape pipeline so a discriminator-key write swaps the active branch without leaking old keys. Return `undefined` if your library doesn't model DUs.

## Validation

### `validateAtPath(data, path?, options?): MaybePromise<ValidationResponse>`

Returns `MaybePromise<ValidationResponse>`. `path` is a `Segment[]` or `undefined` (whole-form validation). Honor `options.sync` when the schema is sync-capable; the runtime uses it to batch error writes inside DU variant reshape.

Must NOT throw. Return `{ success: false, errors }` for validation failures.

## Optional hooks

### `getFieldMetaAtPath(path: Path): ResolvedFieldMeta` _(optional)_

Resolves schema-attached metadata (label, description, placeholder, full payload). Drives `form.fields(p).label` / `.description` / `.placeholder` / `.meta`. Omit if your library doesn't model metadata yet, and consumers see humanized fallbacks.

### `needsAsyncValidation(): boolean` _(optional)_

Return `true` if `validateAtPath` may need a Promise to surface every error this schema can produce. The runtime uses this to decide whether to schedule a one-shot construction-time async pass.

## A minimal Valibot-ish adapter

Assume your library exposes:

- `schema.defaultValues()` returning the schema's typed defaults.
- `schema.parse(data)` returning `{ success: true, data }` or `{ success: false, issues: { path: string[]; message: string }[] }`.

```ts
import type {
  AbstractSchema,
  DefaultValuesResponse,
  GenericForm,
  SlimPrimitiveKind,
  ValidationError,
  ValidationResponse,
} from 'attaform/abstract'

const PERMISSIVE: ReadonlySet<SlimPrimitiveKind> = new Set<SlimPrimitiveKind>([
  'string',
  'number',
  'boolean',
  'bigint',
  'symbol',
  'date',
  'undefined',
  'null',
])

export function myLibAdapter<F extends GenericForm>(schema: MyLibSchema<F>): AbstractSchema<F, F> {
  return {
    fingerprint() {
      return schema.signature?.() ?? 'my-lib:v1'
    },

    getDefaultValues({ constraints }): DefaultValuesResponse<F> {
      const defaults = schema.defaultValues()
      const merged = mergeDeepPartial(defaults, constraints)
      return { data: merged, errors: undefined, success: true, formKey: '' }
    },

    getDefaultAtPath(path) {
      return walkSchemaToDefault(schema, path)
    },

    arrayShapeAtPath(path) {
      return walkSchemaToArrayShape(schema, path)
    },

    isLeafAtPath(path) {
      const kinds = walkSchemaToSlimPrimitives(schema, path)
      if (kinds === undefined) return false
      return ![...kinds].some((k) => k === 'object' || k === 'array' || k === 'map' || k === 'set')
    },

    isRequiredAtPath(path) {
      const leaf = walkSchemaToLeaf(schema, path)
      return leaf?.isRequired ?? false
    },

    getSchemasAtPath() {
      return []
    },

    getSlimPrimitiveTypesAtPath(path) {
      return walkSchemaToSlimPrimitives(schema, path) ?? PERMISSIVE
    },

    getUnionDiscriminatorAtPath() {
      return undefined
    },

    validateAtPath(data, path) {
      const result = path !== undefined ? schema.parseAtPath(data, path) : schema.parse(data)

      if (result.success) {
        return { success: true, data: result.data, errors: [], formKey: '' }
      }

      const errors: ValidationError[] = result.issues.map((issue) => ({
        path: issue.path,
        message: issue.message,
        code: `my-lib:${issue.code ?? 'unknown'}`,
        formKey: '',
      }))

      return { success: false, errors, data: undefined, formKey: '' }
    },
  }
}
```

Wire your adapter through `useAbstractForm`:

```ts
import { useAbstractForm } from 'attaform/abstract'
import { myLibAdapter } from './my-adapter'

const form = useAbstractForm({ schema: myLibAdapter(mySchema) })
```

## Zod-v3 vs. Zod-v4: an introspection asymmetry

Worth knowing if you're studying the reference implementations: the v4 adapter exports `kindOf`, `ZodKind`, and `assertZodVersion` for runtime introspection of Zod nodes; the v3 adapter exports `isZodSchemaType` but not the broader set. Both adapters implement the full `AbstractSchema` contract; the difference is in the consumer-facing diagnostic helpers above the contract surface. If you're forking a Zod adapter as a starting point, the v4 source is the richer reference; the v3 source is the leaner one.

## Where to next

- [The schema contract](/docs/schemas/contract): the high-level mental model `AbstractSchema` implements.
- [Types reference](/docs/reference/types): every type the contract references.
- [Entry-point reference](/docs/reference/entry-points): which subpath ships `AbstractSchema` (`attaform/abstract`).

_Source: https://attaform.dev/docs/schemas/abstract-schema_

---

# The form

> Every form on the page is reactive and supports reading, mutations, validation, and submission handling, all typed against your schema.


One call, one form. `useForm` hands back a reactive form that already knows your schema's shape, types, defaults, and validation. Everything below is a property of that single `form` handle: drillable value reads, per-leaf field state, error arrays, the submit handler, mutators. Wire one input, then reach for whatever else you need on the same `form`.

```ts
const schema = z.object({
  email: z.email(),
  age: z.number(),
})

const form = useForm({ schema })
```

The demo below renders one form against an email + name schema. Type, blur, submit, reset; the panels on the right read the same `form` you wire into the inputs.


## Reactive reads

```ts
form.values // drillable proxy: form.values.email
form.fields // per-leaf FieldState: form.fields.email.touched
form.errors // per-path errors: form.errors.email
form.meta // submit / valid / pending aggregates
```

Every read inside a reactive scope (template, `computed`, `watchEffect`) is tracked. Vue re-runs the consumer when the underlying storage changes.

## Directive surface

```ts
form.register('email')
```

`register` returns the RegisterValue the `v-register` directive consumes. Hand it to any native input: text, number, select, checkbox, radio, textarea, file.

## Submission

```ts
const onSubmit = form.handleSubmit(async (values) => {
  await api.signup(values)
})
```

`handleSubmit` gates dispatch on validation. Returns a handler ready for `<form @submit>` (it calls `preventDefault` for you, so `.prevent` is redundant).

## Per-field writes

```ts
import { unset } from 'attaform'

form.setValue('email', 'new@example.com')
form.setValue('age', unset) // flag any path blank by passing the sentinel
form.resetField('email')
```

## Form-level operations

```ts
form.reset() // re-seed every path from defaultValues
form.clear() // wipe every path to its falsy-for-type baseline
```

Every write path runs the same validation, dirty-tracking, and history pipeline.

## Validation

```ts
form.validate() // sync pass
form.validateAsync() // awaits async refinements
```

Validators emit into `form.errors` on completion. The same pipeline runs inside [`handleSubmit`](/docs/submitting/handle-submit) before your success callback fires, so reach for `validate` directly only when you need a check outside the submit cycle.

## Where to next

- [`values`](/docs/reading-the-form/values): drillable reads.
- [`fields`](/docs/reading-the-form/fields): per-leaf state, validation, and DOM handles.
- [`errors`](/docs/reading-the-form/errors): per-path error reads.
- [`meta`](/docs/reading-the-form/meta): the form-level aggregation plus the submission cycle.
- [`toRef`](/docs/reading-the-form/to-ref): the ref-shaped escape hatch.
- [The `v-register` directive](/docs/binding-inputs/v-register): the bind layer.

_Source: https://attaform.dev/docs/reading-the-form/the-form_

---

# `values`

> A reactive Proxy keyed by your schema's paths. Drill anywhere, read anything, let Vue track it.


`form.values` is the reactive read surface for everything the form holds. The Proxy mirrors your schema's shape: every key resolves to a schema path, every container descends as its own sub-Proxy, and every read inside a reactive scope subscribes for re-renders. Reach for any leaf or container, anywhere; the value you read is always the live one. The exact concrete shape (how defaults, `.optional()`, `.nullable()`, and preprocess land) is covered in [How values are stored](/docs/schemas/storage-shape).


## Leaf and container reads

```ts
const schema = z.object({
  profile: z.object({
    name: z.string(),
    email: z.email(),
  }),
  age: z.number(),
})

const form = useForm({ schema })

// Leaf reads
form.values.profile.name
form.values.age

// Container reads return the nested object
form.values.profile // { name: '', email: '' }
```

## Reactivity

`form.values` is implemented as a deep Proxy. Reads inside a `computed`, `watchEffect`, or template render are tracked; the consumer re-runs when the underlying storage changes:

```vue
<template>
  <p>Hello, {{ form.values.profile.name }}!</p>
</template>
```

Vue's auto-unwrap means you don't write `.value`; the Proxy presents as a plain object surface.

## Reading in templates

`form.values.<path>` is a plain expression in templates, conditionals, and bindings:

```vue
<template>
  <button :disabled="!form.values.profile.email">Send invite</button>
  <p v-if="form.values.age >= 18">Adult plan available.</p>
  <span class="badge">Saving as {{ form.values.profile.firstName || 'guest' }}</span>
</template>
```

Each read subscribes the surrounding render so updates flow without manual `watch` or `computed` wiring.

## Writes never go through the Proxy

`form.values` is read-only. Changes to storage flow through methods on `form` (`setValue`, `clear`, `reset`, `resetField`, and the field-array helpers `append`, `prepend`, `insert`, `remove`, `swap`, `move`, `replace`) or through inputs bound with `v-register`. Every write hits the same validation, dirty-tracking, and history pipeline; assigning to `form.values.email` directly throws in dev.

Optional leaves (those whose schema admits `undefined`, e.g. `z.string().optional()`) return to the absent state when the user clears the bound input. This keeps the `.optional()` semantic reachable from the DOM: a user who types invalid text into an optional field and then clears it sees storage flip back to `undefined` and the validation error clears too. Required leaves keep `''` (or the slim default for non-strings) on clear.

## Where to next

- [`fields`](/docs/reading-the-form/fields): the same reads plus per-leaf state.
- [`errors`](/docs/reading-the-form/errors): paired error reads.
- [`toRef`](/docs/reading-the-form/to-ref): the ref-shaped escape hatch for path-precise interop.
- [`setValue`](/docs/writing-and-mutating/set-value): the write counterpart.
- [How values are stored](/docs/schemas/storage-shape): the conceptual model behind this surface.
- [The form](/docs/reading-the-form/the-form): every other reactive read.

_Source: https://attaform.dev/docs/reading-the-form/values_

---

# `fields`

> A reactive Proxy keyed by schema paths. Every leaf surfaces a 33-property FieldState: state bits, value reads, validation reads, DOM handles, and schema metadata, all in one snapshot the form keeps in sync as users interact.


`form.fields.<path>` is the per-leaf companion to [`form.values.<path>`](/docs/reading-the-form/values). Where `values` answers "what's at this path?", `fields` answers everything else: has the user touched it, is it focused, is it dirty, what errors does it carry, should we be showing them yet, which DOM element is bound. Type into the email input, blur it, refocus, submit. Every cell in the demo's panel updates live, and the schema metadata at the bottom comes from `withMeta(...)` on the schema itself.


## Drillable Proxy

`form.fields` mirrors `form.values`' shape: a Proxy keyed by schema paths. Reach any leaf:

```ts
const schema = z.object({
  profile: z.object({
    name: z.string(),
    email: z.email(),
  }),
  age: z.number(),
})

const form = useForm({ schema })

form.fields.profile.name.touched
form.fields.profile.email.firstError?.message
form.fields.age.dirty
```

Container paths (`form.fields.profile`) keep drilling: a container is a navigation node, not a FieldState, so it carries no `dirty` or `errors` of its own on the dot surface. When you want a container's rolled-up state, call it. `form.fields('profile')` returns a FieldState whose `dirty` is `true` if any leaf under `profile` is dirty, and whose `errors` flatten every descendant error.

### Absence reads `undefined`

Dot and index access is pure navigation, so a node that isn't there right now reads `undefined`, never a phantom you can keep chaining off. Three hops are dynamic, where the live shape decides whether the node exists:

- an out-of-bounds array index, `form.fields.tags[99]`,
- a record key the data doesn't hold, `form.fields.byId.missing`,
- a discriminated-union key whose variant isn't active, `form.fields.cargo.permitNumber` while the `general` variant is live.

The types say exactly what the runtime does. Each dynamic hop is `FieldState<T> | undefined`, so TypeScript asks for a `?.` right where a read might come back empty, and a truthy check never lies:

```ts
form.fields.tags[0]?.value
form.fields.cargo.permitNumber?.firstError?.message
```

A declared `optional` field is always present, because the schema names it: `form.fields.profile.nickname.value` is a real FieldState whose `value` is `undefined`, not an absent node. Register it, read it, reveal it, no guard required.

### A whole-array binding reads through the call-form

Point one `register` at an `<input type="file" multiple>` and it writes the entire `File[]` through a single array path. The dot surface descends into elements, so that array field's own busy and transform state reads through the call-form:

```ts
form.fields('links').busy
form.fields('links').transformError
```

## What FieldState carries

Each leaf exposes a 33-property `FieldState` object. The properties fall into five jobs:

### State bits

The reactive lifecycle of a field: how it got here, what it's doing now.

| Property                  | Type              | Meaning                                                                                                     |
| ------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------- |
| `pristine`                | `boolean`         | `true` until the value diverges from the original.                                                          |
| `dirty`                   | `boolean`         | Inverse of `pristine`.                                                                                      |
| `focused`                 | `boolean \| null` | `true` while the element is focused; `null` while disconnected.                                             |
| `blurred`                 | `boolean \| null` | Inverse of `focused` when connected; `null` while disconnected.                                             |
| `touched`                 | `boolean`         | `true` after the first blur; survives reset cycles.                                                         |
| `interacted`              | `boolean`         | `true` after the user's first value edit through `v-register`; survives reset cycles.                       |
| `blurredAfterInteraction` | `boolean`         | `true` after the first blur that follows an edit (edited, then left); drives the default error-reveal gate. |
| `connected`               | `boolean`         | `true` while at least one element is bound via `v-register`.                                                |
| `blank`                   | `boolean`         | `true` while the leaf reads as empty per the [blank predicate](/docs/validation/showing-errors).            |
| `updatedAt`               | `string \| null`  | ISO timestamp of the last write; `null` until first write.                                                  |

### Value reads

The data sitting at this path right now, and what it was at hydration.

| Property   | Type | Meaning                                                        |
| ---------- | ---- | -------------------------------------------------------------- |
| `value`    | `T`  | Current leaf value (same as `form.values.<path>`).             |
| `original` | `T`  | Hydration-time value; `dirty` flips when `value !== original`. |

### Validation reads

The error surface at this path: raw, ergonomic, and gated.

| Property        | Type                                          | Meaning                                                                                              |
| --------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `errors`        | `readonly ValidationError[]`                  | Every error in this path's subtree (this node plus descendants), schema-declaration order.           |
| `firstError`    | `ValidationError \| undefined`                | Sugar for `errors[0]`.                                                                               |
| `ownErrors`     | `readonly ValidationError[]`                  | Every error at this path's own bucket only, excluding descendants. On a leaf, identical to `errors`. |
| `firstOwnError` | `ValidationError \| undefined`                | Sugar for `ownErrors[0]`.                                                                            |
| `valid`         | `boolean`                                     | `errors.length === 0 && !validating`.                                                                |
| `validating`    | `boolean`                                     | `true` while a per-field validation run is in flight.                                                |
| `displayState`  | `'idle' \| 'pending' \| 'error' \| 'success'` | The single display-state verdict, resolved by [`getDisplayState`](/docs/validation/showing-errors).  |
| `showErrors`    | `boolean`                                     | `displayState === 'error'`. The display-time error gate.                                             |
| `showPending`   | `boolean`                                     | `displayState === 'pending'`. A check has run long enough to earn a spinner.                         |
| `showSuccess`   | `boolean`                                     | `displayState === 'success'`. The field has passed.                                                  |
| `showIdle`      | `boolean`                                     | `displayState === 'idle'`. Nothing to surface yet.                                                   |

Two error scopes sit side by side. `errors` and `firstError` roll up the **subtree**: a container's `errors` is non-empty whenever any descendant is invalid. `ownErrors` and `firstOwnError` read the **own bucket** at this exact path, so a container's own cross-field `.refine()` surfaces on its own without dragging in child errors. On a leaf the two scopes coincide (a leaf has no descendants), and `ownErrors` is the very same array as `errors`.

### DOM reads

Direct handles to the bound elements for imperative work: `focus()`, `scrollIntoView()`, measure positions, attach observers, anything Attaform deliberately doesn't wrap behind helpers.

| Property   | Type                     | Meaning                                    |
| ---------- | ------------------------ | ------------------------------------------ |
| `element`  | `HTMLElement \| null`    | First bound element by registration order. |
| `elements` | `readonly HTMLElement[]` | Every element bound to this path.          |

```ts
form.fields.email.element?.focus()
form.fields.email.element?.scrollIntoView({ block: 'center' })
```

### Schema metadata + identity

Schema-registered presentational hints, the path that produced this FieldState, the stable DOM ids for wiring labels and assistive-tech references, and the element identity key for iterating array elements.

| Property      | Type                            | Meaning                                                                                                                                                                        |
| ------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label`       | `string`                        | Registered label, or a humanized fallback from the path's last segment.                                                                                                        |
| `description` | `string \| undefined`           | Registered description; falls back to `schema.describe('...')` when no override.                                                                                               |
| `placeholder` | `string \| undefined`           | Registered placeholder hint.                                                                                                                                                   |
| `meta`        | `Readonly<FieldMetaPayload>`    | The full registered payload; escape hatch for consumer-augmented keys.                                                                                                         |
| `path`        | `readonly (string \| number)[]` | The path tuple that produced this FieldState.                                                                                                                                  |
| `id`          | `string`                        | Stable, SSR-safe DOM id for this field, unique across every mount on the page.                                                                                                 |
| `aria`        | `{ errorId, descriptionId }`    | Satellite ids derived from `id` for wiring error and description elements.                                                                                                     |
| `key`         | `string`                        | Allocated identity token while the field is an array element, empty otherwise. Follows the element across reorders; the `:key` for [`form.list`](/docs/reading-the-form/list). |

Register schema metadata with `withMeta` (works on Zod 3 and Zod 4) or the native `schema.register(fieldMeta, {...})` chain (Zod 4):

```ts
import { withMeta } from 'attaform'

const schema = z.object({
  email: withMeta(z.email(), {
    label: 'Email address',
    placeholder: 'you@example.com',
  }),
})
```

## Reading FieldState in templates

The display-ergonomics pairing of `firstError` plus `showErrors` is the per-field rendering pattern:

```vue
<input v-register="form.register('email')" />
<p v-if="form.fields.email.showErrors">{{ form.fields.email.firstError?.message }}</p>
```

`showErrors` is the gate; `firstError` is the message. Read them together at every error site.

## Where to next

- [`form.list`](/docs/reading-the-form/list): iterate an array as one FieldState per element, keyed by `key` so a `v-for` survives reorders.
- [`values`](/docs/reading-the-form/values): the value half of every FieldState, lifted to a form-wide Proxy.
- [`errors`](/docs/reading-the-form/errors): the per-path errors Proxy, the raw array behind `firstError`.
- [`meta`](/docs/reading-the-form/meta): the form-level aggregation, every FieldState property rolled up, plus 7 form-only reads.
- [The `v-register` directive](/docs/binding-inputs/v-register): the binding that drives `touched`, `focused`, `blurred`, and `connected`.
- [Display state and showing errors](/docs/validation/showing-errors): the predicate behind `displayState`.
- [The `blank` field-state bit](/docs/validation/blank): the lifecycle behind the `blank` cell.
- [The form](/docs/reading-the-form/the-form): every other reactive read on `form` itself.

_Source: https://attaform.dev/docs/reading-the-form/fields_

---

# `list`

> One array, one FieldState per element, in index order. Each entry carries a stable `key`, so a keyed `v-for` keeps every row attached to its element through any reorder.


`form.list(path)` is the iteration view over an array. It hands back one [`FieldState`](/docs/reading-the-form/fields) per element, in index order, and each entry carries a `key` that follows its element across every shape change. Bind that `key` to your `v-for` and Vue keeps each row's component instance, input focus, and cursor attached to the element the user is working on, even after a drag-reorder.


## Iterating an array

Reach for `list` wherever you render a repeating field. Pair it with the array index for binding and `row.key` for the `:key`:

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

  const schema = z.object({
    roster: z.array(z.string()),
  })

  const form = useForm({ schema })
</script>

<template>
  <div v-for="(row, i) in form.list('roster')" :key="row.key">
    <input v-register="form.register(`roster.${i}`)" />
    <p v-if="row.showErrors">{{ row.firstError?.message }}</p>
  </div>
</template>
```

`list` is typed against every array path in the schema, so the path autocompletes to arrays only, and each entry's type narrows to the element shape.

## Why key by `row.key`

`row.key` is an allocated identity token, not the index. It is minted once for an element and travels with it through `insert`, `remove`, `move`, and `swap`, staying distinct even when two elements hold identical values. Keying a `v-for` by the index instead ties each row to a slot, so a reorder reshuffles which DOM node and component instance render which element; a half-typed input can jump to the wrong row. Keying by `row.key` ties each row to its element, so the row a user is editing stays put when the list around it moves.

The same token is on every FieldState as [`field.key`](/docs/reading-the-form/fields), reachable through `form.fields('roster.0').key` when you need it outside an iteration.

## Each entry is a live FieldState

The entries are the same field states `form.fields` exposes, so every read stays live as the user interacts. A row carries the full surface: `row.value`, `row.errors`, `row.showErrors`, `row.firstError`, `row.touched`, and the rest.

```vue
<template>
  <ul>
    <li v-for="(row, i) in form.list('roster')" :key="row.key">
      <input v-register="form.register(`roster.${i}`)" :aria-invalid="row.showErrors" />
      <span v-if="row.showErrors" :id="row.aria.errorId">{{ row.firstError?.message }}</span>
    </li>
  </ul>
</template>
```

Binding still flows through `form.register` with the element path; `list` supplies the key and the per-row reads, and the array index supplies the register path.

## `form.fields` stays the aggregate

`form.fields('roster')` remains the single aggregated container for the whole array: one rolled-up FieldState whose `errors`, `valid`, and `touched` summarize every element at once. That is the read for an array-level message (`z.array(...).min(1)` lands there). `list` is the complementary per-element view. Reach for the aggregate when you want one verdict for the array, and for `list` when you want a row each.

## Read-only by design

The returned array is frozen. Identity is bookkept by the mutation helpers, so shape changes go through them rather than the view:

- [`append`](/docs/writing-and-mutating/field-arrays) / `prepend` / `insert` to add a row.
- `remove` to drop one, `move` / `swap` to reorder.
- `replace` to overwrite a slot with a fresh element.

Each helper replays its exact change onto the identity tokens, which is what lets `row.key` stay true across the mutation.

## `record` is the record counterpart

`list` is for arrays. For a record, whose entries are keyed rather than ordered, reach for [`record`](/docs/reading-the-form/record): it hands back a keyed object, one FieldState per entry under the entry's own key. The two split cleanly by path type, and each rejects the other at compile time.

## Where to next

- [`record`](/docs/reading-the-form/record): the record counterpart, one FieldState per entry keyed by the record's own key.
- [Field-array mutations](/docs/writing-and-mutating/field-arrays): the seven helpers that add, remove, and reorder elements.
- [`fields`](/docs/reading-the-form/fields): the per-leaf FieldState and the `key` every entry carries.
- [The `v-register` directive](/docs/binding-inputs/v-register): the binding each row's input flows through.
- [`errors`](/docs/reading-the-form/errors): the per-path errors behind `row.firstError`.

_Source: https://attaform.dev/docs/reading-the-form/list_

---

# `record`

> One record, one FieldState per entry, keyed by the entry's own key. Iterate it with `v-for="(field, key) in form.record(path)"` and bind `:key="key"`.


`form.record(path)` is the iteration view over a record. Where [`list`](/docs/reading-the-form/list) hands back an ordered array for an array path, `record` hands back a keyed object for a record path: one [`FieldState`](/docs/reading-the-form/fields) per entry, under the entry's own key. Reach for it whenever the keys are the data, set at run time rather than declared in the schema.


## Iterating a record

Declare the record on your schema, then iterate `form.record` by its key. The keys come from the form, so you render whatever entries exist without keeping a parallel list of your own:

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

  const schema = z.object({
    scoresByTeam: z.record(z.string(), z.number()),
  })

  const form = useForm({ schema })
</script>

<template>
  <div v-for="(field, key) in form.record('scoresByTeam')" :key="key">
    <label>{{ key }}</label>
    <input v-register="form.register(`scoresByTeam.${key}`)" />
    <p v-if="field.showErrors">{{ field.firstError?.message }}</p>
  </div>
</template>
```

`record` is typed against every record path in the schema (a `z.record(...)`, not a fixed-shape `z.object({ ... })`), so the path autocompletes to records only, and each entry's type narrows to the record's value shape.

## Each entry is a live FieldState

Each value in the returned object is the same field state [`fields`](/docs/reading-the-form/fields) exposes, so every read stays live as the user types. An entry carries the full surface: `field.value`, `field.errors`, `field.showErrors`, `field.firstError`, `field.touched`, and the rest. Binding still flows through [`form.register`](/docs/binding-inputs/v-register) with the entry path, which the key supplies.

## Growing and shrinking

The returned object is frozen, a read-only view. A record carries its own keys, so you grow or shrink it through [`setValue`](/docs/writing-and-mutating/set-value) at an entry path. Write a key that isn't there yet and a new entry joins the view:

```ts
form.setValue('scoresByTeam.west', 0)
```

The existing entries keep their field states and their component instances; only the new row mounts. To drop an entry, write the record back without that key.

## `form.fields` stays the aggregate

`form.fields('scoresByTeam')` remains the single aggregated container for the whole record: one rolled-up FieldState whose `errors`, `valid`, and `touched` summarize every entry at once. Reach for the aggregate when you want one verdict for the record, and for `record` when you want an entry each.

## The root record, `form.record()`

When the schema root is itself a `z.record` (a [dictionary form](/docs/schemas/dictionary-forms)), call `form.record()` with no argument for the root entry view. It hands back the same keyed object of field states, one per entry, for the form's top-level map:

```vue
<template>
  <div v-for="(member, id) in form.record()" :key="id">
    <input v-register="form.register(`${id}.tier`)" type="number" />
  </div>
</template>
```

The no-argument form is available only on a record root; on a fixed-shape object root it is a compile error, the same way the path form requires a record path. See [Dictionary forms](/docs/schemas/dictionary-forms) for the whole-form story.

## `list` is the array counterpart

For an array, reach for [`list`](/docs/reading-the-form/list), which returns an ordered FieldState array keyed by an allocated identity token that survives reorders. `record` and `list` split cleanly by path type: a record reads through `record`, an array through `list`, and each rejects the other at compile time.

## Where to next

- [`list`](/docs/reading-the-form/list): the array counterpart, one FieldState per element with reorder-stable keys.
- [Dictionary forms](/docs/schemas/dictionary-forms): a `z.record` schema as the form root, iterated with the no-argument `form.record()`.
- [Records & maps](/docs/schemas/records): declaring a `z.record(...)` schema and binding its entries.
- [`fields`](/docs/reading-the-form/fields): the per-leaf FieldState every entry carries.
- [`setValue`](/docs/writing-and-mutating/set-value): how an entry joins or leaves the record.

_Source: https://attaform.dev/docs/reading-the-form/record_

---

# `errors`

> A reactive Proxy keyed by schema paths. Every leaf carries its current error list, container reads aggregate everything underneath, and the whole tree re-renders the moment validation re-runs.


`form.errors` is the raw validation surface, paired one-to-one with `form.values` and `form.fields`. The demo seeds invalid values up front so the panels light up on mount, then updates live as you edit each field. The container panel shows the live `profile` sub-tree, the form-level panel shows the root-only errors via `form.meta.ownErrors`, and the whole-form panel shows the full sparse tree.


## Leaf reads

```ts
const schema = z.object({
  email: z.email('Enter a valid email'),
  name: z.string().min(1, 'Name is required'),
})

const form = useForm({ schema })

form.errors.email // readonly ValidationError[]
form.errors.email[0]?.message // 'Enter a valid email' | undefined
form.errors.email.length // 0 when valid
```

A static object leaf always returns an array, `readonly ValidationError[]`, empty when valid. Reads past a dynamic boundary carry `| undefined`, because the node there may be absent: a numeric array index (`form.errors.todos[3]?.title`), a record key (`form.errors.byId.missing`), or a field that only exists on an inactive discriminated-union variant. That `| undefined` is honest. Dot and index access is pure navigation, so a key the schema doesn't declare and the data doesn't hold reads `undefined`, never a stand-in proxy, and a truthy check agrees with the runtime. The one exception is a server error parked at a non-schema key: the error stores count as holding it, so it stays reachable and its message lands on the [`''` container-self sentinel](#the-sentinel-container-self-errors) (`form.errors.ghost['']`).

The first error's `.message` is what most templates render:

```vue
<template>
  <input v-register="form.register('email')" />
  <p v-if="form.errors.email.length">{{ form.errors.email[0]?.message }}</p>
</template>
```

For display ergonomics, gating by [`getDisplayState`](/docs/validation/showing-errors) and pulling the first error in one shot, reach for [`form.fields.email.firstError`](/docs/reading-the-form/fields) paired with `form.fields.email.showErrors`. The errors Proxy is the raw aggregate; the fields Proxy is the same data with display gating and `firstError` sugar layered on.

## Container reads

`form.errors` is a drillable Proxy: dot-access descends into containers (returning a sub-Proxy you can keep drilling), and the call form returns a flat aggregate at any path. The two surfaces serve different jobs:

```ts
form.errors.profile // sub-Proxy: { '': [...refines], bio: [...], ... }
form.errors('profile') // flat array: every error inside profile + container-self
form.errors() // flat array: every error in the form
form.errors([]) // flat array: same as errors(), the whole-form aggregate
form.meta.ownErrors // flat array: root-level errors only (root .refine(), form-level setErrors)
```

`form.errors()` is the cheapest "is anything wrong?" check (`form.errors().length === 0` when the form is valid). `form.errors(path)` is uniform at every depth, so `form.errors([])` is the same whole-form aggregate as `form.errors()`, the root included. For the root-level errors alone (a root `.refine()`, an imperatively-set form error) with no field errors mixed in, read `form.meta.ownErrors`, or its first via `form.meta.firstOwnError`. For aggregated counts and submission-state bits, see [`form.meta`](/docs/reading-the-form/meta). When you serialize the dot-form (`JSON.stringify(form.errors)` or `{{ form.errors }}` in a template), the Proxy materializes the live sparse tree, so you can dump the whole error state for debugging without losing structure; global errors sit under the `'[]'` key in that dump, kept distinct from every field.

### The `''` sentinel: container-self errors

A cross-field `.refine()` lives on a container, not a leaf:

```ts
const schema = z.object({
  profile: z
    .object({
      bio: z.string().max(50),
      handle: z.string(),
    })
    .refine((p) => p.bio.includes(p.handle), 'Bio must mention your handle'),
})
```

The refine's error path is `['profile']`, the container itself. To keep `form.errors.profile` readable alongside leaf errors at `['profile', 'bio']` and `['profile', 'handle']`, container-self errors land in the materialized tree under the `''` sentinel slot:

```ts
form.errors.profile[''] // refine errors on profile (and any other container-self entries)
form.errors.profile.bio // leaf errors on bio
```

`JSON.stringify(form.errors.profile)` materializes as `{ '': [refineError], bio: [maxError], handle: [...] }`. Both the refine and the descendant leaves coexist; nothing clobbers anything. The same convention reaches all the way down: a refine on `profile.address` lands at `form.errors.profile.address['']`.

The call form is the flat alternative: `form.errors('profile')` returns one `ValidationError[]` containing the refine PLUS every descendant leaf error in declaration order, no structure. Reach for the structural tree when you want to render per-field; reach for the call form when you want "anything wrong under this container?".

The sentinel is a nested-container convention: it appears one level deep or more. The root has no `''` self-slot, because at the root `''` is just an ordinary field key. `form.errors['']` reads a literal field named `''` (a rare but valid schema key), while global, form-level errors (a root `.refine()`, a path-less `setErrors` call) live at the structurally-distinct root path and read through `form.meta.ownErrors`. In a `JSON.stringify(form.errors)` dump they appear under the `'[]'` key, never under `''`, so the two never collide.

If your schema legitimately declares a field literally named `''` at a nested container (an exceptionally rare choice), that leaf's own errors and the container-self errors share the sentinel slot, and both arrays concatenate into a single read. At the root no such collision exists: `''` is a plain field there, kept entirely separate from the global bucket at `form.meta.ownErrors`.

## Setting errors imperatively

Server-side errors land in the same reactive store as Zod errors. Hand `form.setErrors` a `ValidationError[]` and each entry lands at its `path`:

```ts
form.setErrors([
  { path: ['email'], message: 'Already taken' },
  { path: ['profile', 'handle'], message: 'Reserved' },
])
```

`form.errors.email` and `form.errors.profile.handle` update immediately, and any `form.fields.<path>.firstError` / `form.fields.<path>.showErrors` reads update with them. The render surface is identical whether the error came from Zod or your API. See [Server-side errors](/docs/submitting/server-side-errors) for the full `handleSubmit` flow: scoped and functional updates, clearing, and the opaque `data` payload slot.

## Where to next

- [The form](/docs/reading-the-form/the-form): every other reactive read.
- [`values`](/docs/reading-the-form/values): the read companion to errors.
- [`fields`](/docs/reading-the-form/fields): per-leaf state, including the gated `firstError` / `showErrors` pairing.
- [`meta`](/docs/reading-the-form/meta): the form-level aggregates (`errorCount`, `valid`, `submitting`, etc.).
- [When validation runs](/docs/validation/when-validation-runs): the moment errors appear.
- [Server-side errors](/docs/submitting/server-side-errors): `setErrors` and `clearErrors` in full.

_Source: https://attaform.dev/docs/reading-the-form/errors_

---

# `meta`

> Form-level state in one place: every FieldState bit rolled up across paths, plus the seven form-only reads for the submit cycle and wizard departures.


Submit the demo without changing the simulate-failure toggle to watch `submitting` flip true mid-await, `submissionAttempts` increment, and `submitted` flip true once the callback succeeds. Flip the toggle and submit again: `submissionAttempts` still increments and `submitError` populates with the rejected callback's message, but `submitted` stays false because the callback never resolved. The [Form-only properties](#form-only-properties) section below names every bit; the inherited FieldState aggregations [link forward to the fields page](/docs/reading-the-form/fields).


## Two halves

`form.meta` extends `FieldState` with seven form-only properties. That means `meta` has 38 reads total:

- 31 properties inherited from FieldState, aggregated across every leaf in the form.
- 7 form-only properties that describe the submit cycle and the wizard-departure counter.

The inherited bits are documented once on the [`fields` page](/docs/reading-the-form/fields): same property names, same types, same reactivity. The only difference is the aggregation:

```ts
form.fields.email.dirty // this one field
form.meta.dirty // any field in the form
form.meta.errors // every error across every path (the whole-form aggregate)
form.meta.ownErrors // the root [] bucket alone: the form's own top-level errors
form.meta.value // the full form values object
```

`meta.errors` rolls up every path. `meta.ownErrors` is the exception to the aggregation rule: it reads the root's own bucket only, the form-level errors a root `.refine()` or a path-less `setErrors` pins at `[]`, with no field errors folded in. It is the banner accessor.

## Form-only properties

These seven reads exist only on `meta`, not on individual FieldStates.

| Property             | Type      | Meaning                                                                                                                                                                                           |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `submitting`         | `boolean` | `true` while a `handleSubmit`-produced handler is running. Covers both the validation phase and the async callback.                                                                               |
| `submissionAttempts` | `number`  | How many times the handler has been invoked (pass or fail). Useful for "show errors after first submit" UX.                                                                                       |
| `departAttempts`     | `number`  | How many times wizard navigation has actually departed this form. Bumps on real departures only (no-op back / same-key goTo / blocked next stay put).                                             |
| `submitError`        | `unknown` | The error from the most recent callback rejection. `null` on success and at the start of each new attempt.                                                                                        |
| `errorCount`         | `number`  | Scalar mirror of `errors.length`. Read it from templates and `watch()` without indexing the array.                                                                                                |
| `submitted`          | `boolean` | `true` once a `handleSubmit` callback resolves without throwing and without leaving errors set. Failed submits, including a `setErrors(...); return`, leave it `false`. Zeroed by `form.reset()`. |
| `instanceId`         | `string`  | Per-`useForm()`-call identity, stable for the lifetime of one call. New on every fresh mount.                                                                                                     |

## Templates

The classic submit-button pattern reads two bits:

```vue
<button :disabled="form.meta.submitting" type="submit">
  {{ form.meta.submitting ? 'Saving…' : 'Save' }}
</button>
```

The "show errors after first submit attempt" pattern reads the counter so failed attempts count:

```vue
<p v-if="form.meta.submissionAttempts > 0 && form.meta.errorCount > 0">
  {{ form.meta.errorCount }} field(s) need attention.
</p>
```

The form-level error banner reads `firstOwnError`, the form's own top-level error (a root `.refine()`, a path-less `setErrors`), with no field error mixed in:

```vue
<p v-if="form.meta.firstOwnError" role="alert">
  {{ form.meta.firstOwnError.message }}
</p>
```

The demo pairs two passwords with a root `.refine()`. Submit a mismatch and the refine's error lands at the form root, where `form.meta.firstOwnError` reads it for the banner and `form.meta.ownErrors` holds the whole root bucket:


The "post-success confirmation" pattern reads `submitted` instead, so the banner only renders after the callback actually succeeded. A callback that hands a server rejection to `setErrors` and returns counts as a failed submit, so the banner stays hidden:

```vue
<p v-if="form.meta.submitted && !form.meta.dirty">All saved.</p>
```

The form-summary pattern reads three:

```vue
<p>
  {{ form.meta.dirty ? 'Unsaved changes' : 'No changes' }} ·
  {{ form.meta.valid ? 'Ready to submit' : `${form.meta.errorCount} error(s)` }} ·
  Submitted {{ form.meta.submissionAttempts }} time(s)
</p>
```

## submitError lifecycle

`submitError` mirrors what the callback threw or rejected with, coerced to a real `Error` (a non-`Error` throw keeps its origin on `.cause`). `handleSubmit` catches the throw rather than re-raising it, so a rejected `onSubmit` never escapes as an unhandled rejection.

- `null` at form mount, between attempts, and on success.
- Set to the thrown / rejected value on callback failure.
- Cleared at the start of the next submit attempt.

A thrown callback surfaces twice. `submitError` is the raw-`Error` inspection channel above; the same failure is also piped into the error layer as a `ValidationError`. A bare `throw new Error(...)` lands form-level (the root `[]` bucket), where [`form.meta.firstOwnError`](#templates) and `form.meta.ownErrors` read it for a banner; throw a `{ path, message, code? }` (or an array of them) to land it on a specific field, where it joins `form.errors.<path>` under your own `code`. Either way it also rolls into `form.meta.errors`. This is separate from the `setErrors` path, which never touches `submitError`.

Reach for it when an inline failure banner needs to react to submit errors without your own `try { await onSubmit() }` wrapper:

```vue
<p v-if="form.meta.submitError" class="error">
  Submission failed:
  {{
    form.meta.submitError instanceof Error
      ? form.meta.submitError.message
      : String(form.meta.submitError)
  }}
</p>
```

## departAttempts

`departAttempts` counts how many times `wizard.next`, `wizard.back`, or `wizard.goTo` has actually left this form's step. The counter bumps on real departures only:

- `back()` from the first step is a no-op and leaves it alone.
- `goTo(currentKey)` (same-key jump) leaves it alone.
- `next()` blocked by failed activation leaves it alone.

The counter is a pure read; Attaform's default `getDisplayState` heuristic runs off `submissionAttempts` instead. Reach for `departAttempts` when an analytics event, a prior-step badge, or a layered error-reveal predicate wants the "user visited and left" signal:

```ts
watch(
  () => form.meta.departAttempts,
  (count) => {
    if (count === 1) analytics.track('step_first_departure', { form: form.key })
  }
)
```

Cleared by `form.reset()` alongside the submission counters.

## instanceId

`instanceId` distinguishes two mounts of the same shared form. Two `useForm({ key: 'signup' })` calls return the same FormStore (so writes in one reflect in the other), but `form.meta.instanceId` differs. Useful when devtools, telemetry, or e2e selectors need to disambiguate which mount triggered an event.

```vue
<form :data-form-id="form.meta.instanceId" @submit="onSubmit">
  …
</form>
```

Treat as identity, not state: don't parse it, don't compare ordinally, don't persist.

## Where to next

- [`fields`](/docs/reading-the-form/fields): the per-leaf FieldState, including every property `meta` inherits.
- [`handleSubmit`](/docs/submitting/handle-submit): the dispatch surface that drives `submitting`, `submissionAttempts`, and `submitError`.
- [The form](/docs/reading-the-form/the-form): the full reactive surface that surrounds `meta`.

_Source: https://attaform.dev/docs/reading-the-form/meta_

---

# `toRef`

> Get a `Readonly<Ref<T>>` at any schema path, for the rare case a consumer surface expects a Vue ref instead of the values Proxy.


`form.toRef(path)` returns a `Readonly<Ref<T>>` whose `.value` tracks storage at `path`. For normal reads (templates, computeds, conditional rendering), `form.values.<path>` is the right call. `toRef` is for ref-shaped interop only.

```ts
const schema = z.object({
  profile: z.object({ email: z.email() }),
  todos: z.array(z.object({ title: z.string() })),
})

const form = useForm({ schema })
```

## When to use it

External composables, watchers, and DevTools probes sometimes expect a `Ref` rather than a Proxy property:

```ts
const emailRef = form.toRef('profile.email') // Readonly<Ref<string>>

// Hand off to any third-party composable whose signature expects a Ref
useThirdPartyRefConsumer(emailRef)

// Watch a single path explicitly
watch(emailRef, (next) => {
  /* respond to email changes */
})
```

## Two call forms

`toRef` accepts either a dotted path or a segment tuple. Both resolve to the same leaf with the same inferred type:

```ts
form.toRef('profile.email')
form.toRef(['profile', 'email'])
```

The dotted form is shorter and idiomatic. The tuple form is the escape hatch for keys that contain a literal `.` (a dotted form can't disambiguate `{ 'a.b': … }` from nested `{ a: { b: … } }`). Pick whichever matches the surrounding code's grammar.

## Read-only by contract

`toRef` returns `Readonly<Ref<T>>`. Writes go through the same paths every other consumer uses:

```ts
form.setValue('profile.email', 'a@b.c') // imperative write
form.register('profile.email') // bound writes via v-register
form.append('todos', { title: '' }) // structural writes
```

Attaform tracks dirty, touched, and validation state through those write paths. Assigning to `.value` directly throws; `toRef` is a read handle, not a backdoor.

## Reactivity contract

`toRef` returns a `ComputedRef`-equivalent shape: reads inside reactive scopes track the path, and consumers re-run when storage at `path` changes. Two refs to the same path share reactivity; they don't double-subscribe.

```ts
const refA = form.toRef('profile.email')
const refB = form.toRef('profile.email')

// refA.value === refB.value, always.
// One storage write triggers both refs' subscribers.
```

The same path-precise reactivity Vue offers on `form.values.profile.email`, just wrapped in a `Ref`.

## Where to next

- [`values`](/docs/reading-the-form/values): the Proxy you should reach for first, before `toRef`.
- [`fields`](/docs/reading-the-form/fields): the per-leaf reactive surface for state bits, not just values.
- [The form](/docs/reading-the-form/the-form): every other reactive read on the return shape.

_Source: https://attaform.dev/docs/reading-the-form/to-ref_

---

# Type safety

> Wide while the user is typing, tight the moment the schema validates. Two surfaces, one promise: what you see is what is actually there.


A form library has to tell the truth about what is in the form. Mid-typing, that is whatever the user has put there so far: an incomplete email, an undecided radio pick, a partially-filled subtree rehydrated from yesterday's session. Post-submit, it is the Zod schema's parsed output: every refinement honored, every literal narrowed, every transform applied.

Attaform's types model both states. `form.values`, `defaultValues`, and `form.setValue` use the **in-flight shape**, wide enough to hold whatever the form is actually carrying. `handleSubmit((values) => ...)` hands you the **validated shape**: narrow, exact, what the schema promised.


## The gateway example: email

Take the simplest schema:

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

What is the type of `form.values.email`? `string`. Not a branded `Email`, not `string & { __brand: 'email' }`. Plain `string`. The reason is that during form completion, `form.values.email` legitimately holds `"a"`, then `"andy"`, then `"andy@"`. None of those satisfy `z.email()`, and the schema knows that. That is why [`form.errors.email`](/docs/reading-the-form/errors) populates while the user is mid-typing.

If `form.values.email` were typed as a branded `Email`, the type would lie about what is actually there. The runtime value would be `"andy@"`; the static type would claim it is a valid email. The compiler cannot help you when it has been told a fiction.

So the type follows reality: while the user is typing, `email` is whatever string they have typed. After the schema parses successfully inside `handleSubmit`, it is whatever the schema promises.

## Discriminators do the same thing

```ts
const schema = z.object({
  transport: z.discriminatedUnion('kind', [
    z.object({ kind: z.literal('boat'), hullLengthM: z.number() }),
    z.object({ kind: z.literal('truck'), payloadKg: z.number() }),
  ]),
})
const form = useForm({ schema })

form.values.transport.kind // string (not 'boat' | 'truck')
```

Same reasoning, one layer up. The user may not have picked a variant yet. They may be mid-keystroke in an input wired to the discriminator. They may be rehydrating a draft that was saved with `kind: ''`. Typing `transport.kind` as `'boat' | 'truck'` would lie about every one of those cases.

The literal narrowing engages where it earns its keep: inside `handleSubmit`, after the schema confirms the discriminator is one of the variants. There, `values.transport.kind` is `'boat' | 'truck'`, and TypeScript narrows `values.transport` to the matching variant.

## `defaultValues` works the same way

```ts
const form = useForm({
  schema,
  defaultValues: {
    email: '', // empty string is fine, even though z.email() will reject it
    transport: { kind: 'boat', hullLengthM: 0 }, // any starting state, even invalid
  },
})
```

Rehydration is the killer use case. Yesterday's user opened the form, picked a variant, typed half an email, then closed the tab. Today's `defaultValues` (re-read from `localStorage`, `sessionStorage`, or your server) needs to faithfully restore that half-filled state. If `defaultValues.email` required a value that already passed `z.email()`, you could not rehydrate the "still typing" case at all. You would be forced to invent a valid email the user never typed, or wipe the field entirely and lose their work.

Wide in-flight types mean you can store, hydrate, autosave, and resume from any intermediate state. The schema is still in charge of what counts as valid; the types just acknowledge that the form's job is to **get there**, not to always be there.

## Where the types tighten

`handleSubmit` is the boundary:

```ts
const onSubmit = form.handleSubmit((values) => {
  values.email // string (validated, passed z.email())
  values.transport.kind // 'boat' | 'truck'

  if (values.transport.kind === 'boat') {
    values.transport.hullLengthM // narrowed to number
  } else {
    values.transport.payloadKg // narrowed to number
  }
})
```

The argument to your success callback is `z.infer<typeof schema>`, Zod's parsed output. Every literal is preserved, every refinement is honored, every transform is applied. If the schema did not parse cleanly, the success callback never fires; the error callback runs instead with the in-flight values for you to inspect.

That is the contract: while the form is being filled in, the types help you handle every shape it might be in. The moment validation succeeds, the types snap to what the schema actually guarantees.

## Why not narrow earlier?

A library that narrowed `form.values.email` to a branded `Email` (or `form.values.transport.kind` to `'boat' | 'truck'`) before validation would have to do one of two things, both bad:

- **Refuse to type partial state.** Empty strings, half-typed emails, undecided discriminators are all invalid against the schema. Either `form.values` could not represent them (the form cannot work) or the types would lie (the compiler cannot help).
- **Force consumers to cast.** Every read becomes `as string`, every assignment becomes a fight with the type checker. The schema's value as a source of truth evaporates because you are routing around it on every line.

Wide in-flight types skip both failure modes. The schema still owns what counts as valid; the form just acknowledges that getting to valid is the user's job, not the type system's.

## Where to next

- [`values`](/docs/reading-the-form/values): the in-flight read surface this page is built on.
- [`handleSubmit`](/docs/submitting/handle-submit): the boundary where types tighten.
- [Discriminated unions](/docs/schemas/discriminated-unions): the schema feature that benefits most from the tight side of this contract.

_Source: https://attaform.dev/docs/reading-the-form/type-safety_

---

# The `v-register` directive

> One directive binds a native input to a schema path. The `<input>` stays native; Attaform sits at the directive layer.


Click the input, type a few characters, blur, refocus. The four `form.fields.email.*` bits in the table below flip with each interaction. The directive surfaces every signal the schema-aware layer needs without you wiring a single event listener; the [What it does](#what-it-does) section unpacks the four pieces of plumbing.


## What it does

Bind any native input to a schema path:

```vue
<input v-register="form.register('email')" />
```

The directive runs four pieces of plumbing for you:

1. **Reads** the current value from `form.values.<path>` and writes it into the DOM input on initial render and on every reactive update.
2. **Writes** back to `form.values.<path>` on every `input` event (or `change` / `blur` with modifiers).
3. **Coerces** the DOM string to the schema's leaf type: `type="number"` inputs land in storage as a number, checkboxes as a boolean, radio groups pick the option `value`.
4. **Tracks** field state (`touched`, `focused`, `blurred`, `blank`) and surfaces it through `form.fields.<path>`.

## Let `v-register` own the value

Because the directive already reads and writes the field's value, a second binding for the same value is redundant, and the two can end up fighting over the DOM. Leave off `:value` or `v-model` on a text input or `<select>`, `:checked` on a checkbox or radio, and `:selected` on an `<option>`:

```vue
<!-- Redundant: v-register already drives the value -->
<input v-register="form.register('email')" :value="form.values.email" />

<!-- Correct: v-register owns it -->
<input v-register="form.register('email')" />
```

The one `:value` that stays is an identity rather than state: the value a radio or an `<option>` stands for. Attaform reads that to decide which option is selected, so keep it.

```vue
<label v-for="flavor in flavors" :key="flavor">
  <input type="radio" v-register="form.register('flavor')" :value="flavor" />
  {{ flavor }}
</label>
```

Two guards keep this right without you thinking about it:

- A dev-console warning in every app, the moment the field mounts.
- A build-time warning when you run Attaform's [Vite or Nuxt plugin](/docs/server-and-ssr/ssr-bare-vue), on every compile, so CI catches it too.

Each names the offending attribute and leaves the radio and `<option>` identity `:value` alone.

## Auto-installed

`createAttaform()` registers the directive globally, in bare Vue and in Nuxt. You don't import it.

If you wrap inputs inside a component whose root is **not** the input itself, [`useRegister`](/docs/binding-inputs/use-register) re-binds `v-register` onto an inner native element. For compound components binding multiple paths, prefer [`injectForm`](/docs/reading-the-form/the-form) over `useRegister`.

## Reading errors per field

The directive's binding pair is read-and-error: `form.register('email')` for the input, `form.fields.email.firstError?.message` for the message, gated by `form.fields.email.showErrors` so a half-typed value doesn't get yelled at on first paint.

```vue
<input v-register="form.register('email')" />
<p v-if="form.fields.email.showErrors">{{ form.fields.email.firstError?.message }}</p>
```

The raw `form.errors.email` Proxy stays available as `ValidationError[]` when you need the full array, empty when the field is valid. `form.fields` is the display-ergonomics layer over the same data.

## Accessibility, handled

By default, `v-register` keeps a field's aria attributes in sync with its [display state](/docs/validation/showing-errors), so assistive technology announces exactly what sighted users see, with no extra wiring:

| Attribute          | Set when                                                              |
| ------------------ | --------------------------------------------------------------------- |
| `aria-invalid`     | the field's `displayState` is `'error'`                               |
| `aria-busy`        | the field's `displayState` is `'pending'` (an async check is running) |
| `aria-required`    | the schema marks the path required                                    |
| `aria-describedby` | points at the field's error id while in the error state               |

These track the same gated `displayState` that drives `form.fields.email.showErrors`, so the announcement and the visible message reveal together, never on a half-typed value. The required and invalid states are emitted during SSR too, so a server-rendered form is accessible before hydration.

`aria-required` is scoped with care. A checkbox that rolls up into an array or set group never carries it, since no single box is required on its own and an empty selection is valid; the requirement lives on the group. And every attribute lands on the real form control: when `v-register` is on a wrapper component, the attributes follow the inner element it re-binds with [`useRegister`](/docs/binding-inputs/use-register), never the presentational root.

### Wiring the error element

Auto-aria sets `aria-describedby` to [`form.fields.<path>.aria.errorId`](/docs/reading-the-form/fields). Put that id on your error element so the reference resolves:

```vue
<input v-register="form.register('email')" />
<p v-if="form.fields.email.showErrors" :id="form.fields.email.aria.errorId">
  {{ form.fields.email.firstError?.message }}
</p>
```

`form.fields.email.aria.errorId` is stable for the field and unique across every mount on the page (it folds in the form's `instanceId`), so two instances of the same form never cross their references. The companion `form.fields.email.id` wires a `<label :for>` to the input when you need one.

### Respect your markup

Write any aria attribute yourself and Attaform leaves it alone, for that one attribute. Author `aria-invalid` while the other three stay automatic:

```vue
<input v-register="form.register('email')" :aria-invalid="hasCustomError" />
```

The check happens per attribute and per binding, so reaching for one escape hatch never disables the rest.

### Turning it off

One knob, `autoAria`, at three tiers; the narrower tier wins:

- Per binding: `form.register('email', { autoAria: false })`.
- Per form: `useForm({ schema, autoAria: false })`.
- App-wide: `createAttaform({ defaults: { autoAria: false } })`.

A narrower tier overrides the wider one in either direction, so a single binding can re-enable management with `{ autoAria: true }` even when the form opted out. Any tier set to `false` hands every aria attribute back to your markup; an authored attribute is always preserved regardless.

## Where to next

- [`useRegister`](/docs/binding-inputs/use-register): the composable for re-binding `v-register` onto an inner native element inside a wrapper component.
- [Modifiers](/docs/binding-inputs/modifiers): `.lazy`, `.trim`, `.number` for tuning the write side.
- [Schema-driven coercion](/docs/binding-inputs/coercion): how DOM strings land at the right leaf type.
- [`values`](/docs/reading-the-form/values): what the directive writes into.
- [`errors`](/docs/reading-the-form/errors): the error reads paired with each registered path.
- [`fields`](/docs/reading-the-form/fields): the `id` and `aria` ids the accessibility wiring reads from.
- [Display state and showing errors](/docs/validation/showing-errors): the gated verdict the aria attributes track.

_Source: https://attaform.dev/docs/binding-inputs/v-register_

---

# `useRegister`

> The bridge between `v-register` on a wrapper component and `v-register` on its inner native input.


Type into either of the two fields rendered by `<FieldRow>` and watch the JSON readout update. The parent applies `v-register="form.register('email')"` to the `<FieldRow>` root; inside `FieldRow`, `useRegister()` captures that binding and `v-register="rv"` reattaches it to the inner `<input>`. The sections below trace every step.


## When to reach for it

`useRegister` exists for one specific shape: a Vue component that wraps a single form field, whose **root element is not the input itself**:

```vue
<!-- A labeled-row wrapper. The root is <label>, not the input. -->
<FieldRow v-register="form.register('email')" label="Email" />
```

Inside `<FieldRow>`, the wrapper's root receives the directive, but you need the binding on the inner `<input>` to make the form work. `useRegister` captures the parent's `v-register` binding so you can re-apply it inside.

When the wrapper's root **is** the input itself, Vue's attribute fallthrough already handles the binding, so `useRegister` is unnecessary.

## Capture, re-apply

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

  const rv = useRegister()
</script>

<template>
  <label class="field-row">
    <span>{{ label }}</span>
    <input v-register="rv" />
  </label>
</template>
```

That's the whole pattern: call once, hand the return value to `v-register` inside. `useRegister` reads the parent's binding, surfaces it as a hybrid Ref + RegisterValue Proxy, and the directive picks it up exactly as if the parent had applied it directly to the inner input.

## Two surfaces on the return value

`useRegister()` returns a hybrid Proxy:

- **Ref-shaped**: `v-register="rv"` works because the Proxy answers `__v_isRef` / `.value` like a `Ref<RegisterValue | undefined>`. Vue's template auto-unwrap surfaces the underlying RegisterValue to the directive.
- **Pierced reads**: `rv.path`, `rv.segments`, `rv.formKey`, `rv.formInstanceId` all work directly in script setup without `.value`. Reads inside reactive scopes (`computed`, `watchEffect`) track changes.

```ts
const rv = useRegister()

// In script setup: direct pierce
const ariaLabel = computed(() => `Field for ${rv?.path}`)

// In template: Vue auto-unwraps
// v-register="rv"
```

## Unbound state

When the parent didn't apply `v-register`, every pierced read returns `undefined` and the composable's return type surfaces this honestly as `UseRegisterReturn<V> | undefined`:

```ts
const rv = useRegister()
// rv?.formKey: optional-chain to defend
```

In dev mode, a single `console.warn` fires per instance at mount time when the parent never bound. The directive accepts `undefined` peacefully (its binding type is `RegisterValue<V> | undefined`), so `v-register="rv"` works whether or not a parent bound. No runtime crash, just the warn.

## Multi-field wrappers

`useRegister` is the right call for **single-field** wrappers. For compound components binding **multiple paths** (a date-range picker exposing start + end fields, an address subform exposing street + city + zip), reach for `injectForm<Form>()` and call `ctx.register(path)` directly. That sidesteps the single-binding assumption `useRegister` makes.

## Where to next

- [The `v-register` directive](/docs/binding-inputs/v-register): the directive `useRegister` re-binds.
- [Custom assigners](/docs/binding-inputs/custom-assigners): the escape hatch for non-standard element value surfaces.
- [`injectForm`](/docs/cross-cutting-state/inject-form): for compound components binding multiple paths.

_Source: https://attaform.dev/docs/binding-inputs/use-register_

---

# Text, number, textarea

> One directive, three native inputs, three leaf types: text → string, number → number, textarea → string.


Type into all three inputs and watch the JSON readout update. The number input's value lands as a `number` (not a string), even though the DOM only deals in strings. The directive handles the leaf-type coercion; the [Schema-driven coercion](/docs/binding-inputs/coercion) page explains the rule that powers it.


## Bind any of the three

```vue
<input v-register="form.register('name')" type="text" />
<input v-register="form.register('age')" type="number" />
<textarea v-register="form.register('bio')" />
```

All three follow the same write pattern: `input` event → directive reads the DOM value → coerces to the schema leaf type → writes to storage. No wrapper, no per-element binding code.

## Modifiers

Three modifiers apply across all text-family inputs:

```vue
<input v-register.lazy="form.register('name')" type="text" />
<input v-register.trim="form.register('name')" type="text" />
<input v-register.number="form.register('age')" type="text" />
```

| Modifier  | Effect                                                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `.lazy`   | Writes fire on `change` / `blur` instead of every `input` event. Matches Vue's `v-model.lazy` semantics.                        |
| `.trim`   | Strips leading and trailing whitespace before the write.                                                                        |
| `.number` | Coerces the DOM string to a number before the write. Useful when `type="text"` is required but the schema leaf is `z.number()`. |

The full set lives in the [Modifiers](/docs/binding-inputs/modifiers) page; `.number` and `<input type="number">` are documented side-by-side there.

## Numeric inputs without `type="number"`

`<input type="number">` is the most direct bind, but it has spotty UX: some browsers swallow non-digit input on the fly, others allow it; decimal separators (`.` vs `,`) vary by locale; the spinner buttons can confuse keyboard users. When you want a numeric value in storage but full control of the keyboard, reach for `<input type="text" inputmode="numeric">` paired with the `.number` modifier:

```vue
<input v-register.number="form.register('age')" type="text" inputmode="numeric" />
```

`inputmode="numeric"` is a regular DOM attribute. The directive doesn't intercept it; it passes through to the element. Mobile browsers show the numeric keyboard, desktop browsers accept any keystrokes, and the `.number` modifier coerces the DOM string to a number on write.

## Where to next

- [Modifiers](/docs/binding-inputs/modifiers): `.lazy`, `.trim`, `.number` in depth.
- [Register transforms](/docs/binding-inputs/transforms): composable per-field write transforms.
- [Schema-driven coercion](/docs/binding-inputs/coercion): how the directive maps DOM strings to leaf types.

_Source: https://attaform.dev/docs/binding-inputs/text-number-textarea_

---

# Checkbox

> Boolean for one, array of values for a group; the leaf type picks the binding shape.


Toggle the single checkbox to flip the boolean. Tick a few in the group to watch the array populate with the matching enum literals. The order in storage reflects the order the boxes were checked, not the declaration order in the template. The schema's leaf type at each path decides which binding mode the directive picks.


## Single checkbox → boolean

When the schema leaf is `z.boolean()`, the directive binds checked-state directly:

```vue
<input v-register="form.register('acceptTerms')" type="checkbox" />
```

`acceptTerms` in storage is `true` while checked, `false` otherwise. The `value` attribute is ignored in this mode; boolean state lives in the `checked` property, not the value.

## Checkbox group → array

When the schema leaf is `z.array(z.enum([...]))` (or any array type), every `<input type="checkbox">` bound to the same path forms a group:

```vue
<input v-register="form.register('languages')" type="checkbox" value="ts" />
<input v-register="form.register('languages')" type="checkbox" value="js" />
<input v-register="form.register('languages')" type="checkbox" value="rust" />
```

Each input's `value` attribute is the entry written into the array when it's checked. Unchecking removes the entry. Storage holds only the currently-checked values; the array starts empty when no box is ticked.

The directive picks the binding mode from the schema, not from how you write the template. Declare `z.array(z.string())` and the same `form.register('languages')` call site automatically groups every bound checkbox.

## Where to next

- [Radio groups](/docs/binding-inputs/radio): the single-pick counterpart.
- [Select & multi-select](/docs/binding-inputs/select): the same array semantics in a dropdown shape.
- [Schema-driven coercion](/docs/binding-inputs/coercion): how leaf types drive binding shape.

_Source: https://attaform.dev/docs/binding-inputs/checkbox_

---

# Radio groups

> One register call across every option; the directive writes the picked option's value attribute into storage.


Pick any of the three plans to watch the JSON readout switch to the option's `value` attribute. Every radio bound through the same `form.register('plan')` call automatically belongs to one group; Attaform infers the grouping from the shared path, not from `name=`. The [Schema-driven coercion](/docs/binding-inputs/coercion) page covers how the directive maps option strings to non-string leaf types.


## One register call, many options

```vue
<input v-register="form.register('plan')" type="radio" value="starter" />
<input v-register="form.register('plan')" type="radio" value="pro" />
<input v-register="form.register('plan')" type="radio" value="team" />
```

Every radio bound to `form.register('plan')` belongs to the same group. The directive writes the picked option's `value` attribute into storage:

```ts
form.values.plan // 'starter' | 'pro' | 'team'
```

No `name=` ceremony; the shared `register` call IS the group. The browser's per-name single-pick semantics still apply for keyboard navigation, and Attaform reads the result.

## Default selection

Defaulting a radio group is no different from defaulting any other field. Set the default in `defaultValues` (or the schema's `.default(...)`), and the matching radio renders pre-selected:

```ts
const form = useForm({
  schema: z.object({
    plan: z.enum(['starter', 'pro', 'team']),
  }),
  defaultValues: { plan: 'starter' },
})
```

The directive sets `checked` on whichever radio's `value` matches the stored value.

## Numeric and enum options

Radio inputs only emit DOM strings, but the schema leaf can be a number, an enum literal, or any other scalar. The `.number` modifier coerces:

```vue
<input v-register.number="form.register('priority')" type="radio" value="1" />
<input v-register.number="form.register('priority')" type="radio" value="2" />
```

The directive parses `'1'` → `1` before writing. The [Schema-driven coercion](/docs/binding-inputs/coercion) page covers every leaf-type mapping.

## Where to next

- [Select & multi-select](/docs/binding-inputs/select): same single-pick semantics in a dropdown shape; reach for it when the option set is long enough to warrant a dropdown.
- [Checkbox & checkbox groups](/docs/binding-inputs/checkbox): the multi-pick counterpart.
- [Schema-driven coercion](/docs/binding-inputs/coercion): how `value=` strings map to non-string leaves.

_Source: https://attaform.dev/docs/binding-inputs/radio_

---

# Select & multi-select

> One element, two leaf shapes: a scalar for `<select>`, an array for `<select multiple>`. Pick the mode in the schema; the directive follows.


Pick a country from the single select to watch the JSON readout switch its scalar value. In the multi-select below, hold ⌘ (or Ctrl) and click multiple options. Every picked option's `value=` attribute lands in the `tags` array in selection order. The directive reads the schema leaf at each path and infers single vs. multi automatically.


## Single select → scalar

When the schema leaf is a scalar (enum, string, number), `<select>` binds to that one value:

```vue
<select v-register="form.register('country')">
  <option value="us">United States</option>
  <option value="uk">United Kingdom</option>
</select>
```

The picked option's `value=` attribute lands in `form.values.country`. The schema's leaf type drives the storage type: `z.enum(['us', 'uk'])` keeps the value as the matching literal.

## Multi-select → array

When the schema leaf is an array, `<select multiple>` writes every picked option's value into that array, in selection order:

```vue
<select v-register="form.register('tags')" multiple>
  <option value="design">Design</option>
  <option value="eng">Engineering</option>
  <option value="ops">Ops</option>
  <option value="sales">Sales</option>
</select>
```

```ts
const form = useForm({
  schema: z.object({
    tags: z.array(z.enum(['design', 'eng', 'ops', 'sales'])),
  }),
  defaultValues: { tags: [] },
})

form.values.tags // ['design', 'ops']
```

Deselecting an option removes it from the array; the array shape always reflects the current visual selection. No event-listener wiring on your side; the directive infers multi-mode from the `multiple` attribute and the schema's array leaf.

## The `.number` modifier

`<option value="...">` only stores strings. When the schema's array (or scalar) leaf is `z.number()` or `z.array(z.number())`, the `.number` modifier coerces every picked option's value to a number before the write:

```vue
<select v-register.number="form.register('priority')">
  <option value="1">Low</option>
  <option value="2">Medium</option>
  <option value="3">High</option>
</select>
```

The directive parses `'1'` → `1` per option. The [Schema-driven coercion](/docs/binding-inputs/coercion) page documents the full leaf-type mapping.

## Custom display values

The dropdown's option labels are pure HTML; bind them however you'd render any other list:

```vue
<script setup lang="ts">
  const countries = [
    { code: 'us', flag: '🇺🇸', name: 'United States' },
    { code: 'uk', flag: '🇬🇧', name: 'United Kingdom' },
    { code: 'ca', flag: '🇨🇦', name: 'Canada' },
    { code: 'au', flag: '🇦🇺', name: 'Australia' },
  ]
</script>

<template>
  <select v-register="form.register('country')">
    <option v-for="opt in countries" :key="opt.code" :value="opt.code">
      {{ opt.flag }} {{ opt.name }}
    </option>
  </select>
</template>
```

The directive only cares about each option's `value=` attribute; the visible label can be anything. `<optgroup>` works the same way: the directive reads option values whether or not they're nested under a group label.

## Where to next

- [Radio groups](/docs/binding-inputs/radio): single-pick counterpart in radio form; reach for it when the option set is short enough to show inline.
- [Checkbox & checkbox groups](/docs/binding-inputs/checkbox): array shape via grouped checkboxes.
- [Schema-driven coercion](/docs/binding-inputs/coercion): how `value=` strings map to non-string leaf types.

_Source: https://attaform.dev/docs/binding-inputs/select_

---

# File inputs

> Single file → `File | null`. Multiple → `readonly File[]`. Live handles, ready for `FormData` or your upload pipeline.


Pick a file in the single input to watch the avatar slot fill in with the file name + size. Pick more in the multi-input below to see them stack; the directive writes a `File[]` in the order the picker returned them. Both surfaces hand you live `File` handles you can append to `FormData` or stream into an upload.


## Single file → File | null

```vue
<input v-register="form.register('avatar')" type="file" accept="image/*" />
```

```ts
const form = useForm({
  schema: z.object({
    avatar: z.file().nullable(),
  }),
  defaultValues: { avatar: null },
})

form.values.avatar // File | null
```

Selecting a file writes the `File` handle into storage. Clearing the input (or selecting then cancelling) writes `null`.

## Multiple files → File[]

```vue
<input v-register="form.register('attachments')" type="file" multiple />
```

```ts
const form = useForm({
  schema: z.object({
    attachments: z.array(z.file()),
  }),
  defaultValues: { attachments: [] },
})

form.values.attachments // readonly File[]
```

Every file in the picker selection lands in the array, in picker order. Re-selecting replaces the array; the input never accumulates across picks.

## Uploading via FormData

Live `File` handles work directly with the upload pipelines you'd reach for anyway:

```ts
const onSubmit = form.handleSubmit(async (values) => {
  const body = new FormData()
  body.append('avatar', values.avatar!)
  for (const file of values.attachments) {
    body.append('attachments', file)
  }
  await fetch('/api/upload', { method: 'POST', body })
})
```

The schema's `z.file()` leaf type carries the constraint through validation; refinements like `.min(size)`, `.max(size)`, `.mime([...])` surface in `form.errors.<path>` like any other validator.

## Reset behavior

`form.reset()` clears the file input back to `null` / `[]`. The directive also resets the underlying `<input>`'s `value` attribute, so the picker shows "No file chosen" after the reset, no stale filename hanging around.

## Where to next

- [`reset` & `resetField`](/docs/writing-and-mutating/reset): programmatic clearing.
- [Schema-driven coercion](/docs/binding-inputs/coercion): how File leaves move through the directive.
- [`handleSubmit`](/docs/submitting/handle-submit): wraps your upload callback in the validation gate.

_Source: https://attaform.dev/docs/binding-inputs/file_

---

# Modifiers

> Three knobs on the write side of `v-register`: when to write, what to clean up before writing, what type to land on.


Type into the lazy field and watch the readout only update on blur. Pad spaces around a word in the trimmed field to see them stripped. Type a number into the third field. Even though it's `type="text"`, the value lands in storage as a `number` thanks to `.number`. Each modifier composes with any text-family input; the `.number` modifier also applies to `<select>`.


## `.lazy`

```vue
<input v-register.lazy="form.register('name')" type="text" />
```

Writes fire on `change` / `blur` instead of every `input` event. Matches Vue's `v-model.lazy` semantics, so readers familiar with the convention can reach for it without re-learning.

When to reach for it:

- Heavy validation that's expensive on every keystroke (a sync refinement that walks a large list, an async refinement that hits a server).
- A field that should commit a "settled" value, not an in-progress one.

## `.trim`

```vue
<input v-register.trim="form.register('username')" type="text" />
```

Strips leading and trailing whitespace from the DOM string before the write lands in storage. Cleaner storage values + cleaner validation (no `"hello   "` failing a regex that meant to allow `"hello"`).

The `.trim` modifier runs before any [register transform](/docs/binding-inputs/transforms) you've supplied, so transforms see the already-trimmed value.

## `.number`

```vue
<input v-register.number="form.register('age')" type="text" />
<select v-register.number="form.register('priority')">
  …
</select>
```

Coerces the DOM string to a `number` before the write. Useful in two specific shapes:

- **`<input type="text">` for a numeric leaf.** The browser doesn't enforce numeric input on `type="text"`, but the schema leaf is `z.number()`. `.number` parses the string for you.
- **`<select>` with numeric option values.** `<option value="1">` only ever stores `'1'` in the DOM; the `.number` modifier coerces per-pick to `1`.

`<input type="number">` already coerces to a number through [schema-driven coercion](/docs/binding-inputs/coercion); `.number` is for the cases where the input itself isn't numeric.

## Compose freely

Modifiers compose with each other and with the rest of the binding surface:

```vue
<input v-register.lazy.trim="form.register('username')" type="text" />
<input v-register.number.lazy="form.register('age')" type="text" />
```

`.lazy.trim` writes a stripped value on blur; `.number.lazy` writes a parsed number on blur. Order in the template doesn't change the order of operations: the directive applies trim, then number, then writes.

## Where to next

- [Register transforms](/docs/binding-inputs/transforms): for transformations that go beyond the three built-in modifiers.
- [Schema-driven coercion](/docs/binding-inputs/coercion): what happens to the value after the modifier runs.
- [The `v-register` directive](/docs/binding-inputs/v-register): the binding the modifiers attach to.

_Source: https://attaform.dev/docs/binding-inputs/modifiers_

---

# Register transforms

> A write-time pipeline that reshapes each value before it lands in storage. Compose `trim`, `lowercase`, `clamp`, `format` per field, and return a Promise when the reshape needs a round trip first.


Type a mixed-case title with spaces into the slug field and watch the readout: the value lands as a lowercased, dashified, alphanumeric-only string. The first input has no transforms; the second composes two (`lowercase` then `dashify`) through the `transforms` array on `register`. The [Composition order](#composition-order) section unpacks why left-to-right composition makes a personal transform library easy to assemble.


## A transform is a function

```ts
import type { RegisterTransform } from 'attaform'

const lowercase: RegisterTransform = (v) => (typeof v === 'string' ? v.toLowerCase() : v)
const dashify: RegisterTransform = (v) => (typeof v === 'string' ? v.replace(/\s+/g, '-') : v)
```

`RegisterTransform` is `(value: unknown) => unknown`. The shape is intentionally generic, so a personal library of transforms plugs into any `register()` call site regardless of leaf type. Library authors defend against type mismatches by no-op'ing on the unexpected branch.

## Attach via `transforms: [...]`

```ts
form.register('slug', { transforms: [lowercase, dashify] })
```

Pass an ordered array on the `register` options. Every keystroke (or `change`/`blur` with `.lazy`) flows through the transforms left-to-right; the final value is what lands in storage.

## Composition order

Transforms run left-to-right:

```ts
form.register('slug', { transforms: [trim, lowercase, dashify] })
// 'Hello World ' → 'Hello World' → 'hello world' → 'hello-world'
```

Pick the order that matches the data flow you want. The [`.trim`](/docs/binding-inputs/modifiers) modifier runs before any transform, so a `[trim, ...]` transforms array would be redundant. Reach for the modifier when you want trimming and the transforms array when you want anything else.

## Async transforms

Hand a transform a `Promise` and Attaform shifts into async mode on its own. The chain stays fully synchronous, landing the value in the same tick, right up until a transform returns a thenable. From there Attaform defers the write, flips the field to `busy`, and commits the resolved value the moment it arrives.

```ts
const normalize: RegisterTransform = async (value, ctx) => {
  const res = await fetch(`/api/normalize?q=${value}`, { signal: ctx?.signal })
  return res.text()
}

form.register('handle', { transforms: [normalize] })
```

Mix sync and async freely in one array. The pipeline runs synchronously until the first `Promise` shows up, so a `[trim, normalize, lowercase]` chain trims in the same tick, waits on `normalize`, then lowercases the result before it lands.

### Watch the busy state

While an async transform settles, the field reports it:

```ts
form.fields.handle.busy // true while the chain is in flight
form.fields.handle.transforming // true specifically for transform work
```

`transforming` is the transform-only signal; `busy` unions it with validation, so one read covers every reason the field is working. Both roll up to `form.meta`, and on a revealed field they drive `displayState` to `'pending'` and set `aria-busy`, the same anti-flash timing a pending validation rides. Bind `busy` directly when you want a spinner the instant work starts, even before the field has been revealed.

### Latest edit wins

Edit faster than the work settles and only the most recent run commits. Earlier in-flight runs are discarded the moment a newer value supersedes them, so the field never stutters back to a stale result or commits two answers out of order.

### Failures land on `transformError`

An async transform that rejects routes its error to a dedicated channel instead of throwing into your app or logging to the console:

```ts
form.fields.handle.transformError // Error | null
```

This is a separate surface from validation `errors`: a normalization that could not finish is a different story from a value the schema rejected. The field keeps its prior committed value, and a later successful run clears the error.

### Cancel stale work with `ctx.signal`

Every transform receives a `ctx` whose `signal` is an `AbortSignal`. Attaform aborts it when a newer edit supersedes the run, or when `reset()` or unmount tears the field down. Thread it into cancellable I/O and a superseded request drops instead of racing the live one:

```ts
const normalize: RegisterTransform = async (value, ctx) => {
  const res = await fetch(`/api/normalize?q=${value}`, { signal: ctx?.signal })
  return res.text()
}
```

A purely synchronous chain never touches `signal` and never allocates a controller, so the fast path stays allocation-free.

### Submit waits for transforms to settle

[`handleSubmit`](/docs/submitting/handle-submit) drains every in-flight transform before it validates, so a submit fired one keystroke after an edit validates the resolved value, not the one mid-flight. Need the same guarantee by hand? `await form.settleTransforms()` resolves once the field (or the whole form) is quiet, and it resolves rather than rejects even when a transform failed.

## From a dropped file to clean data

Here is where async transforms earn their keep: point one at an `<input type="file">` and a file the visitor picks becomes finished form state. No upload handler, no change listener to wire, just a `transforms` array doing the work.

Download the sample below (or write your own), then pick it in the demo. Each line becomes a URL, the lines that are not web addresses get dropped, and a busy indicator runs the whole time the file is being read and tidied.


Two transforms compose the result. The first reads the file and reshapes its lines; the second lowercases what survives:

```ts
const schema = z.object({ links: z.array(z.string()).min(1) })

const linesToUrls: RegisterTransform = async (value) => {
  const files = Array.isArray(value) ? (value as File[]) : []
  const urls: string[] = []
  for (const file of files) {
    for (const line of (await file.text()).split(/\r?\n/)) {
      const trimmed = line.trim()
      if (trimmed === '' || trimmed.startsWith('#')) continue
      try {
        const url = new URL(/^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`)
        if (url.protocol === 'http:' || url.protocol === 'https:') urls.push(url.href)
      } catch {
        // a line that cannot become a URL is dropped
      }
    }
  }
  return urls
}

const lowercase: RegisterTransform = (value) =>
  Array.isArray(value) ? value.map((url) => String(url).toLowerCase()) : value

const form = useForm({ schema })
```

```vue
<input
  v-register="form.register('links', { transforms: [linesToUrls, lowercase] })"
  type="file"
  accept=".txt,text/plain"
  multiple
/>
```

Because `linesToUrls` reads each file with `await file.text()`, the chain goes async the instant files are picked: `form.fields('links').busy` flips true, the resolved `string[]` commits when the read finishes, and an unreadable file lands its message on `form.fields('links').transformError`. (`links` is an array field, so its rolled-up state reads through the call-form `form.fields('links')` rather than the dot-form, which would descend into a child path.)

## Throws are caught

A _synchronous_ throw gets caught: the pipeline aborts, nothing writes, and the directive's assigner returns `false`, so a buggy transform never crashes the host app. (An async rejection takes the `transformError` channel above instead, never a throw.) Defensive shape:

```ts
const safeBigInt: RegisterTransform = (v) => {
  try {
    return typeof v === 'string' ? BigInt(v) : v
  } catch {
    return v // pass through; the slim gate will reject the bad value with a friendly message
  }
}
```

`BigInt('not-a-number')` throws; the catch lets the original value through, and the schema's leaf validator handles the rejection.

## Where to next

- [File inputs](/docs/binding-inputs/file): the `File` and `File[]` leaves an async transform reshapes into finished data.
- [Modifiers](/docs/binding-inputs/modifiers): built-in `.lazy`, `.trim`, `.number` for the most common reshaping.
- [Schema-driven coercion](/docs/binding-inputs/coercion): what runs after the transforms array.
- [Custom assigners](/docs/binding-inputs/custom-assigners): `assignKey` for elements whose value surface isn't a DOM property.

_Source: https://attaform.dev/docs/binding-inputs/transforms_

---

# Schema-driven coercion

> Two built-in rules handle 90 % of real forms: string → number and string → boolean. Compose more when your schema needs them.


Type a number into the `count` field and watch it land in storage as a `number` (not a string). Type "true" or "false" into `enabled` and see it commit as a `boolean`. Both inputs are `type="text"`; coercion is what makes `z.number()` and `z.boolean()` leaves work against plain text inputs at the directive layer.


## The default registry

```ts
defaultCoercionRules = [
  { input: 'string', output: 'number', transform: parseNumber },
  { input: 'string', output: 'boolean', transform: parseTrueFalse },
]
```

- **string → number** trims whitespace, parses with `Number()`, returns `coerced: false` on `NaN` (the slim gate then rejects the unparseable value with a friendly message). Whitespace-only inputs skip the coercion so blank-paths machinery stays in charge.
- **string → boolean** lowercases + trims, accepts `'true'` / `'false'` in any case (`'True'`, `'FALSE'`, `' true '`). Anything else skips so the gate can reject.

The same two rules cover most native HTML input shapes: `<input type="number">` (number leaf), `<input type="checkbox" value="...">` (boolean leaf), `<select>` with numeric option values.

## When coercion fires

Coercion runs **only on user-typed DOM values**. Programmatic writes through [`form.setValue`](/docs/writing-and-mutating/set-value), `form.register('path').setValueWithInternalPath`, or the field-array helpers are **never** coerced; they're typed against the schema's leaf type at the call site, so the value already matches. The strictness is intentional: if you've got the value in hand in code, you knew its type when you typed it.

The coercion step sits between the directive's value extraction and the slim-type gate's write check:

```
DOM event → extract → modifier (.trim, .number) → transforms[] → coerce → slim gate → storage
```

A value the registry can't coerce (`coerced: false`) passes through unchanged; the slim gate handles the rejection downstream with a typed diagnostic.

[`<input type="file">`](/docs/binding-inputs/file) inputs skip coercion entirely; `File` handles are objects, not strings, and land in storage as-is.

## Extending the default registry

`useForm({ coerce })` accepts three forms:

```ts
useForm({ coerce: true }) //   defaults (string→number, string→boolean)
useForm({ coerce: false }) //   no coercion; slim gate rejects mismatches as-is
useForm({ coerce: [...defaultCoercionRules, defineCoercion({ ... })] })
```

Spread `defaultCoercionRules` to extend; pass a bare array to **replace** entirely. Adding a string → Date rule for ISO timestamps:

```ts
import { useForm } from 'attaform'
import { defaultCoercionRules, defineCoercion } from 'attaform'

useForm({
  schema,
  coerce: [
    ...defaultCoercionRules,
    defineCoercion({
      input: 'string',
      output: 'date',
      transform: (s) => {
        const d = new Date(s)
        return Number.isFinite(d.getTime()) ? { coerced: true, value: d } : { coerced: false }
      },
    }),
  ],
})
```

Now `<input type="text" v-register="form.register('publishedAt')" />` against a `z.date()` leaf works without modifiers.

## App-wide defaults

Set coercion at the plugin level so every form picks up the same custom rule without per-form opt-in:

```ts
import { createAttaform } from 'attaform'
import { defaultCoercionRules, defineCoercion } from 'attaform'

createAttaform({
  defaults: {
    coerce: [
      ...defaultCoercionRules,
      defineCoercion({
        /* ... */
      }),
    ],
  },
})
```

Per-form `useForm({ coerce })` overrides the plugin default. The plugin default overrides Attaform's built-in default (`defaultCoercionRules`). Three layers, deterministic resolution.

## Sync, no throws

Coercion rules MUST be sync. They SHOULD NOT throw; wrap internal try / catch when the conversion can fail (e.g. `BigInt('not-a-number')` throws for non-numeric strings). Attaform wraps each invocation in try / catch as defense in depth; throws are caught, logged once per `(input, output)` pair, and the original value passes through to the slim gate.

## Where to next

- [Modifiers](/docs/binding-inputs/modifiers): `.number` for the `<input type="text">` + numeric-leaf combo without touching the registry.
- [Register transforms](/docs/binding-inputs/transforms): the per-field write pipeline that runs before coercion.
- [`form.setValue`](/docs/writing-and-mutating/set-value): the programmatic-write surface that bypasses coercion entirely.
- [The `v-register` directive](/docs/binding-inputs/v-register): the layer coercion plugs into.

_Source: https://attaform.dev/docs/binding-inputs/coercion_

---

# Custom assigners

> The escape hatch for elements whose value surface isn't a DOM property. Install a write function per element and decide what lands in storage when an event fires.


Click the color swatches to watch the JSON readout flip. The widget isn't an `<input>`; it's a plain `<div>` with buttons that dispatches `input` events and stores its picked color on `dataset.color`. A custom assigner installed via `el[assignKey] = fn` translates that to a form write. The [Install via `assignKey`](#install-via-assignkey) section walks through the wire-up.


## When v-register needs help

`v-register`'s default extractor reads `el.value` (or `el.checked` for checkboxes, `el.files` for files). For elements whose value lives somewhere else (a Web Component with `el.color`, a custom widget with `el.dataset.x`, a third-party slider with a method-only surface), the default can't see what to write.

A custom assigner replaces the write step. The directive still fires on the same DOM events; the assigner decides what value to commit.

## Install via `assignKey`

```ts
import { onMounted, useTemplateRef } from 'vue'
import { assignKey, type CustomDirectiveRegisterAssignerFn } from 'attaform'

const widgetEl = useTemplateRef<HTMLDivElement>('widget')

const colorAssigner: CustomDirectiveRegisterAssignerFn = (_value, rv) => {
  const el = widgetEl.value
  if (!el || !rv) return false
  rv.setValueWithInternalPath(el.dataset.color ?? '')
  return true
}

onMounted(() => {
  const el = widgetEl.value
  if (el) {
    ;(el as HTMLDivElement & { [k: symbol]: CustomDirectiveRegisterAssignerFn })[assignKey] =
      colorAssigner
  }
})
```

The template anchor: `<div ref="widget" v-register="form.register('color')" />`. The `v-register` binding still goes on the element; the assigner is what reroutes the write step.

`assignKey` is `Symbol.for('attaform:assign-key')`, a well-known symbol so multiple installers (your code, a third-party wrapper, Attaform's own built-in assigners) can detect and coordinate.

## The function signature

```ts
type CustomDirectiveRegisterAssignerFn = (
  value: unknown,
  registerValue?: RegisterValue
) => boolean | undefined
```

| Arg             | Use                                                                                                                                                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`         | What the directive extracted from the event, post-transforms and post-coerce. May be `undefined` when the assigner reads its own state.                                                                                                               |
| `registerValue` | The `RegisterValue` for the current binding. Call `rv.setValueWithInternalPath(v)` to commit a write. Supplied by the directive on every fire regardless of install path, so the assigner doesn't have to capture the RV via closure at install time. |

Return `true` to signal the write was accepted, `false` to reject. `undefined` is treated as success, so simple assigners can `return` nothing.

## Reach for transforms first

If you just want to reshape the value before write (uppercase, trim, parse), reach for [register transforms](/docs/binding-inputs/transforms) instead. Transforms compose into a per-field pipeline declared at the call site, no element-level installation, no symbol indirection.

`assignKey` is for cases where the extracted value isn't right at all: different source, different shape, different element type. Web Components, custom widgets, third-party libraries that don't speak the standard DOM event surface.

## Where to next

- [Register transforms](/docs/binding-inputs/transforms): the higher-level option for value reshaping.
- [`useRegister`](/docs/binding-inputs/use-register): the composable for Vue component wrappers that need to re-bind v-register internally.
- [The `v-register` directive](/docs/binding-inputs/v-register): the directive layer custom assigners plug into.

_Source: https://attaform.dev/docs/binding-inputs/custom-assigners_

---

# Third-party components

> Already invested in a component library? Keep it. The same `v-register="form.register(path)"` that binds a native input also binds a component from the kit you already use.


Attaform's happy path is markup you control: a native `<input>`, or a small wrapper you wrote. That keeps the binding direct and the surface tiny, and it is what the rest of these docs reach for first. But plenty of teams already lean on a component library, and rewriting every field is not on the table. Attaform meets you there.

There is no separate API to learn for this. You write the same one line you would write on a native input, and Attaform does the reaching.

Here is `v-register` binding real components from two libraries, the same one line on each. Interact with any control and watch its value flow into the form while its field state lights up beside it:


reka-ui ships headless primitives, so each control above is unstyled markup the demo themes itself. PrimeVue ships fully themed components instead. The binding does not care either way:


## The one line you write

```vue
<script setup lang="ts">
  import { useForm } from 'attaform'
  import { z } from 'zod'
  // A text field from the component library you already use:
  import { TextField } from 'your-ui-kit'

  const schema = z.object({ email: z.email() })
  const form = useForm({ schema })
</script>

<template>
  <TextField v-register="form.register('email')" />
</template>
```

That is the whole integration. No `control` prop, no options bag, no adapter per library. The `form` handle is the same reactive form you use everywhere else, and `form.register('email')` is the same binding you would hand a native `<input>`.

## How Attaform reaches in

A native input gives `v-register` everything in one element. A component hides its real control behind a wrapper, so Attaform reaches in along two cooperating paths.

**The value rides the component's own `v-model`.** At compile time, Attaform sees `v-register` on a component and wires up the standard Vue model contract for you: it feeds `modelValue` from form state and listens for `update:modelValue` to write back. The value it passes is the typed value your schema expects, not a stringified DOM string, so a number field stores a number and a date field stores a `Date`. Because the value flows through the component's own `modelValue`, the server renders the seeded value straight into the HTML: the form is correct before hydration, no flash, no client-only patch.

**The field state comes from the real control.** At mount, the directive looks inside the component for the native control it renders and binds onto it. When it finds exactly one input, that control becomes the field's anchor: focus and blur tracking, the `connected` bit, the [aria attributes](/docs/binding-inputs/v-register#accessibility-handled), and the focus-and-scroll target for an invalid submit all light up on it, exactly as they would on a bare input.

Composite widgets are welcome too. A PIN input made of several boxes, or a slider built from `<div>`s with no native control at all, has no single element to anchor. Attaform notices, steps back from the single-element latch, and tracks focus at the widget root instead, so the field still knows when the reader is inside it. Tabbing between a widget's own parts stays focused; leaving it reads as a blur.

## When a component has more than one root

Vue hands a runtime directive to a component only when that component renders a **single element root**. A component whose template root is a fragment (several sibling nodes, as some combobox and select roots are) never receives the directive at all.

The value channel still works, because that rides the component's props and emits. What you lose is the directive half: the field's `connected` bit, focus tracking, aria, and scroll-to-error. In development, Attaform notices a value arriving from a component it never attached to and points it out, so the gap is loud rather than silent.

The fix is to give the directive a single element to land on:

```vue
<!-- Wrap the fragment-rooted component so v-register binds the wrapper. -->
<div v-register="form.register('country')">
  <FancyCombobox v-model="..." />
</div>
```

or reach for the component's own single-root option if it offers one.

## When the value lives somewhere else

Most Vue components speak the standard `modelValue` / `update:modelValue` contract, and those bind with nothing extra. For the ones that do not, Attaform has a tool sized to each case:

- **A different model name.** A component that emits `value` / `update:value` instead of the standard pair will not see Attaform's `modelValue`. Wrap it in a thin component that maps one to the other, then bind the wrapper. A few lines of composition, and it joins the happy path.
- **A value that is not a DOM property.** A widget that keeps its value on a method, a dataset attribute, or a custom property needs [a custom assigner](/docs/binding-inputs/custom-assigners): a per-element write function that decides what lands in form state.
- **A wrapper you wrote yourself.** When the component is your own and its root is not the input, [`useRegister`](/docs/binding-inputs/use-register) re-binds the parent's `v-register` onto the inner element directly. It is the most direct path whenever you can edit the component.

## Tested against real libraries

Attaform does not formally promise to support every component library in existence. What it offers is a set of careful heuristics, run at the directive and the compile-time transform, that make most standard Vue components bind without ceremony, plus the escape hatches above for the rest.

The demos above run reka-ui and PrimeVue live. Behind them, the cross-library test suite exercises `v-register` against the real rendered output of all three, [reka-ui](https://reka-ui.com), [PrimeVue](https://primevue.org), and [Nuxt UI](https://ui.nuxt.com): single-input fields, spinbuttons, composite PIN inputs, control-less sliders, and fragment-rooted comboboxes each land in the matrix, so the behavior described on this page is pinned, not promised.

## Where to next

- [The `v-register` directive](/docs/binding-inputs/v-register): the directive doing the reaching, and the accessibility it wires.
- [`useRegister`](/docs/binding-inputs/use-register): re-bind `v-register` inside a wrapper component you author.
- [Custom assigners](/docs/binding-inputs/custom-assigners): the write hook for non-standard value surfaces.
- [`injectForm`](/docs/cross-cutting-state/inject-form): for compound components binding several paths at once.

_Source: https://attaform.dev/docs/binding-inputs/third-party-components_

---

# `setValue` patterns

> The programmatic write surface: three call shapes, a callback option, and the `unset` sentinel for flagging any path blank.


Click the four buttons in the demo to exercise every `setValue` shape: string path, segment tuple, callback, whole-form. The reactive surface (`values`, `fields`, validation) updates the same way it does for directive-driven writes; `setValue` and `v-register` share the pipeline. The [Three call shapes](#three-call-shapes) section unpacks each form.


## Three call shapes

`setValue` accepts whatever shape fits the write site. Each example below assumes a `form` handle from `useForm({ schema })`:

```ts
const form = useForm({ schema })

form.setValue({ name: 'Ada', age: 30 }) // whole-form
form.setValue('profile.email', 'a@b.c') // dotted path
form.setValue(['profile', 'email'], 'a@b.c') // segment tuple
```

The dotted-path form is the most ergonomic for plain object schemas. The segment-tuple form sidesteps the dotted-key collision (a schema key that contains a literal `.`) and gives TypeScript precise typed-tuple inference. The whole-form shape replaces every path at once: useful for hydrating from a server response or applying external state.

## Callback form

Pass a function to read the current value and return the next:

```ts
form.setValue('count', (prev) => (prev ?? 0) + 1)
form.setValue('tags', (prev) => [...prev, 'new-tag'])
form.setValue(['profile', 'name'], (prev) => prev.trim().toLowerCase())
```

The callback receives the current value at the path; its return value lands in storage. Equivalent to reading `form.values.<path>`, computing the next value, and writing it, in one atomic step.

## Returns `boolean`

`setValue` returns `true` when the write was accepted, `false` when it was rejected by the slim-type gate (value didn't match the leaf's accept set). Reach for the return value when a downstream action depends on the write succeeding:

```ts
if (form.setValue('age', 21)) {
  /* proceed */
}
```

## Same pipeline as `v-register`

Every `setValue` call flows through the same write pipeline as the directive: slim-type gating, dirty / touched tracking, persistence, history. The reactive surface (`values`, `fields`, validation) reacts identically. No "programmatic writes are second-class" carve-out.

The one difference: `setValue` writes are **never coerced**. Coercion is for user-typed DOM strings; values you pass to `setValue` are already typed at the call site (TypeScript checks it), so coercion would be a no-op at best and a footgun at worst.

## Flagging a path blank

To flag a path as displayed-empty, pass the `unset` sentinel. The runtime writes the schema's slim value at that path and joins the path to `form.blankPaths` so the bound input renders empty.

```ts
import { unset } from 'attaform'

form.setValue('middleName', unset) // storage holds '', form.blankPaths has 'middleName'
form.setValue('profile', unset) // recursive, marks every primitive descendant
form.setValue('cargo', unset) // DU stub, writes { kind: '' } with no variant body
```

`unset` works at every path the consumer can address: primitive leaves, containers, arrays, tuples, records, discriminated unions, wrappers, and the root. See [the `unset` page](/docs/writing-and-mutating/unset) for the full contract.

## Where to next

- [`reset` & `resetField`](/docs/writing-and-mutating/reset): restore defaults instead of just writing.
- [`clear`](/docs/writing-and-mutating/clear): write blank values without going through defaults.
- [Field-array mutations](/docs/writing-and-mutating/field-arrays): append, insert, remove, swap, move, replace, prepend.
- [`unset`](/docs/writing-and-mutating/unset): the blank-anywhere sentinel for `defaultValues`, `setValue`, and `reset`.

_Source: https://attaform.dev/docs/writing-and-mutating/set-value_

---

# `reset` & `resetField`

> The defaults are the destination: `reset` for the whole form, `resetField` for one path. Both wipe state along with values.


Type into any field to flip it dirty. Click `resetField` to restore one path; click `reset()` to restore everything; click `reset(newDefaults)` to redirect the defaults AND restore in one call. The dirty markers and the form-level pristine/dirty status update reactively as state reset propagates.


## `reset()` restores defaults

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

Every path goes back to its `defaultValues` entry, or, where no override was given, to the schema-slim default (`''` for strings, `0` for numbers, `false` for booleans). Alongside the value reset:

- `dirty` flips false on every leaf.
- `touched` flips false on every leaf.
- `errors` clear at every path.
- `meta.submissionAttempts`, `meta.submitted`, and `meta.submitError` all zero (the submission surface returns to its initial state).

`reset()` is the right call after a successful submit when you want the form to look fresh, or when a "Discard changes" button needs to back out unsaved edits.

## `reset(nextDefaults)` redirects defaults

Pass a new defaults object to update the form's defaults AND reset in one step:

```ts
form.reset({ name: 'New Default', email: 'new@example.com' })
```

After this call, the new object IS the form's defaults for any subsequent `reset()` or `resetField` call. Useful when the form needs to switch contexts: editing record A then loading record B's values as the new baseline.

The argument is a `Partial<DefaultValuesInput<Form>>`. Fields you don't mention pick up the previous defaults. Pass `{}` to reset with no changes to the defaults.

## `resetField(path)` restores one path

```ts
form.resetField('email')
```

Same semantics as `reset()`, scoped to a single path:

- Value goes back to the path's default.
- `dirty` and `touched` flip false at that path.
- Errors at that path clear.

Useful when one field's been edited but the user wants to discard just that change while keeping the rest of the form's edits in place.

## Reset vs clear

`reset` and `resetField` go to **defaults**. [`clear`](/docs/writing-and-mutating/clear) goes to **blank**: the schema-slim empty value, skipping defaults. Pick reset when "back to baseline" is the goal; pick clear when "wipe to zero" is.

## Where to next

- [`setValue` patterns](/docs/writing-and-mutating/set-value): write specific values without going through defaults.
- [`clear`](/docs/writing-and-mutating/clear): wipe to blank values, defaults intentionally skipped.
- [Submit lifecycle](/docs/submitting/handle-submit): handlers that pair reset with successful submits.

_Source: https://attaform.dev/docs/writing-and-mutating/reset_

---

# `clear` & blank values

> Wipe to the schema's empty shape, not to defaults. For "blank canvas" UX where defaults would be the wrong destination.


Click the per-field clear buttons to watch each path drop to its schema-slim empty value: `''` for the string title, `[]` for the tags array, `false` for the published boolean. Click `clear()` to wipe everything. The defaults declared on `useForm` are intentionally skipped; that's the distinction from `reset`. The blank flag on each field flips on to mark the cleared state.


## What "blank" means

`clear` writes the **schema-slim** empty value at each cleared path:

| Leaf type     | Cleared value         |
| ------------- | --------------------- |
| `z.string()`  | `''`                  |
| `z.number()`  | `0`                   |
| `z.boolean()` | `false`               |
| `z.array()`   | `[]`                  |
| `z.object()`  | `{}` (then descended) |
| `z.date()`    | `new Date(0)`         |
| `z.file()`    | `null`                |

Same shapes Attaform uses for the initial defaults when nothing is declared in `defaultValues` or `schema.default(...)`. The blank predicate (`fields.<path>.blank`) flips true at every cleared path.

## Clear is not reset

The key distinction: `clear` skips defaults; `reset` restores them. Pick clear when the user-facing intent is "blank canvas": a fresh draft, a wipe, a "start over from nothing". Pick `reset` when the intent is "back to baseline": the form's authoritative starting state.

```ts
form.reset() // values.title === 'A great draft'  (the default)
form.clear() // values.title === ''  (the schema-slim empty)
```

Both wipe `dirty` / `touched` along with the value; both surface the same reactive pipeline.

## Three call shapes

```ts
form.clear() // whole form
form.clear('profile.email') // dotted path
form.clear(['profile', 'email']) // segment tuple
```

Same call ergonomics as `setValue`. The whole-form call clears every path recursively; the per-path forms scope to one leaf or container.

## Returns `boolean`

`true` on accepted writes, `false` when the slim-type gate rejects (rare; the empty value should always be valid for the path's accept set, but containers with required fields may flag).

## When `clear()` is the right call

- A "Compose new" button in a draft UI where the user expects an empty canvas, not a re-populated form.
- After a successful submit when the next interaction should start from nothing rather than the previous defaults.
- Implementing a "Discard and start over" affordance distinct from "Undo my edits".

For "go back to the baseline this form was hydrated with," reach for [`reset`](/docs/writing-and-mutating/reset) instead.

## Where to next

- [`reset` & `resetField`](/docs/writing-and-mutating/reset): restore defaults instead of clearing.
- [`unset`](/docs/writing-and-mutating/unset): flag any path blank in `defaultValues`, `setValue`, or `reset`.
- [Display state and showing errors](/docs/validation/showing-errors): how blank fields interact with the error-display predicate.

_Source: https://attaform.dev/docs/writing-and-mutating/clear_

---

# `unset`

> A consumer-side shorthand for "this path starts blank." The runtime writes the schema's slim value at that path, joins every primitive descendant to `form.blankPaths`, and the bound input renders empty until the user types.


The demo carries a primitive leaf (`email`) and a container (`profile` with `name` + `age`). Click `setValue('email', unset)` to flag the leaf blank, or `setValue('profile', unset)` to flag the whole container blank. The panel shows storage (always concrete, never the sentinel) and the live `blankPaths` set.


## What `unset` does

`unset` is a sentinel symbol exported from every entry point. Pass it as a value in `defaultValues`, `setValue`, or `reset`. The runtime translates it into two effects at the targeted path:

1. **Storage** receives the schema's slim concrete. For primitive leaves that's `''`, `0`, `0n`, `false`. For `.optional()` wrappers it's `undefined`; for `.nullable()` it's `null`. For container paths the runtime recurses: an object writes a shape with every leaf at its slim, an array writes `[]`, a tuple writes its slim positions, a record writes `{}`, a discriminated union writes `{ <discriminatorKey>: '' }` with no variant body.
2. **`form.blankPaths`** gains every primitive descendant under the target. The `v-register` directive reads from the same set when binding the DOM input, so the field renders empty even though storage holds a concrete value.

Reads through `form.values.<path>` always see the slim value. Storage never holds the sentinel symbol.

## Where `unset` can land

The sentinel works at every position the consumer can address:

```ts
import { unset, useForm } from 'attaform'

const schema = z.object({
  email: z.string(),
  profile: z.object({ name: z.string(), age: z.number() }),
  tags: z.array(z.string()),
  cargo: z.discriminatedUnion('kind', [
    z.object({ kind: z.literal('boat'), length: z.number() }),
    z.object({ kind: z.literal('truck'), payload: z.number() }),
  ]),
})

const form = useForm({
  schema,
  defaultValues: {
    email: unset, // primitive leaf
    profile: unset, // container, marks profile.name and profile.age
    tags: unset, // array, writes []
    cargo: unset, // DU, writes { kind: '' } stub, no variant body
  },
  key: 'demo',
})
```

The same value works on every imperative write:

```ts
form.setValue('profile', unset) // re-blank the whole profile sub-tree
form.setValue('cargo', unset) // reset cargo to a no-variant-selected state
form.reset({ tags: unset, email: unset }) // baseline that re-applies on reset()
```

Root-level `unset` is admitted too. `defaultValues: unset` or `form.reset(unset)` walks the whole schema, marking every primitive descendant blank. Useful for "the user must touch every field" workflows where presence carries audit weight: a housing application form that needs to record "client manually set income to 0" separately from "income defaulted to 0."

## Container behavior, in detail

| Position                       | Storage write                          | `blankPaths` adds                         |
| ------------------------------ | -------------------------------------- | ----------------------------------------- |
| Primitive leaf                 | Schema's slim primitive                | The leaf path                             |
| Bare object                    | Recursive slim subtree                 | Every primitive descendant under the path |
| Array / tuple / record         | `[]` / slim tuple / `{}`               | The container path itself                 |
| Discriminated union container  | `{ <discriminatorKey>: <kind-blank> }` | The discriminator's path                  |
| `.optional()` wrapper          | `undefined`                            | The wrapper path                          |
| `.nullable()` wrapper          | `null`                                 | The wrapper path                          |
| Date / RegExp / Map / Set leaf | The schema's slim concrete             | The leaf path                             |

The container path itself does NOT enter `form.blankPaths`. `form.fields('profile').blank` derives reactively from the conjunction "every primitive descendant is blank," so an empty container reads blank by vacuous truth, and one descendant filled flips the container's blank false automatically.

## Reading the blank state

`form.values.<path>` returns concrete storage. Read the displayed-empty state through `form.fields`:

```ts
form.fields.email.blank // true after setValue('email', unset)
form.fields('profile').blank // true when every descendant of profile is blank
```

`form.blankPaths.value` exposes a `BlankPathsView` (Set-like: `size`, `has(input)`, `values()`, plus a `Symbol.iterator`) for callers that want the whole list (persistence, debug overlays). The `v-register` directive reads the same signals and renders the DOM empty.

## Required schemas raise `no-value-supplied`

A required leaf sitting in `form.blankPaths` surfaces an error in `form.errors`:

```ts
const schema = z.object({ income: z.number() }) // required
const form = useForm({ schema, defaultValues: { income: unset } })

form.errors.income // [{ code: 'atta:no-value-supplied', … }]
form.fields('income').blank // true
```

`.optional()`, `.nullable()`, and `.default(N)` schemas accept the empty case. Those leaves still sit in `form.blankPaths` (the directive needs the signal to render the input empty), but no error fires. See [the `blank` field-state bit](/docs/validation/blank) for the full lifecycle.

## Cross-entry availability

`unset` and `isUnset` ship from every entry point: `attaform`, `attaform/zod`, `attaform/zod-v3`, `attaform/zod-v4`. The `Unset` type is exported alongside for explicit type annotations:

```ts
import { unset, isUnset, type Unset } from 'attaform'

function maybeBlank(v: string | Unset): string | undefined {
  return isUnset(v) ? undefined : v
}
```

`isUnset` is a type guard for explicit narrowing of `value: T | Unset` payloads (input parameters, `setValue` callbacks). It is NOT a `form.values` check: storage never holds the symbol, so `isUnset(form.values.<path>)` always returns `false`.

## Where to next

- [The `blank` field-state bit](/docs/validation/blank): the storage / display side-channel `unset` plugs into.
- [`setValue` patterns](/docs/writing-and-mutating/set-value): the imperative write surface.
- [Defaults from the schema](/docs/schemas/defaults): how schema-declared defaults and `unset` interact at mount time.

_Source: https://attaform.dev/docs/writing-and-mutating/unset_

---

# Field-array mutations

> Seven shape-changing helpers, typed against every array path in your schema. Stable per-item identity across moves, removes, and swaps.


Use the row arrows and per-row × button to move and remove items; the buttons below dispatch every helper against the array. Watch the readout: the order, count, and contents reflect each call. Stable keys mean per-item validation state, dirty bits, and DOM focus survive shape changes; reordering doesn't reset what the user typed.


## The seven helpers

Each helper is typed against the form's `ArrayPath<Form>` set; TypeScript autocompletes only the paths that actually point at an array. The value-shape generic narrows on the inferred element type.

| Helper                        | Signature         | What it does                                            |
| ----------------------------- | ----------------- | ------------------------------------------------------- |
| `append(path, value)`         | adds at the end   | Appends one item to the array.                          |
| `prepend(path, value)`        | adds at index 0   | Adds one item to the front; shifts the rest right.      |
| `insert(path, index, value)`  | adds at index     | Inserts one item; shifts subsequent items right.        |
| `remove(path, index)`         | drops at index    | Removes one item; shifts subsequent items left.         |
| `swap(path, a, b)`            | swaps two indices | Exchanges the items at the two indices.                 |
| `move(path, from, to)`        | moves an item     | Removes from `from` and re-inserts at `to` in one step. |
| `replace(path, index, value)` | replaces at index | Overwrites the item at `index` without changing length. |

## Reading the path

```ts
const form = useForm({
  schema: z.object({
    checkpoints: z.array(z.string()),
  }),
})

form.append('checkpoints', 'New checkpoint')
form.remove('checkpoints', 2)
```

The path string autocompletes to every array path in the schema. Nested arrays work the same way: `register('teams.0.players')` for an inner array, and the helpers take the same form.

## Stable per-item identity

Every helper preserves the existing items' reactive identity, and an item's full state travels with it to its new index:

- `append` leaves indices 0..n unchanged.
- `prepend`, `insert`, `swap`, and `move` carry the moved item's value, its original baseline, its dirty and touched state, any error you set on it, its blank display, and its bound DOM element to the new index. Nothing bleeds onto the item that shifts into the vacated slot.
- `remove` drops the removed item's state; `replace` starts the incoming item fresh.

Practical consequence: a user typing in row 3, hitting "Move up", finishes typing in row 2 without losing focus or having the entered text reset. A row already marked dirty stays dirty at its new index, and the row that shifts into the old slot keeps its own clean state. Attaform tracks the item, not the slot.

Because each item carries its own baseline, Attaform still reads a structural change as a change: a reorder, insert, or removal leaves `form.meta.dirty` true even when every surviving item matches its own baseline.

## Validation per item

Per-item validation tracks the item, not the slot. An error you set with `form.setErrors` on `checkpoints.0` follows the item through a `move(0, 4)` to `checkpoints.4`. Schema verdicts recompute from the live value after each shape change, so a still-invalid item shows its error at its new index, and a removed item's verdict clears at once instead of lingering on whatever shifts into the slot.

For array-level refinements (`z.array(...).min(3)` or `.refine(arr => arr.length > 0)`), the error lands at the array path itself, not at any slot. Read it via `form.errors('checkpoints')` (or `form.fields('checkpoints').firstError`).

## Reset behavior

`reset()` restores the array's default: same length, same item values, every item back to its pre-edit state. `clear('checkpoints')` writes `[]`. No special "reset the array's helpers", same pipeline as the rest of the writes.

## Where to next

- [`form.list`](/docs/reading-the-form/list): iterate the array as one FieldState per element, keyed by `key` so a `v-for` survives every reorder.
- [`setValue` patterns](/docs/writing-and-mutating/set-value): when you need to write the whole array, not mutate one slot.
- [`reset` & `resetField`](/docs/writing-and-mutating/reset): restore the array to its baseline.
- [Display state and showing errors](/docs/validation/showing-errors): array-level error display.

_Source: https://attaform.dev/docs/writing-and-mutating/field-arrays_

---

# Variant memory

> Switching away from a discriminated-union variant doesn't have to mean losing what was typed. Memory snapshots ride alongside the active state and rehydrate on switch-back. Opt out when the variants are unrelated or memory matters.


Two side-by-side forms with the same payment schema. Type into the card variant, switch to bank, switch back. The left form (`rememberVariants: true`) restores your card details; the right form (`rememberVariants: false`) starts fresh every switch. Same schema, opposite memory policy.


## The default

```ts
useForm({
  schema,
  // rememberVariants: true is Attaform's default
})
```

Switching back to a previously-visited variant lands on its prior subtree, including nested fields. Each discriminated union at every nesting depth is independently memorized: a top-level union and a nested one each keep their own memory map.

## Opting out

```ts
useForm({ schema, rememberVariants: false })
```

With `false`, every switch drops the outgoing variant's typed state. The new variant initializes from its slim default; the old data is gone.

Use the opt-out when:

- **The variants represent unrelated data.** A "contact preference" picker between phone and email should clear the phone when switching to email.
- **Memory leaks user input you don't want re-applied.** A wizard step that should reset when the user backtracks.
- **Memory-constrained targets.** Snapshots are small per-union, but a deeply nested form with many unions accumulates.

## Per-app default

Set the default app-wide via the plugin:

```ts
createAttaform({
  defaults: { rememberVariants: false },
})
```

Per-form `useForm({ rememberVariants: true })` overrides back to memory-on for forms that want it.

## What gets memorized

When the discriminator value flips:

1. The current variant's subtree is snapshotted into the memory map keyed by the outgoing variant's discriminator value.
2. The new variant's slim default seeds storage.
3. On a subsequent switch to a remembered variant, the snapshot rehydrates over the seeded default.

What's stored: the value subtree only. Field-state (touched, blurred, focused, etc.) is NOT part of the snapshot; that travels with the active field state, which lives outside the union's storage tree.

## Memory is in-memory only

Variant memory does NOT survive a page reload. Persisted state (`useForm({ persist: 'local' })`) restores values into form storage on hydration, but the variant memory map starts empty: the first discriminator switch after reload loses any persisted typing in the outgoing variant.

For cross-session continuity of inactive-variant typing, persist beyond the union boundary yourself. Mirror the inactive subtree into a separate persisted slot via a watcher on the discriminator.

## `reset()` and `resetField()` interactions

- **`reset()`** clears all variant memory. The reset state becomes the new "no memory" baseline.
- **`resetField(path)`** clears any memory entry whose union path equals or sits under `path`. Resetting a single union's path drops only that union's memory; sibling unions retain theirs.

## Where to next

- [Discriminated unions](/docs/schemas/discriminated-unions): the schema feature variant memory rides on top of.
- [`reset` & `resetField`](/docs/writing-and-mutating/reset): both interact with the memory map deterministically.
- [App-wide defaults](/docs/cross-cutting-state/app-defaults): set `rememberVariants` once for every form in the app.

_Source: https://attaform.dev/docs/writing-and-mutating/variant-memory_

---

# When validation runs

> Per-field validation triggers on `change`, `blur`, or `submit`: your call, per form. Sync refinements fire immediately; async refinements await.

Validation timing is configured per form via the `validateOn` option:

```ts
const form = useForm({
  schema,
  validateOn: 'change', // default
})
```

## Triggers

| Value                | Per-field validation fires on                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `'change'` (default) | Every committed write to storage. Pairs with the directive's commit cadence (per-keystroke by default, per-blur on `.lazy`). |
| `'blur'`             | When the input loses focus.                                                                                                  |
| `'submit'`           | Only when `handleSubmit` dispatches.                                                                                         |

The directive's commit cadence and the validation trigger are independent. With default `<input v-register>` and `validateOn: 'change'`, both fire per keystroke. Switch to `<input v-register.lazy>` and validation still rides the commit, which now lands on `change` (per-blur). Switch to `validateOn: 'blur'` and validation skips the per-write rhythm entirely.

The same schema runs in every mode: the only thing that changes is _when_ a refinement gets evaluated.


Under `validateOn: 'blur'`, leaving a field you never edited can't change any verdict, so Attaform skips the pass: it tracks whether the form has changed since the last validation and only revalidates when it has. Refocus a field that's showing an error, then tab away, and the error holds steady instead of blinking through `'pending'` and back.

## Debouncing

Pass a `debounceMs` to coalesce rapid bursts:

```ts
useForm({
  schema,
  validateOn: 'change',
  debounceMs: 200,
})
```

The field's last committed write wins after `debounceMs` of quiet. Useful for expensive sync refinements; required for async refinements that hit a network (otherwise every keystroke fires a request).

`debounceMs` is only meaningful with `validateOn: 'change'`. TypeScript rejects pairing it with `'blur'` or `'submit'`, so a misconfigured form is a compile error rather than a silent runtime drop.

## Sync versus async

Sync refinements (`refine`, `superRefine` with synchronous returns) run on the trigger. Async refinements (anything that returns a Promise) are awaited:

- During typing (`validateOn: 'change'`), the field's `form.fields.<path>.validating` flips true while the Promise is in flight.
- On submit, `handleSubmit` waits for every active async refinement to settle before calling the success callback.
- `form.meta.valid` only flips true once every active path has resolved at least one validation pass, including the async ones. No flash-of-valid window.

## Where to next

- [Display state and showing errors](/docs/validation/showing-errors): the `getDisplayState` predicate.
- [`errors`](/docs/reading-the-form/errors): per-path error reads.

_Source: https://attaform.dev/docs/validation/when-validation-runs_

---

# Per-field validation

> The schema is the validator. Chain refinements onto one leaf, or attach cross-field rules to the parent with a target path.


Type into each field to watch its own refinements light up: the username's regex requirement, the password's min length, and the cross-field "passwords must match" check that fires when `confirmPassword` differs from `password`. Both single-field and cross-field validators live in the schema; the [Two patterns](#two-patterns) section traces each.


## Two patterns

Attaform reads two Zod patterns for per-field validation, both surfacing errors at the right `form.errors.<path>`.

### Single-field chains

Every Zod primitive accepts a chain of refinements:

```ts
z.object({
  username: z
    .string()
    .min(3, 'At least 3 characters')
    .max(20, 'At most 20 characters')
    .regex(/^[a-z0-9_]+$/, 'Lowercase letters, numbers, and underscores only'),
})
```

Each refinement's error message appears at `errors.username`. The order matters: refinements stop at the first failure, so `.min(3)` runs before `.regex`. Read the field's `firstError` to get the first failure's message; the full array is available at `errors.<path>` for surfacing every refinement that fired.

### Cross-field refinements

For checks that involve multiple paths, attach `.refine` to the parent object and use the `path` option to target where the error lands:

```ts
z.object({
  password: z.string().min(8),
  confirmPassword: z.string(),
}).refine((data) => data.password === data.confirmPassword, {
  message: 'Passwords must match',
  path: ['confirmPassword'],
})
```

The refinement runs against the whole parent value; the `path` option directs the error to `errors.confirmPassword` so the UI surfaces it next to the right input. Without `path`, the error lands at the parent path (the form root in this example).

## Custom per-field refinements

For predicates beyond the built-in chain, use `.refine` at the leaf:

```ts
z.string().refine((v) => !v.includes('admin'), {
  message: 'Reserved word, pick another username',
})
```

The function receives the parsed leaf value; return `true` to accept, `false` to reject. The message string surfaces as the error's `.message`.

## Sync vs async

Sync refinements run on every validation pass: keystroke, blur, submit (per the [validateOn config](/docs/validation/when-validation-runs)). For checks that need a server round-trip (uniqueness probes, slug availability, password-breach lookups), reach for [async refinements](/docs/validation/async-refinements). Zod's `.refine` accepts an async predicate, and Attaform awaits it before submit dispatches.

## Where to next

- [Async refinements](/docs/validation/async-refinements): predicates that await a server round-trip.
- [The validation lifecycle](/docs/validation/lifecycle): the three imperative methods (`validate`, `validateAsync`, `process`).
- [When validation runs](/docs/validation/when-validation-runs): the `validateOn` timing knob.
- [Display state and showing errors](/docs/validation/showing-errors): the `getDisplayState` predicate.

_Source: https://attaform.dev/docs/validation/per-field-validation_

---

# Async refinements

> Predicates that await a server round-trip: uniqueness probes, slug availability, password-breach lookups. Same surface as sync refinements, just with `async`.


Type a username and blur the field to watch `validating` flip true for ~700ms while the simulated check runs. Try `ada`, `champ`, or `athlete` to see the "taken" error land. Try any unused name to see it accept. The submit handler awaits every in-flight refinement before dispatching; submitting mid-check holds until the check resolves.


## Declare an async predicate

Zod's `.refine` accepts an `async` function:

```ts
z.string().refine(async (v) => isAvailable(v), {
  message: 'That username is taken',
})
```

The predicate runs alongside sync refinements; the chain awaits its resolution before deciding pass / fail. Attaform forwards the awaited result to `form.errors.<path>` and `fields.<path>` like any other refinement.

## In-flight signal

While an async refinement is pending at a path:

- `fields.<path>.validating` is `true`.
- `meta.validating` is `true` when ANY field has a pending async refinement.

Render a "Checking…" indicator next to the field:

```vue
<small v-if="fields.username.validating">Checking availability…</small>
```

This is per-field UX; for a form-level spinner reach for `meta.validating` instead.

## `handleSubmit` awaits

The submit handler waits for every pending async refinement before deciding pass / fail:

1. Sync validation runs across every active path.
2. Async refinements await.
3. If every refinement passes, `onSubmit(values)` fires with the parsed Zod output.
4. If anything fails, focus pulls to the first invalid field and `onError(errors)` fires.

Submitting mid-check is safe: the handler holds until the check resolves, then routes through `onSubmit` or `onError`. No flash-of-valid window where the user hits submit while a slow uniqueness probe hasn't finished.

## Debouncing keystroke triggers

By default, sync refinements run on every committed write (with `validateOn: 'change'`, which pairs with the directive's per-keystroke commit). For async refinements, you usually want **blur**: server probes shouldn't fire on every keystroke. Set `validateOn: 'blur'` per form:

```ts
useForm({
  schema,
  validateOn: 'blur', // async probes fire on blur, not keystroke
})
```

Blur fires the probe only when the value actually changed since the last pass, so refocusing a field and tabbing away without editing it won't re-hit the server.

Or stay on the per-keystroke trigger and coalesce bursts with `debounceMs`:

```ts
useForm({
  schema,
  validateOn: 'change',
  debounceMs: 400, // wait 400ms of quiet before validating
})
```

See [When validation runs](/docs/validation/when-validation-runs) for the full timing API.

## Race-safety

Two rapid edits before the first probe returns: the directive cancels the stale in-flight request (where the underlying client supports `AbortSignal`) or ignores its result (where it doesn't). The newest probe's result is the one that lands in `errors.<path>`. No "earlier request resolves last, overwrites the correct error" race.

## Validation, not persistence

An async refinement's job is to return a verdict: it reads a value and answers "is this allowed?". Writing to your server inside that same loop (saving the value while you check it) is tempting, but it tangles two concerns, validity and persistence, into one predicate. Keep the refinement a pure read, and persist on change through an [autosave](/docs/cross-cutting-state/autosave) instead.

The two compose cleanly. An [autosave](/docs/cross-cutting-state/autosave) handler can gate its write on `await form.validateAsync(path)`, so the refinement you wrote here decides whether the save fires. One value check, reused for both the error message and the save gate.

## Where to next

- [Autosave](/docs/cross-cutting-state/autosave): the watch-based recipe for persisting values as they change.
- [The validation lifecycle](/docs/validation/lifecycle): the imperative `validateAsync()` for non-submit code paths.
- [When validation runs](/docs/validation/when-validation-runs): the `validateOn` cadence knob.
- [`handleSubmit`](/docs/submitting/handle-submit): the dispatch surface that awaits async refinements.

_Source: https://attaform.dev/docs/validation/async-refinements_

---

# URL availability check (preprocess + async refine)

> Two cooperating layers. Preprocess augments the user's input into a full URL. Async refine checks it against a backend, with sentinels for "empty" and "malformed" so refine can skip the network when there's nothing worth asking. A cache makes repeat checks free.



## What the form needs to do

A signup form takes a site URL. Users type informally (`example.com`, not `https://example.com`). The form has to:

1. Accept whatever the user types verbatim, so the input cursor never jumps under their fingers.
2. Augment the value to a full URL when checking it.
3. Ask the backend whether the URL is already taken.
4. Surface a specific message for each failure mode: empty, malformed, or taken.
5. Avoid hammering the backend on every keystroke; reuse previous answers.

Preprocess and async refine map onto that work cleanly. Preprocess **prepares** the value (trim, add protocol, decide whether it's URL-shaped at all). Refine **validates** it (ask the backend, surface a message). Storage stays as the user's raw text, so re-rendering, persistence, and history all carry the input the user actually typed.

## The schema

Hoist the schema next to the form so the type flows through `useForm` cleanly. Two sentinels (`EMPTY_URL` and `INVALID_URL`) bridge the two layers; both are strings so the inner `z.string()` accepts them, and refine recognizes them by exact equality.

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

const EMPTY_URL = '__atta:empty-url__'
const INVALID_URL = '__atta:invalid-url__'

const TAKEN = new Set(['https://google.com', 'https://apple.com', 'https://github.com'])
const availabilityCache = new Map<string, boolean>()

async function checkAvailability(url: string): Promise<boolean> {
  const cached = availabilityCache.get(url)
  if (cached !== undefined) return cached
  await new Promise((r) => setTimeout(r, 350))
  const available = !TAKEN.has(url)
  availabilityCache.set(url, available)
  return available
}

function formatUrl(v: unknown): string {
  if (typeof v !== 'string') return INVALID_URL
  const trimmed = v.trim()
  if (trimmed.length === 0) return EMPTY_URL
  const withProtocol = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`
  try {
    const parsed = new URL(withProtocol)
    // WHATWG URL accepts `https://ersdg` and `https://a.b` as
    // structurally valid. Require a TLD of at least two characters so
    // the demo rejects domain-less and 1-char-suffix strings the way
    // a real signup form would.
    const dot = parsed.hostname.lastIndexOf('.')
    if (dot === -1) return INVALID_URL
    if (parsed.hostname.length - dot - 1 < 2) return INVALID_URL
    return parsed.href.replace(/\/$/, '')
  } catch {
    return INVALID_URL
  }
}

const schema = z.object({
  url: z.preprocess(
    formatUrl,
    z.string().refine(
      async (val) => {
        if (val === EMPTY_URL || val === INVALID_URL) return false
        return checkAvailability(val)
      },
      {
        error: (issue) => {
          const val = issue.input as string
          if (val === EMPTY_URL) return 'Please enter a URL.'
          if (val === INVALID_URL) return "That doesn't look like a URL."
          return `${val} is already taken.`
        },
      }
    )
  ),
})

const form = useForm({ schema, key: 'url-check' })
```

## How the layers split the work

Preprocess and refine each own a single decision.

**Preprocess decides what shape the value is in.** It receives whatever the consumer wrote (`unknown` at the type level under the [storage contract](/docs/schemas/storage-shape)) and produces one of three string outputs: a fully-qualified URL, the empty sentinel, or the invalid sentinel. The function is synchronous, so it never holds up the write boundary; storage at `form.values.url` keeps the raw text the user typed.

**Refine validates the prepared value.** It sees the post-preprocess string. Sentinels short-circuit straight to failure; real URLs go through `checkAvailability`. Refine also owns the error messages: it has all the context (the value, the sentinel) to pick the right copy without preprocess having to thread it through.

**The cache is a Map keyed on the post-preprocess URL.** Repeat checks against the same URL hit the cache instead of the simulated network, so a user who types `google.com`, edits it to `apple.com`, then back to `google.com` only pays the API cost twice. In production, you'd populate the cache from a SWR / TanStack Query layer rather than rolling your own.

## Three messages, one validator

| User input         | Preprocess returns       | Refine outcome | Error message                          |
| ------------------ | ------------------------ | -------------- | -------------------------------------- |
| `''` (empty input) | `EMPTY_URL`              | invalid        | "Please enter a URL."                  |
| `'###'`            | `INVALID_URL`            | invalid        | "That doesn't look like a URL."        |
| `'google.com'`     | `'https://google.com'`   | invalid        | "https://google.com is already taken." |
| `'attaform.dev'`   | `'https://attaform.dev'` | valid          | (none, form submits)                   |

Every message comes out of the refine layer. Preprocess never raises an error itself; it just hands a value over for refine to grade. This is the cleanest division: validation messages all live in one place.

## Storage stays raw

Under the [storage contract](/docs/schemas/storage-shape), `form.values.url` holds whatever the user typed, never the post-preprocess value and never the sentinel. The directive re-renders the input from storage, so the user always sees their own text. The sentinels live only inside the parse pipeline (preprocess output → refine input); they never leak to the surface.

This split is what makes the recipe work. Under a "preprocess mutates storage at write" model, typing `google.com` would jump to `https://google.com` mid-edit, the cursor would land in the middle of "google", and the sentinel pattern would surface in `form.values.url` as a magic string. Under the no-write-mutation contract, the typed value is the displayed value is the stored value, and the parsed view is reached through `handleSubmit`, `validate`, or `validateAsync`.

## Reaching the typed result

Submit hands the success callback the post-parse output: preprocess has augmented the URL, refine has confirmed availability, and the cache holds the answer for the next pass.

```ts
const onSubmit = form.handleSubmit((data) => {
  data.url // 'https://attaform.dev', full URL, augmented + checked
  // POST to the signup endpoint…
})
```

If you need the typed shape outside submit, call `form.validateAsync()` or `form.parse()`. Both run the same pipeline against current storage and return the post-parse output.

## Tweaks

- **One sentinel instead of two.** If you only need a single "rejected" message ("That URL won't work"), collapse `EMPTY_URL` and `INVALID_URL` into one sentinel and short-circuit refine on that single check. You lose the empty-vs-malformed distinction but the schema gets a few lines shorter.
- **Throttle the network round-trip.** The form checks on every change by default. For a network-backed check you'll usually want `validateOn: 'blur'` (hit the endpoint when the field loses focus) or `validateOn: 'submit'` (defer entirely), optionally paired with `debounceMs` to coalesce bursts. The cache absorbs repeat checks regardless.
- **Invalidate on success.** After a successful signup, call `availabilityCache.delete(submittedUrl)` so a subsequent re-check picks up the new "taken" state on the server.
- **Real backend.** Swap the `setTimeout`-based `checkAvailability` for your API call. A library like TanStack Query gives you the cache + de-duplication for free; the schema stays exactly as written.

## Where to next

- [The storage contract](/docs/schemas/storage-shape): why preprocess and coerce keep storage raw, and how the two-layer model splits responsibilities.
- [Async refinements](/docs/validation/async-refinements): the broader lifecycle around async refine, debouncing, and the validating state.
- [Display state and showing errors](/docs/validation/showing-errors): when to render `form.errors.url` so the user sees the message at the right moment.

_Source: https://attaform.dev/docs/validation/url-availability-check_

---

# The validation lifecycle

> Three imperative entry points to the same validator. Pick by what you need next: reactive read, awaited verdict, or parsed payload.


Click each button to dispatch the matching method against the current form values. The result panel surfaces the return shape of each: a reactive status snapshot from `validate()`, an awaited verdict from `validateAsync()`, and the fully parsed Zod output from `parse()`. The methods share the predicate pipeline; the differences are about what they hand you back.


## `validate(path?)`

```ts
const status = form.validate()
// status.value.pending: true while async refinements are in flight
// status.value.success: true once everything passes (after settling)
```

Returns a `Readonly<Ref<ReactiveValidationStatus<Form>>>`, Vue's reactive surface for the validation result. Reads inside `computed` / `watchEffect` / templates track changes; the ref re-renders consumers when the verdict flips.

Sync-only by nature: the predicate work runs synchronously, but async refinements get observed via the `pending` flag rather than awaited. Use `validate()` when you want a reactive "is this valid right now?" read without holding up the caller.

Optional `path` argument scopes the validation to a subtree (`validate('profile.email')` runs predicates only for that path).

## `validateAsync(path?)`

```ts
const result = await form.validateAsync()
if (result.success) {
  // every refinement passed, including async ones
}
```

Returns a `Promise<ValidationResponseWithoutValue<Form>>`. Awaits every async refinement before resolving; the result is the final verdict.

Use this for non-submit code paths that need a synchronous-feeling "is this valid?" gate: a "Save draft" button that can write partial state but wants to know whether the data is shippable, a step-completion guard in a multi-step flow, anything that needs to react after every check has settled.

## `parse(path?)`

```ts
const result = await form.parse()
if (result.success) {
  await api.send(result.data) // parsed Zod output
}
```

Returns a `Promise<ValidationResponse<GetValueFormType>>`, the same shape as `validateAsync` plus the parsed value when validation passes. The parsed value runs through Zod's transforms and refinements, so `result.data` reflects every `.transform(...)` and `.preprocess(...)` in the schema.

`parse` is always async, and there is no synchronous variant by design. A schema can grow an async refinement or transform at any moment, and a sync parse would quietly skip it the instant one lands. One always awaited `parse` closes that whole category, so the call reads the same way every time: `await form.parse()`.

Use `parse` when validation success means dispatching the parsed output to an API or downstream pipeline; `handleSubmit` is built on top of it.

## Choosing between the three

| Need                                                 | Reach for                                         |
| ---------------------------------------------------- | ------------------------------------------------- |
| Reactive "is this valid?" read in a template         | `validate()` (or `meta.valid`)                    |
| Awaited verdict in a code path                       | `validateAsync()`                                 |
| Awaited verdict + parsed payload to ship             | `parse()`                                         |
| Submit gate that calls `onSubmit` with parsed values | `handleSubmit()` (which calls `parse` internally) |

For most form UX, you reach for `meta.valid` (reactive read) and `handleSubmit` (gated dispatch). The three lifecycle methods are escape hatches for the cases where those two don't fit.

## Where to next

- [Per-field validation](/docs/validation/per-field-validation): the predicate patterns the lifecycle runs against.
- [Async refinements](/docs/validation/async-refinements): what `validateAsync` and `parse` await.
- [When validation runs](/docs/validation/when-validation-runs): the `validateOn` cadence that drives passive runs.
- [`handleSubmit`](/docs/submitting/handle-submit): the dispatch surface built on top of `parse`.

_Source: https://attaform.dev/docs/validation/lifecycle_

---

# Display state and showing errors

> Errors exist in the store the moment validation runs; the display state decides what the UI surfaces, and when.


Every path on a form carries a single display-state verdict, `field.displayState`, that is one of four values:

- `'idle'`: nothing to surface yet.
- `'pending'`: a check has been running long enough to earn a spinner.
- `'error'`: a blocking error is ready to show.
- `'success'`: the field has passed and earned its green check.

`getDisplayState` is the one heuristic that resolves that verdict, and it runs for every field. Attaform's default holds back until the user has actually interacted with a field, so a fresh-page form does not open with every required field already complaining.


## Sugar over the verdict

The four `show*` booleans are exact projections of `displayState`, so they can never disagree with it:

| Boolean       | True when                    |
| ------------- | ---------------------------- |
| `showErrors`  | `displayState === 'error'`   |
| `showPending` | `displayState === 'pending'` |
| `showSuccess` | `displayState === 'success'` |
| `showIdle`    | `displayState === 'idle'`    |

Bind whichever reads cleanest. A field that narrates all of its states in one template block:

```vue
<input v-register="form.register('email')" />
<p v-if="form.fields.email.showErrors">{{ form.fields.email.firstError?.message }}</p>
<Spinner v-else-if="form.fields.email.showPending" />
<CheckIcon v-else-if="form.fields.email.showSuccess" />
```

Prefer one branch over the set? Switch on `form.fields.email.displayState` directly. Either way, the same verdict drives the same paint.

## The default heuristic

The default opens one timing gate, then resolves the verdict by precedence.

### 1. Timing gate

The gate opens when either:

- The form has attempted at least one submit (`formMeta.submissionAttempts > 0`), OR
- The field has been edited and then left (`blurredAfterInteraction`, sticky-true after the first blur that follows a value edit).

Until the gate opens, `displayState` is `'idle'` no matter what is in the store. This is "reward early, punish late." A clean tab-through stays quiet: `blurredAfterInteraction` only flips on a blur that follows an edit, so a field the user tabbed through but never edited does not complain until a submit forces the issue. The first pass stays quiet too: editing alone does not open the gate, so the error reveals once the user finishes the pass and leaves the field, never mid-entry, even when the field happened to be tabbed through earlier. And because the bit is sticky and carries no not-focused condition, the gate stays open through a re-focus: once a field has been revealed, fixing its error clears the message live, instead of making the user blur again to see it.

### 2. Precedence

Once the gate is open, the default resolves in order:

1. **Pending (timed).** While a per-field validation runs, the field is heading for a spinner, but Attaform holds the prior verdict for a short window first. A fast check that settles inside that window never shows `'pending'` at all; a slow one flips to the spinner and is then held a minimum so it cannot blink off. This anti-flash timing is tunable, see [Tune the timing](#tune-the-timing).
2. **Error.** An error at the field resolves to `'error'` (containers roll up their descendants, see below).
3. **Success.** No error, `field.valid`, and the green check is earned: the field is non-blank and `dirty`, so the user put valid content there themselves. An empty field that happens to pass, a pre-filled field merely tabbed through, and the post-submit flood of every valid field all stay `'idle'` rather than greening for free. `valid` already waits on the form-wide first validation pass for async schemas, so success never fires before the first real verdict lands.
4. **Idle.** Anything else, including a valid-but-unearned field (blank or unchanged), stays `'idle'`.

### Rollup at containers and the form

A container resolves over the gated verdicts of everything beneath it, so one verdict reflects the whole subtree.

- **Leaves** resolve on their own error.
- **Containers** (an object, an array row, the array itself, and the root `form.meta`) resolve to `'error'` when any descendant is showing an error, or when a cross-field error is pinned at the container itself. Each descendant counts only once its own gate has opened, so a sibling that has been blurred never drags an untouched field's error up to the group.

Precedence rolls up too: a container shows `'pending'` while any descendant is still checking, `'error'` if a gated descendant (or the container's own cross-field check) failed, `'success'` once every field is valid and at least one is earned, and `'idle'` otherwise. An untouched optional sibling sits `'idle'` without holding the group's success back.

That makes `form.meta.showErrors` the natural binding for a form-level "fix the errors below" banner: it turns on the moment a field's error becomes visible and off when the last one clears.

### `form.meta` during a submit

`form.meta.showPending` reflects validation, including the validation a submit runs before your handler. A submit re-validates the whole form, so `form.meta.showPending` stays lit through that pass and a form-level "Checking…" affordance reads true during it. It does not light during the handler itself, because `show*` tracks validation, never submission.

To gate a submit button across the whole submit (its validation and your handler), bind `form.meta.submitting`, the flag that means a submit is in flight:

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

So `form.meta.showPending` is the broad "the form is validating" light and `form.meta.submitting` is the precise "a submit is running" flag: use the first for an ambient indicator, the second to gate the button.

This detour is `form.meta`-only: the submit-driven `pending` is applied at the root, so an individual field never flips to a spinner just because a submit is validating, and each field keeps showing its own verdict throughout. And `showSuccess`, like every verdict, is a validation signal, not a "submission finished" one: for a "Saved" confirmation, gate on `form.meta.submitted` (which flips once the handler resolves), not on `showSuccess`.


## Override per form

```ts
useForm({
  schema,
  getDisplayState: (prev, ctx) =>
    ctx.field.errors.length > 0 && ctx.field.touched ? { display: 'error' } : { display: 'idle' },
})
```

Pass a custom reducer to bend the rule, for example to reveal errors the moment a field is touched (ignoring focus and submit state). A reducer receives `(prev, ctx)`: `prev` is the field's previous `DisplayMachine`, and `ctx` carries the field's `FieldState` and the form's `FormMeta` (both with the derived `displayState` / `show*` / `firstError` keys omitted, so an accidental self-reference is impossible) plus `ctx.validatingSince` and `ctx.now` for timing. It returns the next machine: `{ display }` at minimum, optionally with a `reviewAt` timestamp telling Attaform when to look again.

## Compose with the default

Adopter reducers can layer on top of `defaultDisplayState`. Defer to it for the common case and special-case only the paths you care about:

```ts
import { defaultDisplayState } from 'attaform'

useForm({
  schema,
  // Defer everywhere, but never show a success check on `username`.
  getDisplayState: (prev, ctx) => {
    const next = defaultDisplayState(prev, ctx)
    return next.display === 'success' && ctx.field.path[0] === 'username'
      ? { display: 'idle' }
      : next
  },
})
```

## Tune the timing

The spinner is anti-flash by default. A validation that settles quickly never shows `'pending'` at all, and once a spinner appears it stays up for a minimum so it cannot blink off the instant the check lands. Two timings shape this, both in milliseconds:

- `showDelay` (default `100`): how long a validation may run before its spinner is allowed to show. Anything that settles inside this window stays on its prior verdict, so a synchronous or microtask-fast check never flashes a spinner on every keystroke.
- `minVisible` (default `120`): once shown, the minimum the spinner stays up, so a check that lands just past `showDelay` does not flash it on and immediately off.

The shipped values live in `DEFAULT_TIMINGS`. To retune, build a default with `makeDefaultDisplayState`:

```ts
import { makeDefaultDisplayState } from 'attaform'

useForm({
  schema,
  // Tighter: a spinner after 50ms, held for 200ms once shown.
  getDisplayState: makeDefaultDisplayState({ showDelay: 50, minVisible: 200 }),
})
```

This shapes only the display projection. `errors`, `valid`, `validating`, and the underlying validation all run exactly as before; only when the spinner appears and how long it lingers change. For total control, a from-scratch reducer owns its own timing by returning a `reviewAt` (an absolute `Date.now()` stamp) to tell Attaform when to re-evaluate the field.

## Where to next

- [`errors`](/docs/reading-the-form/errors): the error reads themselves.
- [When validation runs](/docs/validation/when-validation-runs): the timing knob for the underlying validation pass.

_Source: https://attaform.dev/docs/validation/showing-errors_

---

# The `blank` field-state bit

> A storage / display side-channel for cleared numeric inputs. Storage holds `0`, the user sees empty, and the form doesn't silently submit `0` for an unfilled required field.


The demo shows four fields with different schemas. Watch the `blank` column and the `errors` column as you type. The numeric field starts blank-marked even though `values.age === 0`; the required string field uses the schema's refinement instead; the loose string field never raises an error; and the `unset`-defaulted country starts blank-marked deliberately, clearing as soon as you type.


## Why it exists

The whole library obeys one principle: **`errors = f(schema, state)`**. Storage plus the schema tell you whether the form is valid, except for one case.

Numeric inputs lie. A `<input type="number">` whose value the user has just cleared shows `''` in the DOM, but the slim shape requires a number, so storage holds `0`. The schema can't tell the difference between "user typed `0`" and "user supplied nothing": both produce `0` in storage. Without a side-channel, the runtime would either:

- Trust storage and silently submit `0` for an unfilled required field (the public-housing-form footgun: "Income? `$0`. Approved.").
- Re-define `0` as "definitely blank," which loses the case where the user actually meant `0`.

`blankPaths` is the side-channel. It's a reactive `BlankPathsView` (Set-like: `size`, `has(input)`, `values()`, `Symbol.iterator`) recording paths where the runtime knows storage and the visible display diverge. The schema author writes `z.number()` and gets the "empty input" signal back without inventing a sentinel value.

## When `blank` auto-marks

The runtime auto-marks **numeric leaves only**. The asymmetry is real:

| Type      | Storage slim default | DOM "empty" | Need the side-channel?                |
| --------- | -------------------- | ----------- | ------------------------------------- |
| `number`  | `0`                  | `''`        | **Yes**: storage and display diverge. |
| `bigint`  | `0n`                 | `''`        | **Yes**: same reason.                 |
| `string`  | `''`                 | `''`        | No, they match byte-for-byte.         |
| `boolean` | `false`              | unchecked   | No, they match.                       |

For strings and booleans the schema sees what the user sees. Require non-empty strings via `z.string().min(1)`: the refinement error fires the moment storage is `''`, schema speaking.

## Lifecycle (numeric)

```text
form mounts (no defaults)
  → blankPaths.add('income')
  → form.errors.income = [{ code: 'atta:no-value-supplied', … }]
  → form.fields.income.blank === true

user types "5"
  → blankPaths.delete('income')
  → form.errors.income = undefined
  → form.fields.income.blank === false

user clears the input (backspace)
  → directive sees el.value === ''
  → blankPaths.add('income')
  → form.errors.income re-appears reactively
  → form.fields.income.blank === true

user types "0"
  → blankPaths stays empty (the value is intentional)
  → form.errors.income stays undefined
```

`errors = f(schema, state)` holds at every step: `state` includes `(form.value, blankPaths)`, and the function recomputes whenever either changes.

## Lifecycle (string)

```text
form mounts (no defaults)
  → blankPaths empty (strings don't auto-mark)
  → form.errors.email = undefined          (z.string() accepts '')
  → form.fields.email.blank === false

user types "hi" then deletes
  → blankPaths still empty
  → form.errors.email still undefined      (z.string() still accepts '')
  → form.fields.email.blank === false
```

If the schema is `z.string().min(1)` instead, the lifecycle is the same on `blankPaths`, but `form.errors.email` carries a refinement error whenever storage is `''`, because that's the schema speaking. The blank channel stays out of it.

## Explicit opt-in at any path: the `unset` sentinel

Sometimes you do want a string or boolean leaf to start blank: a "please choose" indicator on a checkbox, a deferred-fill text field. That's an explicit consumer signal, not runtime inference. Use the `unset` sentinel:

```ts
import { unset, useForm } from 'attaform'

useForm({
  schema: z.object({ agreed: z.boolean(), note: z.string() }),
  defaultValues: { agreed: unset, note: unset },
})

// Or imperatively:
form.setValue('agreed', unset)
form.reset({ note: unset })
```

`unset` works at every position the consumer can address: primitive leaves, containers, arrays, tuples, records, discriminated unions, optional / nullable wrappers, and the root. Container `unset` recurses through the schema's slim subtree and adds every primitive descendant to `blankPaths` in one call:

```ts
form.setValue('profile', unset) // marks profile.name, profile.age, etc.
form.reset({ cargo: unset }) // DU stub, marks the discriminator path
form.reset(unset) // root: marks every primitive leaf in the schema
```

Combined with required schemas, the sentinel surfaces a `atta:no-value-supplied` error reactively at each marked path: same lifecycle as the numeric auto-mark case, just driven by consumer intent rather than runtime inference. See [the `unset` page](/docs/writing-and-mutating/unset) for the position-by-position contract.

## How to read `blank` in your UI

Attaform never renders. The signal is exposed; your component decides what to do.

```vue
<script setup lang="ts">
  const form = useForm({ schema })
</script>

<template>
  <input v-register="form.register('income')" />

  <!-- show errors only after the user has touched the field -->
  <p v-if="form.errors.income && form.fields.income.touched" class="error">
    {{ form.errors.income[0].message }}
  </p>

  <!-- separately, an "unanswered" hint that distinguishes from errors -->
  <span v-if="form.fields.income.blank" class="hint">Required, please enter a number</span>
</template>
```

Reading `form.errors.income` directly gives you whatever the schema and the blank channel produced. Reading `form.fields.income.blank` gives you the raw "did the user supply something?" bit, useful for pre-error indicators or progress meters.

## Submit-time integration

`handleSubmit` checks `blankPaths` against the schema before running the success callback:

- If `blankPaths` is non-empty AND the schema requires those paths, submission fails. The success callback never runs, `meta.submissionAttempts` ticks, and `meta.submitError` carries the aggregate.
- If `blankPaths` is non-empty but the schema accepts the empty case (`.optional()`, `.nullable()`, `.default(x)`), submission proceeds.

The `atta:no-value-supplied` error surfaces in `form.errors.<path>` and in `form.meta.errors`: same shape as a schema-emitted error, distinct `code` for filtering.

## `blank` and history

Every history position captures the `blankPaths` set at the time of the snapshot. Undoing a "type a number, then clear it" sequence restores both the value AND the blank bit. The field reads as empty the way it did before the undo.

## Where to next

- [Defaults from the schema](/docs/schemas/defaults): auto-mark interacts with `defaultValues`; explicit values turn it off.
- [`unset`](/docs/writing-and-mutating/unset): flag any path blank in `defaultValues`, `setValue`, or `reset`.
- [Display state and showing errors](/docs/validation/showing-errors): `firstError` includes the `no-value-supplied` entry; `getDisplayState` decides when to render it.

_Source: https://attaform.dev/docs/validation/blank_

---

# `handleSubmit`

> A submit handler that waits for validation, hands you parsed values, and routes rejections through `onError`.


Submit the form without checking the terms box to watch the `onError` path fire: focus pulls to the broken field and the rejection alert lands. Check the box, fill the email, submit again to see `onSubmit` receive the parsed values. The [dispatch contract](#the-dispatch-contract) section traces every step between the click and the callback.


## Signature

```ts
const submit = form.handleSubmit(
  async (values) => {
    /* onSubmit */
  },
  (errors) => {
    /* onError, optional */
  }
)
```

The return value is a function ready for `<form @submit>`. Call signature: `(event?: Event) => Promise<void>`. It calls `event.preventDefault()` for you when it receives the submit event, so bind it with `@submit`, not `@submit.prevent`: the `.prevent` modifier would only prevent the default a second time.

## The dispatch contract

When the returned handler fires:

1. The form's submit count increments. `form.meta.submissionAttempts` lifts; the default `getDisplayState` heuristic starts surfacing errors for every field.
2. Sync validation runs across every active path.
3. Async refinements are awaited.
4. If every refinement passes, `onSubmit(values)` is called with the **parsed** Zod output: `.transform`-aware, fully typed.
5. The submit counts as a success, flipping `form.meta.submitted` to `true`, only when `onSubmit` resolves without throwing and leaves no errors set. A callback that hands a server rejection to `setErrors` and returns is a failed submit (see [server-side errors](/docs/submitting/server-side-errors)).
6. Every failure pulls focus to the first invalid field. They differ in one respect: a **validation** failure (step 4 rejected, so `onSubmit` never ran) also calls `onError(errors)` when supplied. A failure your callback produces after it runs, a throw or a `setErrors` and return, does not. `onError` is the verdict on Attaform's own validation, and by then that had already passed. A thrown callback additionally lands on `form.meta.submitError` and surfaces on `form.errors`.

While step 4 is awaiting your `onSubmit` callback, `form.meta.submitting` is `true`. It flips back when the callback resolves or rejects. A rejection is caught, not re-thrown, so it never escapes as an unhandled rejection: the raw error lands on `form.meta.submitError`, and a normalized copy joins `form.errors` (form-level, or path-scoped when you throw a `{ path, message }`), so a banner reading [`form.meta.firstOwnError`](/docs/reading-the-form/meta) catches it.

## Without onError

```ts
const submit = form.handleSubmit(async (values) => {
  await api.signup(values)
})
```

Skip `onError` when the default behavior (focus the first invalid field) is enough. Validation errors still surface through `form.errors.<path>`; the optional callback is for cross-field UI behavior like a toast or a console log.

## Submission state

```vue
<button :disabled="form.meta.submitting" type="submit">
  {{ form.meta.submitting ? 'Saving…' : 'Save' }}
</button>
```

`form.meta.submitting` is the reactive flag while the `onSubmit` callback runs.

## Where to next

- [`errors`](/docs/reading-the-form/errors): the per-path error reads.
- [When validation runs](/docs/validation/when-validation-runs): the timing knob.
- [Display state and showing errors](/docs/validation/showing-errors): the `getDisplayState` predicate.

_Source: https://attaform.dev/docs/submitting/handle-submit_

---

# Server-side errors

> A server rejection is just another invalid path. Hand Attaform the errors and they land in the same reactive surface as schema errors: same `firstError` reads, same focus and scroll on submit, same display gating.


The demo signs in against a simulated backend. Submit with the wrong password to land an error right under the field; sign in as `locked@example.com` to get a form-level lockout whose structured `data` payload carries the unlock time. Every response routes through a single `form.setErrors` call.


## One shape in, one shape out

Attaform reads and writes errors in one shape, `ValidationError`, the same record the validator produces. So when your server speaks that shape, there is nothing to translate: hand the array straight to `form.setErrors`.

```ts
const onSubmit = form.handleSubmit(async (values) => {
  form.clearErrors()
  const response = await api.signIn(values)

  if (!response.ok) {
    form.setErrors(response.errors)
    return
  }
  // success path
})
```

`response.errors` is a `ValidationError[]`: each entry carries a `message`, an optional `path`, an optional `code`, and an optional `data` payload. An entry with a `path` lands at that field; an entry with no path lands at the form level, in the global `[]` bucket. `form.setErrors` stamps the form key on every entry as it lands, so errors stay isolated to this form.

Returning after `setErrors` is a failed submit: `form.meta.submitted` stays `false` and focus pulls to the first error. It does not fire `onError`, though, that callback is the verdict on Attaform's own validation, which already passed here. You do not need to throw to signal the rejection, and you do not need to call `form.focusFirstError()` by hand. Reserve a thrown error for the unexpected (a network drop, a 500), which also lands on `form.meta.submitError` for inspection.

## `setErrors` and `clearErrors`

`form.setErrors` owns the manual error layer, the errors you set by hand. Schema errors live in their own layer and merge in on read, so setting manual errors never disturbs validation. Its call forms mirror [`form.setValue`](/docs/writing-and-mutating/set-value):

| Call                      | Effect                                                                             |
| ------------------------- | ---------------------------------------------------------------------------------- |
| `setErrors(errors)`       | Replace the whole manual layer with this list. Each entry lands at its own `path`. |
| `setErrors(prev => next)` | Functional replace. `prev` is the current manual layer as a `ValidationError[]`.   |
| `setErrors(path, errors)` | Scope to one path. Replaces that path's manual errors and stamps the path for you. |
| `clearErrors(path?)`      | Clear one path, or everything with no argument, schema and manual errors alike.    |

```ts
form.setErrors(response.errors) // whole layer, each entry at its path
form.setErrors([{ message: 'Service unavailable, try again shortly.' }]) // a form-level banner
form.setErrors('email', [{ message: 'Already registered' }]) // scoped to one field
form.setErrors((prev) => [...prev, { path: ['email'], message: 'Also flagged by fraud check' }])
form.clearErrors('email') // one field
form.clearErrors() // everything
```

A whole-layer `setErrors` is a full replace: any path absent from the new list is cleared. Reach for the scoped form or the functional updater when you want to touch one path and leave the rest alone.

## The error shape

What you read back is firm: every `ValidationError` has a `message`, a `path`, a `code`, and a `formKey`. What you pass in is loose, so a server response rarely needs massaging:

```ts
type ErrorInput =
  | Error
  | {
      message?: string
      path?: (string | number)[]
      code?: string
      data?: Json | null
      formKey?: FormKey
    }
```

- **`message`** is optional. An `Error` contributes its `message`; a missing or empty message becomes `"Unknown error"` rather than throwing.
- **`path`** defaults to `[]` (form level). The scoped `setErrors(path, ...)` form stamps the path for you and ignores any path on the entry.
- **`code`** defaults to `atta:user-error`. Set your own (`auth:locked`, `api:duplicate`) to branch on it in the UI.
- **`data`** is an opaque `Json` payload Attaform never inspects. It rides along untouched, so a lockout can carry its unlock time, a challenge its captcha token, a step-up its MFA descriptor.
- **`formKey`** is accepted but ignored: the form always stamps its own. So a `ValidationError` you read back (from `form.errors()`, or a server that already speaks the shape) is itself valid input, with no mapping required.

Reading `data` where you render the error is how the lockout banner in the demo knows when to unlock:

```ts
const lockout = computed(() => {
  const locked = form.meta.ownErrors.find((e) => e.code === 'auth:locked')
  const data = locked?.data as { unlocksAt?: string } | null | undefined
  return data?.unlocksAt ? new Date(data.unlocksAt) : null
})
```

## Servers that speak a different shape

When a backend returns its own envelope, map it to `ValidationError` in one pass at the call site. There is no parser to configure and no shape for Attaform to guess at: you own the one line that knows your server, and everything past it is the canonical contract.

```ts
const response = await api.signUp(values)

if (!response.ok) {
  form.setErrors(response.failures.map((f) => ({ path: f.field.split('.'), message: f.detail })))
  return
}
```

## The same reactive surface

Once set, server errors are indistinguishable from schema errors at every read:

- `form.errors.email` returns the `ValidationError[]` at that path, server or schema, same shape.
- `form.fields.email.firstError` returns the first one, and `form.fields.email.showErrors` gates its display through the [display-state](/docs/validation/showing-errors) predicate.
- `form.meta.ownErrors` returns the form-level errors on their own, and `form.meta.firstOwnError` is the first, ideal for a top-of-form banner.
- `form.focusFirstError()` pulls focus to the first server error exactly as it would a schema one.

No "this one came from the server" branch in your template. The render code reads `form.fields.<path>.firstError?.message` the same way for both.

## Clearing on a fresh round-trip

A server error stays put until you clear it: editing the field does not drop it on its own, which matches the network round-trip (the value is not re-checked until the next submit). Clearing the whole layer at the top of `handleSubmit` is the common rhythm, so each submit starts clean.

For clear-on-edit UX, watch the path and clear it:

```ts
watch(
  () => form.values.email,
  () => form.clearErrors('email')
)
```

## Where to next

- [`handleSubmit`](/docs/submitting/handle-submit): the dispatch surface server errors plug into.
- [Focus & scroll on invalid submit](/docs/submitting/focus-scroll): the same machinery, applied to server errors after they land.
- [`errors`](/docs/reading-the-form/errors): the reactive read surface for every error, server or schema.
- [Types reference](/docs/reference/types): `ValidationError`, `ErrorInput`, and `Json` in full.

_Source: https://attaform.dev/docs/submitting/server-side-errors_

---

# Focus & scroll on invalid submit

> The default does the right thing on submit. The imperative helpers exist for when you need to drive focus or scroll outside the submit path.


Submit the form with empty fields to watch focus pull to the first invalid one automatically. That's `handleSubmit` running its default invalid-submit policy (`'focus-first-error'`). The two buttons below dispatch the helpers imperatively, so you can drive focus or smooth-scroll outside the submit handler. Submitting again with valid fields shows the no-op success path.


## Default on invalid submit

`handleSubmit` pulls focus to the first invalid field on failed submission:

```ts
const onSubmit = form.handleSubmit(async (values) => {
  await api.send(values)
})
```

When validation fails, the handler:

1. Increments `form.meta.submissionAttempts`. `form.meta.submitted` stays `false`; it only flips on a successful callback.
2. Surfaces errors at every invalid path.
3. Calls `form.focusFirstError()` (the same method exposed below).
4. Calls `onError(errors)` if you passed one.

The "first" invalid field is in schema-declaration order, which matches the visual reading order for most forms (top to bottom, left to right).

## `focusFirstError(options?)`

```ts
form.focusFirstError({ preventScroll: false })
```

Returns `true` when a target was found and focused, `false` when no field is in an error state. The optional `preventScroll: true` skips the browser's default focus-related scroll if you've got a custom scroll strategy.

Reach for this when:

- A page-level error banner has a "Jump to first error" button.
- A multi-step form's "Next" button should pull focus on validation failure without going through `handleSubmit`.
- Replacing the default invalid-submit policy with custom UX (see [Customizing the invalid-submit policy](#customizing-the-invalid-submit-policy)).

## `scrollToFirstError(options?)`

```ts
form.scrollToFirstError({ behavior: 'smooth', block: 'center' })
```

Returns `true` when a target was found and scrolled into view. Options forward to the underlying `Element.scrollIntoView`: `behavior: 'smooth'` for animated scroll, `block: 'center'` to position the field in the middle of the viewport.

The default invalid-submit policy focuses but doesn't scroll on most browsers (focus triggers a minimal scroll). For tall forms where the first error might be far above the user's current scroll position, layer this on:

```ts
const onSubmit = form.handleSubmit(
  async (values) => {
    /* ... */
  },
  () => {
    form.scrollToFirstError({ behavior: 'smooth', block: 'center' })
  }
)
```

## Customizing the invalid-submit policy

Disable the default focus pull at the form level and run your own:

```ts
useForm({
  schema,
  onInvalidSubmit: 'none', // skip the default focus
})
```

Then drive focus + scroll from `onError`:

```ts
const onSubmit = form.handleSubmit(onSubmitValid, () => {
  form.scrollToFirstError({ behavior: 'smooth', block: 'center' })
  form.focusFirstError({ preventScroll: true })
})
```

The `'focus-first-error'` (default), `'scroll-to-first-error'`, `'both'`, and `'none'` policy options live on the form config and on `createAttaform({ defaults })` for an app-wide default. See the [Types reference](/docs/reference/types) for the full set.

## Where to next

- [`handleSubmit`](/docs/submitting/handle-submit): the dispatch surface that calls these by default.
- [Server-side errors](/docs/submitting/server-side-errors): bring API failures back into the same focus / scroll machinery.
- [Display state and showing errors](/docs/validation/showing-errors): the predicate that decides when errors render.

_Source: https://attaform.dev/docs/submitting/focus-scroll_

---

# Undo & redo

> Opt into a per-form history chain with one option. Every value mutation records a position; the namespace exposes `undo()` / `redo()` / `clear()` and the reactive flags that gate your UI.


Type into any field, append a few tags, then hit `⌘Z` / `⌘⇧Z` (or click the buttons) to walk the chain. `canUndo` and `canRedo` gate the buttons reactively; `clear()` reseeds the chain at the current state, the move you'd make after a "Save successful" milestone.


## The option

```ts
useForm({
  schema,
  history: true, // default 128-position bounded chain
})
```

Tune the depth:

```ts
useForm({ schema, history: { max: 200 } })
```

Disable explicitly:

```ts
useForm({ schema, history: false })
```

When omitted, `history` defaults to `false`. The namespace is still present on the form return so templates don't need conditional logic, but every method is a no-op and the flags read `false` / `0`.

## The namespace

All undo/redo surface lives under `form.history`:

| Member    | Type            | What it does                                                        |
| --------- | --------------- | ------------------------------------------------------------------- |
| `undo()`  | `() => boolean` | Step back to the previous state. `false` at baseline.               |
| `redo()`  | `() => boolean` | Replay the next state after an undo. `false` when nothing's queued. |
| `clear()` | `() => void`    | Wipe the chain; reseed at the current state as the new baseline.    |
| `canUndo` | `boolean`       | Gate an "Undo" button reactively.                                   |
| `canRedo` | `boolean`       | Gate a "Redo" button reactively.                                    |
| `size`    | `number`        | Reachable positions across the chain (useful for debug overlays).   |

## What gets captured

Every form value mutation: `setValue`, `register`-backed input edits, any array helper (`append`, `prepend`, `insert`, `remove`, `swap`, `move`, `replace`), or a programmatic write. Each recorded position carries:

- The form value.
- The error map at the time of the captured position.
- The `blankPaths` set (so cleared-but-defaulted numeric fields keep showing as empty after an undo, instead of resurrecting their slim default).

What's NOT captured:

- **Field interaction state**: `touched` / `focused` / `blurred` / `connected`. UI interaction history; it shouldn't rewind. A field that was touched stays touched.
- **Submission lifecycle**: `meta.submissionAttempts`, `meta.submitError`.
- **Validation in-flight state**.

Calling `setErrors` / `clearErrors` does NOT record a position; those only touch the error map. Whatever errors are live when the next mutation lands go into that mutation's delta.

## Keyboard shortcuts

Not wired by default; wire them in a few lines:

```vue
<script setup lang="ts">
  function onKeydown(event: KeyboardEvent) {
    if ((event.metaKey || event.ctrlKey) && event.key === 'z') {
      event.preventDefault()
      event.shiftKey ? form.history.redo() : form.history.undo()
    }
  }
</script>

<template>
  <form @keydown="onKeydown">
    <!-- … -->
  </form>
</template>
```

Attaform stays out of the global keydown business so you can layer shortcuts at the right scope (per-form, per-route, global), with the modifier convention that fits your platform.

## `clear()` at a milestone

After a "save successful" moment, or any point where consumers should lose access to the prior chain without disturbing the rendered form, call `clear()`. The form value, errors, and blank-paths stay exactly where they are; only the past and future history reset.

```ts
async function onSaveSuccess() {
  await api.commit(form.values())
  form.history.clear()
}
```

After `clear()`: `canUndo === false`, `canRedo === false`, `size === 1`. The current position is still reachable; there's just nothing on either side of it.

## Interactions

- **`reset()`** is itself a mutation; the pre-reset state stays one undo away. Consumers who want a hard wipe call `form.history.clear()` after `reset()`, or pop a confirmation dialog before calling `reset()`.
- **Live field validation** still runs on undo / redo; the restored state validates like any other.

## Memory

The default `max: 128` keeps at most 128 reachable positions across the undo + redo halves combined. Bump it for editors with long histories; drop it for memory-constrained targets. Internally history stores one base snapshot plus a chain of forward deltas (per-mutation `Patch[]` from the diff machinery), so each additional position costs `O(changed-leaf-count)`. Typing one character into one field allocates a single patch, not a clone of the whole form.

## Where to next

- [`reset` & `resetField`](/docs/writing-and-mutating/reset): recorded as positions; the pre-reset state stays one undo away.

_Source: https://attaform.dev/docs/cross-cutting-state/undo-redo_

---

# Autosave

> A copy-paste `useAutosave` composable built on a Vue `watch`: per-field status, an aggregate `isSaving`, a validity gate, and debounced writes. Attaform owns the reactive form, you own the save policy.


Email saves as a draft: even an invalid address persists as you type, while Attaform still flags it inline below the field. Display name and bio gate on validity instead, holding back until they pass (display name needs two characters). Type a burst and one save lands per pause, the toast confirming it. Tick the box to fail saves and watch the aggregate banner flip. Load the saved profile or reset to watch a write land with no autosave at all.


## The recipe

`useAutosave` watches each path through `form.toRef`: it debounces every field, gates the save on the field being valid, tracks per-path status, and rolls that up into an aggregate. Drop it into your app as a composable and own it from there.

```ts
// composables/useAutosave.ts
import { computed, nextTick, reactive, watch } from 'vue'
import type { FlatPath, GenericForm, UseFormReturnType } from 'attaform'

export type SaveStatus = 'idle' | 'pending' | 'saving' | 'saved' | 'error'

export function useAutosave<Form extends GenericForm>(
  form: UseFormReturnType<Form>,
  paths: readonly FlatPath<Form>[],
  save: (path: FlatPath<Form>, value: unknown, signal: AbortSignal) => Promise<void>,
  options: {
    debounceMs?: number
    gateOnValidity?: boolean | ((path: FlatPath<Form>) => boolean)
  } = {}
) {
  const { debounceMs = 600, gateOnValidity = true } = options
  const status = reactive<Record<string, SaveStatus>>({})
  for (const path of paths) status[path] = 'idle'

  let paused = false

  async function run(path: FlatPath<Form>, value: unknown, signal: AbortSignal) {
    try {
      const gate = typeof gateOnValidity === 'function' ? gateOnValidity(path) : gateOnValidity
      if (gate && !(await form.validateAsync(path)).success) {
        status[path] = 'idle'
        return
      }
      if (signal.aborted) return
      status[path] = 'saving'
      await save(path, value, signal)
      if (!signal.aborted) status[path] = 'saved'
    } catch {
      if (!signal.aborted) status[path] = 'error'
    }
  }

  for (const path of paths) {
    let timer: ReturnType<typeof setTimeout> | undefined
    let controller: AbortController | undefined
    watch(form.toRef(path), (value) => {
      if (paused) return
      status[path] = 'pending'
      controller?.abort()
      controller = new AbortController()
      const { signal } = controller
      if (timer) clearTimeout(timer)
      timer = setTimeout(() => void run(path, value, signal), debounceMs)
    })
  }

  function runWithoutAutosave(write: () => void) {
    paused = true
    try {
      write()
    } finally {
      void nextTick(() => {
        paused = false
      })
    }
  }

  return {
    status,
    isSaving: computed(() => Object.values(status).some((s) => s === 'saving')),
    failed: computed(() => paths.filter((path) => status[path] === 'error')),
    runWithoutAutosave,
  }
}
```

The path and form type helpers (`FlatPath`, `GenericForm`, `UseFormReturnType`) come from the core `attaform` entry. The composable is adapter-agnostic: it works against a Zod v3, Zod v4, or any other adapter's form, since it only reaches for `form.toRef` and `validateAsync`.

## What it gives you back

| Return               | Type                       | Use                                                                       |
| -------------------- | -------------------------- | ------------------------------------------------------------------------- |
| `status`             | `Record<path, SaveStatus>` | Per-field badge: `idle` / `pending` / `saving` / `saved` / `error`.       |
| `isSaving`           | `ComputedRef<boolean>`     | Aggregate "a save is in flight" for a header spinner or banner.           |
| `failed`             | `ComputedRef<path[]>`      | The paths whose last save errored, for a retry affordance.                |
| `runWithoutAutosave` | `(write) => void`          | Run a programmatic write (hydrate, reset) without tripping a save. Below. |

None of it lives in form state. `status` is a plain reactive map the composable owns: the form's `dirty` / `validating` surface stays about the form, autosave status stays about autosave.

## Wiring it up

Hoist the schema, build the form, then point `useAutosave` at the paths you want saved. The `save` callback is yours: it receives the path, its value, and an `AbortSignal` to hand straight to `fetch`.

```ts
const schema = z.object({
  email: z.string().email(),
  displayName: z.string().min(2),
  bio: z.string().max(160),
})

const form = useForm({ schema })

const { status, isSaving, failed, runWithoutAutosave } = useAutosave(
  form,
  ['email', 'displayName', 'bio'],
  async (path, value, signal) => {
    await api.patch(`/profile/${path}`, { value }, { signal })
  },
  { debounceMs: 600 }
)
```

`useAutosave` registers its watchers inside `setup`, so they stop automatically when the component unmounts. No manual teardown.

## How the watch reacts

Each path gets its own `watch(form.toRef(path), ...)`. `form.toRef('email')` is a read-only Vue ref over that path's value, resolved from a dotted string, so the watcher fires whenever the value at that path changes. Writing the same value back is a no-op in Attaform, so a watcher never fires for a write that changed nothing.

`toRef` resolves a nested path directly, so `form.toRef('profile.bio')` watches a leaf several levels deep with no extra wiring. For a whole container path, add `{ deep: true }` to that watcher to react to any field beneath it, since an in-place leaf edit keeps the container's reference stable (Vue's deep-watch behaviour).

## Gating on validity

This is where validation and persistence meet. `gateOnValidity` (on by default) runs `form.validateAsync(path)` before each save and skips the write when the field is invalid, so a value that fails validation never reaches the server, and the field's [async refinements](/docs/validation/async-refinements) run as part of that same check.

`.refine` decides whether a value is allowed; the autosave decides whether to persist it. Composing them gives you "save only what passes" without either concern leaking into the other. Turn the gate off (`{ gateOnValidity: false }`) when you want a true draft autosave that captures even invalid in-progress state.

For per-field control, pass a predicate instead of a boolean: `gateOnValidity: (path) => path !== 'email'` keeps `email` a draft while gating the rest. The demo above does exactly that, so an invalid email still autosaves while `fields.email.showErrors` surfaces the validation message. The write persists the draft, the read flags it, and neither blocks the other.

## Debouncing and superseding

A network round-trip per keystroke is wasteful, so each path gets its own debounced scheduler. The recipe inlines a small `setTimeout` debounce to stay dependency-free; if your app already uses VueUse, swap in `useDebounceFn` with no other change.

Each watcher also owns an `AbortController`. When a newer edit lands before the previous save finished, the recipe aborts the prior controller and starts a fresh one, so a stale request to a slow endpoint cancels itself and the latest write wins. The `save` callback receives that `signal`, so passing it to `fetch` cancels the request in flight; checking `signal.aborted` after an `await` skips a status update for work that has been superseded. Because the scheduler returns immediately, the actual save runs after the watcher has finished, so `run` catches its own throw and sets `status[path] = 'error'` rather than letting it escape.

## Pausing autosave for hydration and reset

A `watch` reacts to every change to its source, including the writes you make yourself: loading a saved record with `form.setValue`, or a `form.reset()`. Left unguarded, hydrating ten fields would echo ten autosaves straight back at the server you just loaded from. `runWithoutAutosave` wraps such a write so the watchers skip it: it raises an internal flag, runs your write, then clears the flag on the next tick once the watchers have seen (and ignored) the change.

```ts
function loadProfile(saved: Profile) {
  runWithoutAutosave(() => form.setValue(saved))
}

function discard() {
  runWithoutAutosave(() => form.reset())
}
```

The pause belongs to the recipe, not the form. The form has no idea autosave exists, the same separation that keeps `status` out of `form.meta`. You own the autosave, so you own when it pauses.

## Why a recipe, not a shipped export

Attaform ships [zero runtime dependencies](/docs/getting-started/why-attaform), and a genuinely good autosave wants opinions the core should not make for you: the debounce window, retry and backoff policy, whether a save is optimistic or confirmed, and what "saved" even means for your backend. Those are application decisions. The reactive form is the small, sharp primitive Attaform owns; `useAutosave` is the policy you own, sized and tuned to your app. Copy it, change it, delete the parts you do not need.

## Where to next

- [Async refinements](/docs/validation/async-refinements): the server-side validity checks the gate runs.
- [`setValue` patterns](/docs/writing-and-mutating/set-value): the write surface the recipe drives, including the hydrating record load.
- [Undo and redo](/docs/cross-cutting-state/undo-redo): the other cross-cutting reaction to form changes, kept inside the form.

_Source: https://attaform.dev/docs/cross-cutting-state/autosave_

---

# `injectForm`

> Reach any registered form from any descendant. Call `injectForm` and get the same handle back. Ambient resolution for the parent's own form, keyed resolution for distant ones.


The parent owns the form and renders the email field. `ProfileFieldset.vue` and `StatusPill.vue` are sibling SFCs that each call `injectForm('docs-demo-inject-form')` to reach the same form: no props passed, same reactive surface. Both children would run unchanged regardless of how deep they sat in the tree.


## The common case: ambient resolution

Parent owns the form (no `key`):

```vue
<!-- SignupForm.vue -->
<script setup lang="ts">
  import { useForm } from 'attaform'

  const form = useForm<Form>({ schema })
  const onSubmit = form.handleSubmit(async (values) => {
    await api.post('/signup', values)
  })
</script>

<template>
  <form @submit="onSubmit">
    <EmailRow />
    <ProfileGroup />
    <button>Sign up</button>
  </form>
</template>
```

Any descendant grabs the same form:

```vue
<!-- EmailRow.vue -->
<script setup lang="ts">
  import { injectForm } from 'attaform'

  const form = injectForm<Form>()
</script>

<template>
  <label>Email</label>
  <input v-register="form?.register('email')" />
  <em v-if="form?.fields.email.showErrors">{{ form?.fields.email.firstError?.message }}</em>
</template>
```

You supply the `Form` generic; Vue's injection system erases it, so Attaform can't recover the shape on your behalf. Other than that, `injectForm<Form>()` returns a form type-identical to `useForm`'s return.

## Reaching a form that isn't an ancestor

Floating save buttons, sidebar status widgets, anything in a different branch of the component tree:

```vue
<!-- FloatingSaveButton.vue (anywhere in the app) -->
<script setup lang="ts">
  import { injectForm } from 'attaform'

  const form = injectForm<Form>('signup')
  const onSave = () => form?.handleSubmit(async (values) => api.post('/signup', values))()
</script>

<template>
  <button :disabled="!form?.meta.dirty || form?.meta.submitting" @click="onSave">Save</button>
</template>
```

Pass the same `key` you passed to `useForm({ key: 'signup' })`. If no form is registered under that key when the component mounts, `injectForm` returns `null` and dev mode logs the unresolved key at the call site. Reach for the form with `?.` at every consumption site so a missing form degrades to no-ops instead of crashing. See [When resolution fails](#when-resolution-fails) below.

## How a key resolves

A key is a name, not a location. What `injectForm('signup')` resolves to is fixed by two properties, and it helps to hold both at once.

**It is position-independent.** A keyed form lives in Attaform's app-level registry, not in the component tree. `injectForm('signup')` reaches it from any component in the app: a sibling branch, a floating toolbar, a modal teleported to the document body. Extracting a wrapper or changing how deep a component sits never changes what a key resolves to.

**It is time-dependent.** The registry entry appears when the form's own `useForm({ key: 'signup' })` runs its setup, and not a moment before. So the one thing a key cannot do is hand back a form that has not been created yet.

Together they give a single rule: **resolve downward.** Vue runs a parent's setup before its children's, so:

- A descendant reaching an ancestor's keyed form always resolves. The ancestor's `useForm` ran first, so the entry is already there.
- An ancestor reaching a descendant's form gets `null`. At the ancestor's setup the descendant has not run, so nothing is registered under that key yet.

Create a form where it is owned, and reach for it at or below that point. If you catch yourself reaching upward, or sideways for a form a sibling creates, that is the cue to lift the `useForm({ key })` up to a common ancestor so the form exists before anyone asks for it.

| Resolution       | Keyed: `injectForm('signup')`                          | Ambient: `injectForm()`                         |
| ---------------- | ------------------------------------------------------ | ----------------------------------------------- |
| Resolves through | Attaform's app-level registry                          | Vue `provide` / `inject`                        |
| Reaches          | any component in the app                               | descendants of the owning `useForm`             |
| Ready            | once the owner's `useForm({ key })` setup has run      | always, from a descendant (the owner ran first) |
| On a miss        | `null`, plus a dev warning listing the registered keys | `null`, silently                                |

The dev warning on a keyed miss names this timing case directly and points at the call site, so a form that simply registered late reads differently from a typo.

## Do I need to pass a `key` to `useForm`?

The two resolution modes are cleanly split:

- **Anonymous (no `key`) → ambient access.** `useForm({ schema })` fills the parent's ambient slot. Any descendant's `injectForm<Form>()` (no key) resolves to it; closest ancestor wins when nested.
- **Keyed (`key: 'x'`) → explicit access only.** `useForm({ schema, key: 'x' })` registers the form under `'x'` but does NOT fill the ambient slot. Descendants reach it via `injectForm<Form>('x')`, not via the no-key form.

Skip `key` for single-component one-off forms (login modal, settings panel). Supply one when you want cross-component lookup, multi-call-site shared state, a stable persistence default, or a legible DevTools label.

### Gotcha: multiple anonymous `useForm` in one component

Vue's `provide` / `inject` is last-write-wins per component. If a parent calls `useForm` twice without keys, the second overwrites the first in the ambient slot, and descendants using `injectForm<Form>()` only see the second.

```ts
// Parent component
const formA = useForm({ schema: schemaA }) // provides ambient → A
const formB = useForm({ schema: schemaB }) // provides ambient → B (overwrites A)
// Descendants' injectForm<Form>() reads B. A is unreachable via ambient.
```

The runtime emits a dev-mode `console.warn` lazily, when (and only when) a descendant actually consumes the ambient slot via `injectForm<Form>()` with no key. The warning lists each anonymous `useForm()` call by source frame so you can navigate to the offending sites.

**Fix:** give each form a key (which removes them from the ambient slot entirely) and look them up explicitly:

```ts
useForm({ schema: schemaA, key: 'a' })
useForm({ schema: schemaB, key: 'b' })
// Descendants:
const a = injectForm<FormA>('a')
const b = injectForm<FormB>('b')
```

Mixing modes is fine; keyed forms don't interfere with an ambient sibling. A parent with three keyed forms plus one anonymous form produces no warning; the descendant's `injectForm<F>()` unambiguously resolves to the (only) anonymous one.

## Compound vs. single-purpose

For components that touch one field, both `injectForm` and `useRegister` work. The choice:

- **`useRegister`**: single-field child that takes `v-register` from its consumer. Use when the parent decides which path the child binds to.
- **`injectForm`**: child that touches one or more specific paths the parent doesn't declare. Use when the path is the child's responsibility (an `AddressBlock` always binds `address.street`, `address.city`, `address.zip`).

`useRegister` doesn't accept a key or path; it's a single-purpose ambient hook. Compound use cases belong on `injectForm`.

## Lifetime

Both resolution modes ref-count on the form's registry entry. In practice:

- The form survives until every component that reached it unmounts.
- Cleanup is automatic; no explicit dispose call from the consumer.
- A form accessed only by `injectForm(key)` stays alive as long as at least one consumer is mounted, even if the original `useForm` owner unmounted first.

## When resolution fails

`injectForm` returns `T | null` rather than throwing, so descendants are robust to mount-order quirks (children rendered before the parent's `useForm` runs, conditional ancestors, dynamic imports). Two cases produce `null`:

- **No ambient form**: `injectForm()` with no ancestor `useForm` and no key. Returns `null` silently. Ambient lookup is opportunistic, so a downstream component library reading the ambient slot stays quiet in trees that don't have a form rather than spamming consumers' consoles.
- **Key not registered**: `injectForm('key-name')` but nothing is registered under that key. Dev mode logs the unresolved key at the call site. If the form is created lower in the tree, it registers after this call runs; see [How a key resolves](#how-a-key-resolves).

Keep the return as `T | null` and reach for it with `?.` at the consumption sites. The directive accepts `undefined` peacefully, optional chains short-circuit cleanly through reactive reads, and the child still works the moment the form becomes available:

```vue
<script setup lang="ts">
  const ctx = injectForm<Form>('signup')
</script>

<template>
  <input v-register="ctx?.register('email')" />
  <em v-if="ctx?.fields.email.showErrors">{{ ctx?.fields.email.firstError?.message }}</em>
</template>
```

For optional consumers (a floating panel that should hide entirely when the form isn't mounted), wrap the whole subtree in `v-if`:

```vue
<template>
  <div v-if="ctx" class="status">{{ ctx.meta.dirty ? '●' : '' }}</div>
</template>
```

Either way, the non-null assertion (`ctx!`) is a pattern to avoid: it teaches the type checker to look the other way, and a single mount-order regression turns into a runtime crash instead of a quiet no-op.

`injectForm` does throw `OutsideSetupError` if called outside a Vue setup function: a structural mistake the runtime can catch unambiguously.

## Where to next

- [`useRegister` for custom components](/docs/binding-inputs/use-register): the single-field child binding alternative.
- [Undo & redo](/docs/cross-cutting-state/undo-redo): `injectForm` makes "Undo" buttons in distant components effortless.
- [Multistep flows (`useWizard`)](/docs/multistep/use-wizard): orchestrates multiple `useForm` instances, not single-form access.

_Source: https://attaform.dev/docs/cross-cutting-state/inject-form_

---

# App-wide defaults

> One plugin call sets the defaults every `useForm` in the app inherits. Set the convention once, override per-form when a particular surface needs something different.


This page is code-only; `createAttaform` runs at app boot, before any form mounts. The demos throughout the rest of the docs implicitly use Attaform's built-in defaults (`validateOn: 'change'`, `debounceMs: 0`, etc.); this page shows how to set your own.

## Setup

### Bare Vue 3

```ts
// main.ts
import { createApp } from 'vue'
import { createAttaform } from 'attaform'
import App from './App.vue'

createApp(App)
  .use(
    createAttaform({
      defaults: {
        debounceMs: 100,
        onInvalidSubmit: 'focus-first-error',
      },
    })
  )
  .mount('#app')
```

### Nuxt 3 / 4

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['attaform/nuxt'],
  attaform: {
    defaults: {
      debounceMs: 100,
      onInvalidSubmit: 'focus-first-error',
    },
  },
})
```

The Nuxt module surfaces the same `AttaformDefaults` type under `attaform.defaults` in your `nuxt.config.ts`; no separate `createAttaform` call needed.

## Resolution order

Per-form > app-level > library default. Per-form always wins.

```text
useForm({ … })  >  createAttaform({ defaults })  >  library default
```

## Merge semantics

Every option resolves independently. Set anything once at the app level, override anything per-form without losing the rest:

```ts
// Plugin side
createAttaform({
  defaults: { validateOn: 'change', debounceMs: 100 },
})

// useForm calls
useForm({ schema })
// → validateOn: 'change', debounceMs: 100 (both inherited)

useForm({ schema, validateOn: 'blur' })
// → validateOn: 'blur'; debounceMs is dropped
//   (the TS-level ValidateOnConfig discriminated union rejects
//    debounceMs when validateOn isn't 'change'; paired with 'blur'
//    is a compile-time error)

useForm({ schema, debounceMs: 25 })
// → validateOn: 'change' (app-level), debounceMs: 25 (per-form wins)
```

`validateOn` and `debounceMs` are flat top-level fields. The `ValidateOnConfig` discriminated union enforces that `debounceMs` is only valid when `validateOn` is `'change'` (or omitted); pairing it with `'blur'` / `'submit'` doesn't compile.

## What's supported

`AttaformDefaults` covers the form-shaping options:

```ts
type AttaformDefaults = {
  strict?: boolean
  validateOn?: 'change' | 'blur' | 'submit'
  debounceMs?: number
  onInvalidSubmit?: 'none' | 'focus-first-error' | 'scroll-to-first-error' | 'both'
  history?: true | { max?: number }
  rememberVariants?: boolean
  coerce?: boolean | CoercionRegistry
  getDisplayState?: GetDisplayState
  maxRecursionDepth?: number
}
```

`getDisplayState` resolves `field.displayState` and its `show*` projections: the centralized "what should this field surface right now?" reducer, returning one of idle, pending, error, or success. Set it once at the app level so every form follows the same convention. To keep the default behavior but retune the anti-flash spinner timing, pass `makeDefaultDisplayState({ showDelay, minVisible })`. See [Display state and showing errors](/docs/validation/showing-errors) for the full contract.

## What's NOT supported (and why)

- `schema`: per-form by definition; a cross-form schema doesn't make sense.
- `key`: per-form identity.
- `defaultValues`: per-form initial values.

## Per-form `defaultValues`

Global defaults shape options like `strict` and `validateOn`. Per-form initial values live on each `useForm({ defaultValues })` call.

Three patterns:

```ts
import { unset } from 'attaform'

// 1. Plain values: explicit defaults flow into storage and the form
//    is not blank for those leaves.
useForm({ schema, defaultValues: { email: 'me@example.com', count: 10 } })

// 2. Omit defaultValues entirely: every NUMERIC primitive leaf
//    (number, bigint) is auto-marked blank at construction. Storage
//    holds the schema's slim defaults; the form displays empty;
//    `form.errors.<path>` reactively carries 'No value supplied' for
//    required schemas. Strings and booleans are NOT auto-marked
//    because their slim defaults match what the DOM shows natively.
useForm({ schema })

// 3. Mark any path as `unset`: leaf, container, or the whole form.
//    The runtime writes the schema's slim value at the path and adds
//    every primitive descendant to form.blankPaths.
useForm({ schema, defaultValues: { email: unset, count: 10 } })
useForm({ schema, defaultValues: { profile: unset } }) // container
useForm({ schema, defaultValues: unset }) // root
```

`unset` works in `setValue('profile', unset)` and `reset({ email: unset })` identically: same semantic at every position.

## Alternative: userland wrapper

If you need defaults but don't want to touch the plugin (third-party component library, opting in only for some forms), wrap `useForm` in your project:

```ts
// composables/useAppForm.ts
import { useForm as attaformUseForm } from 'attaform'
import type { z } from 'zod'

export function useAppForm<S extends z.ZodObject>(opts: Parameters<typeof attaformUseForm<S>>[0]) {
  return attaformUseForm({
    validateOn: 'change',
    debounceMs: 100,
    ...opts,
  })
}
```

Fully equivalent for the consumer; every `useAppForm` call gets your defaults; per-form options still win via the spread. The plugin-level approach is idiomatic for first-party apps; the wrapper is right when you can't (or shouldn't) influence the plugin config from your call site.

## Where to next

- [Display state and showing errors](/docs/validation/showing-errors): set the `getDisplayState` predicate app-wide for a consistent feel across forms.
- [When validation runs](/docs/validation/when-validation-runs): `validateOn` and `debounceMs` defaults shape every form in the app.

_Source: https://attaform.dev/docs/cross-cutting-state/app-defaults_

---

# useWizard

> Compose a reactive wizard from an ordered list of step slots. Each slot holds a form, an affordance key for a screen with no data collection, or a function that picks one or the other at runtime. Attaform threads the same handle through navigation, status aggregation, URL sync, and a `handleSubmit` that validates the whole wizard on every call.


A linear three-step wizard. Each step keeps its own `useForm` call, its own schema, and its own reactive surface. The rail highlights `wizard.currentStep`, the progress bar reflects `wizard.progress`, each Next calls `wizard.tryNext()` to gate advance on the active step, and Finish runs `wizard.handleSubmit` over the whole wizard.


## Forms and steps

Attaform separates two concepts that often get conflated in multistep code:

- A **form** is the artifact `useForm` returns: schema, fields, values, errors, submission. The central noun of Attaform.
- A **step** is a position in the wizard's sequence. Steps come in two flavors:
  - A **collection step** holds a form. The wizard gathers data here.
  - An **affordance step** holds a bare string key, no form. The wizard uses it for screens that present rather than collect: a welcome card, a terms-and-conditions panel, a review surface, a confirmation card.

A wizard's `steps` list mixes the two freely. The shape of a typical onboarding flow:

```ts
import { useForm, useWizard } from 'attaform'
import { z } from 'zod'

const shippingSchema = z.object({ address: z.string(), city: z.string() })
const contactSchema = z.object({ email: z.email(), phone: z.string() })
const paymentSchema = z.object({ cardNumber: z.string(), cvv: z.string() })
const billingSchema = z.object({ name: z.string(), address: z.string() })

const shipping = useForm({ schema: shippingSchema, key: 'shipping' })
const contact = useForm({ schema: contactSchema, key: 'contact' })
const payment = useForm({ schema: paymentSchema, key: 'payment' })
const billing = useForm({ schema: billingSchema, key: 'billing' })

const wizard = useWizard({
  steps: ['welcome', shipping, contact, 'shipping-review', payment, billing, 'final-review'],
})
```

Seven positions, four collection steps, three affordance steps. The wizard treats every position uniformly. `wizard.currentStep` walks the list left to right. `wizard.statuses[key]` answers for every step, with affordance steps reading as always-valid so a rail dot or progress fraction doesn't need to special-case them. Under the hood, each affordance step gets a wizard-owned noop form backed by an empty `AbstractSchema` (no fields, validates as `{}`), so affordance positions participate in the same registry, status, and submission machinery as schema-backed forms without the wizard knowing about Zod (or any other adapter).

Affordance steps are a first-class building block, not an edge case. Onboarding flows live or die by the breathing room between dense collection screens: the welcome card that sets expectations, the review surface that lets the user check their work, the congratulations card that confirms a transaction landed. Each one is one string in the `steps` array.

## Step slots

Each entry in `steps` is a **slot**. Four slot kinds compose the list:

```ts
import { useForm, useWizard, lazy } from 'attaform'

const wizard = useWizard({
  steps: [
    shipping, // form slot
    'shipping-review', // affordance slot
    (ctx) => (ctx.forms.contact.values.kind === 'business' ? billing : payment), // function slot
    lazy((ctx) => buildSummaryForm(ctx)), // memoized lazy slot
  ],
})
```

- **Form slot**: a form built with `useForm`. The wizard surfaces it as-is.
- **Affordance slot**: a bare string. Becomes the step's key; the wizard generates a noop form under it.
- **Function slot**: `(ctx) => Form | string | undefined`. Re-evaluates reactively as `ctx.forms.<key>.values` mutate. The picked result replaces the slot's compiled step. Returning `undefined` drops the slot.
- **Lazy slot**: `lazy((ctx) => ...)`. Memoized by the resolver's tracked reactive reads. Re-fires on dep change or `wizard.reset()`. Right shape for resolvers expensive enough that thrash matters.

See [Step slots](/docs/multistep/step-slots) for the full slot reference, including the `ctx` shape and the rules around reactive re-evaluation.

## Options

`useWizard` takes one options bag. `steps` is required; the rest default sensibly for the common URL-synchronized wizard case.

| Option            | Type                                                               | Default             | What it does                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `steps`           | `Array<StepSlot>`                                                  | required            | Ordered list of slots that compile into the wizard's step list. See [Step slots](/docs/multistep/step-slots).                                                       |
| `key`             | `string`                                                           | synthetic           | Identifier registered in the per-app registry for [`injectWizard`](/docs/multistep/inject-wizard). Anonymous wizards get a synthetic SSR-stable key under the hood. |
| `defaultStatuses` | `Record<key, FormStatus>` &#124; sync factory &#124; async factory | unset               | Seed payload used while a form's defaults are still resolving. See [Statuses](/docs/multistep/statuses).                                                            |
| `progress`        | `(steps) => number`                                                | valid-step fraction | Override the default `progress` computation. The override is invoked inside a `computed`, so read reactive sources only.                                            |
| `focusFirstError` | `boolean`                                                          | `true`              | On submission failure, jump to the first failing form and run its `applyInvalidSubmitPolicy()` (focus / scroll per the form's `onInvalidSubmit` configuration).     |
| `restore`         | `() => { step? }` &#124; `false`                                   | URL `?step=<key>`   | Source of truth for the active step. Watched reactively; re-applies on URL changes. See [URL sync](/docs/multistep/url-sync).                                       |
| `persist`         | `({ step }) => void` &#124; `false`                                | URL `?step=<key>`   | Destination for the active step. Invoked when `currentStep` changes (diffed to break the restore-persist loop). See [URL sync](/docs/multistep/url-sync).           |

## The wizard handle

`useWizard` returns a reactive handle. Every reactive read is a plain getter, no `.value`. Use the rail of links below to reach the page that covers each surface in depth.

| Member               | What it is                                                                                                                                                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`                | The wizard's identifier (explicit or synthetic).                                                                                                                                                                            |
| `currentStep`        | The active step's key. Typed `string` when the slot tuple is statically non-empty; `string` &#124; `undefined` when a function slot can drop.                                                                               |
| `activeForm`         | A live view of the active step's form; operating through it always targets the current step. No longer identity-equal to `wizard.forms[currentStep]` (use that for the raw handle). Narrows in lockstep with `currentStep`. |
| `activeIndex`        | Zero-based position of the active step.                                                                                                                                                                                     |
| `isFinalStep`        | `true` when `activeIndex === count - 1`. Gates the Next-vs-Finish split in templates.                                                                                                                                       |
| `count`              | `steps.length`. Includes affordance positions.                                                                                                                                                                              |
| `steps`              | Ordered list of compiled `{ key, form }` slots. See [Step slots](/docs/multistep/step-slots).                                                                                                                               |
| `forms`              | Record indexable by step key. See [Aggregates](/docs/multistep/aggregates).                                                                                                                                                 |
| `canAdvance`         | `true` when a next step exists. Pure positional check.                                                                                                                                                                      |
| `canGoBack`          | `true` when a prior step exists.                                                                                                                                                                                            |
| `complete`           | Forward-looking: `isFinalStep && every-form-valid`. See [Statuses](/docs/multistep/statuses).                                                                                                                               |
| `done`               | Monotonic: `true` once a `handleSubmit` succeeds; only `reset()` flips it back. See [Statuses](/docs/multistep/statuses).                                                                                                   |
| `submitting`         | `true` while a `wizard.handleSubmit` call is in flight. Global re-entrance guard.                                                                                                                                           |
| `submissionAttempts` | Count of `wizard.handleSubmit` invocations.                                                                                                                                                                                 |
| `visited`            | Append-only breadcrumb of navigated step keys.                                                                                                                                                                              |
| `progress`           | Fraction in `[0, 1]`. Defaults to valid-step ratio.                                                                                                                                                                         |
| `statuses`           | Per-key `FormStatus` proxy. See [Statuses](/docs/multistep/statuses).                                                                                                                                                       |
| `allValues`          | Namespaced record of each step's values. See [Aggregates](/docs/multistep/aggregates).                                                                                                                                      |
| `allErrors`          | Namespaced record of each step's validation errors. See [Aggregates](/docs/multistep/aggregates).                                                                                                                           |
| `next` / `back`      | Positional navigation. Refuses while `submitting`.                                                                                                                                                                          |
| `goTo`               | Jump to a specific step by key. Dev-warn on unknown keys.                                                                                                                                                                   |
| `tryNext`            | Validate the active step, advance iff valid; resolves to whether the pin moved. The inline-bindable gated Next. See [handleSubmit](/docs/multistep/handle-submit#gating-advance-per-step).                                  |
| `handleSubmit`       | Whole-wizard submission handler; never advances. See [handleSubmit](/docs/multistep/handle-submit).                                                                                                                         |
| `reset`              | Zeros wizard lifecycle, resets every form, returns to `steps[0]`, clears the persisted step, flips `done` back.                                                                                                             |

## Submission, in one place

`wizard.handleSubmit(onSubmit, onError?)` returns one event handler that validates the entire step list, from any step, and calls `onSubmit` once with every step's values. It never advances; bind it to your Finish button.

```ts
const onFinish = wizard.handleSubmit(async (ctx) => {
  await api.checkout({
    shipping: ctx.get(shipping),
    payment: ctx.get(payment),
  })
})
```

To gate a Next button on the active step's validity, reach for `wizard.tryNext()`:

```ts
await wizard.tryNext() // validate the active step, advance only on a clean pass
```

`wizard.tryNext()` binds straight to a control (`@click="wizard.tryNext()"`) and resolves to whether the pin moved. For custom valid or invalid handling, compose the active form's submit with `next()` instead: `wizard.activeForm.handleSubmit(() => wizard.next())`.

See [handleSubmit](/docs/multistep/handle-submit) for the whole-wizard handler in depth, including the gated-advance composition, `focusFirstError`, re-entrance, error aggregation, and the `ctx` shape.

## Navigation

```ts
await wizard.next() // advance one position
wizard.back() // retreat one position
wizard.goTo('shipping-review') // jump to a specific step by key
```

`next` / `back` / `goTo` are pure positional navigation. None of them validate. To gate an advance on the active step, use `wizard.tryNext()` (or compose `wizard.activeForm.handleSubmit(() => wizard.next())` when you need custom valid or invalid handling). Out-of-bounds calls dev-warn and no-op; mid-submission navigation is blocked until `wizard.submitting` clears. A wizard wired into a checkout or signup never throws on navigation.

## URL sync, on by default

A wizard with no extra options reads its starting step from `?step=<key>` on the URL and writes the active step back as the user navigates. Reloads land on the same step, the browser back / forward buttons walk the flow, and the URL is shareable. On the server, the wizard reads the incoming request's `?step` so deep-links render the right step on the first byte.

```ts
import { useForm, useWizard } from 'attaform'

const wizard = useWizard({
  steps: ['welcome', shipping, payment, 'final-review'],
  // restore: defaults to reading ?step=<key>
  // persist: defaults to writing ?step=<key>
})
```

To rename the param, scope it across multiple wizards on the same page, or wire the state to non-URL storage (localStorage, a broadcast channel, a router state field), pass `restore` and `persist` callbacks. See [URL sync](/docs/multistep/url-sync).

## Cross-component access with `key`

Pass `key` to give the wizard a stable identifier. Any descendant component reaches the same reactive handle through [`injectWizard`](/docs/multistep/inject-wizard) without prop-threading:

```ts
const wizard = useWizard({
  steps: ['welcome', shipping, payment, 'final-review'],
  key: 'checkout',
})
```

Anonymous wizards (option omitted) get a synthetic SSR-stable key under the hood and remain reachable via ambient `injectWizard()` from descendants of the parent that called `useWizard`.

## Degenerate inputs

Conditions that would otherwise crash the surrounding app dev-warn and degrade:

- **Empty `steps` array.** Dev-warns and degrades. `wizard.currentStep` reads as `undefined`, navigation refuses, the surrounding app keeps rendering.
- **Duplicate step keys.** First occurrence wins; later duplicates dev-warn and drop.
- **Same form ref in multiple slots.** First slot keeps the canonical position; later slots dev-warn and drop.
- **`defaultStatuses` with an unknown key.** Ignored; known entries still apply.
- **`restore` returns a key not in the compiled steps.** Dev-warn; the wizard falls back to the first step.

A wizard wired into a signup or checkout never crashes the surrounding app for shapes that are clearly a mistake.

## Where to next

- [Step slots](/docs/multistep/step-slots) for the full slot reference (form, string, function, lazy).
- [`injectWizard`](/docs/multistep/inject-wizard) for cross-component access to the wizard handle.
- [Statuses](/docs/multistep/statuses) for the per-step rollup, `defaultStatuses`, `complete`, and `done`.
- [Aggregates](/docs/multistep/aggregates) for `allValues`, `allErrors`, and `forms`.
- [handleSubmit](/docs/multistep/handle-submit) for the universal submission pipeline.
- [URL sync](/docs/multistep/url-sync) for `restore` / `persist` and the SSR hand-off.
- [Patterns](/docs/multistep/patterns) for branching, review surfaces, per-step persistence and undo.

_Source: https://attaform.dev/docs/multistep/use-wizard_

---

# `injectWizard`

> Reach a registered wizard from any descendant component. Ambient resolution for the parent's own wizard, keyed resolution for distant ones, and a single `null` on miss instead of a thrown error so floating panels, sticky nav rails, and sidebar widgets stay robust to mount-order quirks.


`useWizard` creates and provides the wizard handle; `injectWizard` looks it up. The two compose the way `useForm` and [`injectForm`](/docs/cross-cutting-state/inject-form) do, scaled up to the wizard handle so a progress rail, a floating finish button, or a deep-tree review summary can reach the wizard without prop-threading.

## The common case, ambient resolution

The parent owns the wizard (no `key`):

```vue
<!-- CheckoutWizard.vue -->
<script setup lang="ts">
  import { useForm, useWizard } from 'attaform'
  import { z } from 'zod'

  const shippingSchema = z.object({ address: z.string(), city: z.string() })
  const paymentSchema = z.object({ cardNumber: z.string(), cvv: z.string() })

  const shipping = useForm({ schema: shippingSchema, key: 'shipping' })
  const payment = useForm({ schema: paymentSchema, key: 'payment' })

  const wizard = useWizard({
    steps: ['welcome', shipping, payment, 'final-review'],
  })
</script>

<template>
  <ProgressRail />
  <StepBody />
  <NavButtons />
</template>
```

Any descendant grabs the same wizard:

```vue
<!-- ProgressRail.vue -->
<script setup lang="ts">
  import { injectWizard } from 'attaform'

  const wizard = injectWizard()
</script>

<template>
  <ol v-if="wizard">
    <li
      v-for="(step, i) in wizard.steps"
      :key="step.key"
      :class="{
        done: wizard.statuses[step.key]?.valid,
        current: wizard.currentStep === step.key,
      }"
    >
      <button type="button" @click="wizard.goTo(step.key)">Step {{ i + 1 }}</button>
    </li>
  </ol>
</template>
```

The rail reads `wizard.currentStep`, `wizard.statuses`, and `wizard.steps` exactly the way the parent does. Same reactive surface, same identity. Updates in the parent propagate to the child without a roundtrip.

## Reaching a wizard that isn't an ancestor

Sticky finish buttons, sidebar status widgets, or any component in a different branch of the tree look up the wizard by `key`:

```vue
<!-- CheckoutWizard.vue -->
<script setup lang="ts">
  const wizard = useWizard({
    steps: ['welcome', shipping, payment, 'final-review'],
    key: 'checkout-wizard',
  })
</script>
```

```vue
<!-- FloatingFinishButton.vue (anywhere in the app) -->
<script setup lang="ts">
  import { injectWizard } from 'attaform'

  const wizard = injectWizard('checkout-wizard')

  const finish = wizard?.handleSubmit(async (ctx) => {
    await api.checkout(ctx.values)
  })
</script>

<template>
  <button v-if="wizard" :disabled="!wizard.complete" @click="finish">Finish</button>
</template>
```

Pass the same `key` the parent passed to `useWizard({ key: 'checkout-wizard' })`. The handle returned is identity-equal to the parent's, so `wizard.handleSubmit` wired from a floating button runs the same submission pipeline the parent's Finish button would.

`injectWizard` accepts an object form too: `injectWizard({ key: 'checkout-wizard' })`. The positional and object forms are equivalent; pick whichever spreads better into the surrounding setup.

## How a key resolves

`injectWizard('checkout-wizard')` resolves through the same registry that backs `injectForm`, with the same two properties. It is **position-independent** (the handle lives in Attaform's app-level registry, so any component reaches it regardless of branch or depth) and **time-dependent** (the entry appears once the wizard's own `useWizard({ key })` setup has run, and not before). The [How a key resolves](/docs/cross-cutting-state/inject-form#how-a-key-resolves) section on `injectForm` walks the shared mechanism and the resolve-downward rule in full.

One corollary is specific to wizards. The form steps you pass to `useWizard({ steps })` are `useForm` handles, so they follow the same ordering: they have to exist when the wizard's setup runs. A form created inside a step's own child component does not exist yet at that point, which is why the checkout example above creates `shipping` and `payment` in the same component as the `useWizard` call. Create the step forms alongside the wizard, or above it, and the wizard has them the moment it is built.

## Do I need to pass a `key` to `useWizard`?

The two resolution modes are cleanly split:

- **Anonymous (no `key`) reaches ambient.** `useWizard({ steps })` fills the parent's ambient slot. Any descendant's `injectWizard()` (no key) resolves to it; closest ancestor wins when nested.
- **Keyed (`key: 'x'`) reaches explicit access only.** `useWizard({ steps, key: 'x' })` registers the wizard under `'x'` but does NOT fill the ambient slot. Descendants reach it via `injectWizard('x')`, not via the no-key form.

Skip `key` for single-component wizards (an in-page checkout, a modal flow). Supply one when you want cross-tree lookup, a stable identifier for DevTools, or a sticky finish button rendered far from the step container.

### Gotcha: multiple anonymous `useWizard` in one component

Vue's `provide` / `inject` is last-write-wins per component. If a parent calls `useWizard` twice without keys, the second overwrites the first in the ambient slot, and descendants using `injectWizard()` only see the second.

```ts
// Parent component
const checkout = useWizard({ steps: [shipping, payment] }) // ambient → checkout
const cancel = useWizard({ steps: [reasons, confirm] }) // ambient → cancel (overwrites checkout)
// Descendants' injectWizard() reads cancel. checkout is unreachable via ambient.
```

Attaform emits a dev-mode `console.warn` lazily, when (and only when) a descendant actually consumes the ambient slot via `injectWizard()` with no key. The warning lists each anonymous `useWizard()` call by source frame so you can navigate to the offending sites.

**Fix:** give each wizard a key (which removes them from the ambient slot entirely) and look them up explicitly:

```ts
useWizard({ steps: [shipping, payment], key: 'checkout' })
useWizard({ steps: [reasons, confirm], key: 'cancel' })
// Descendants:
const checkout = injectWizard('checkout')
const cancel = injectWizard('cancel')
```

Mixing modes is fine. Keyed wizards don't interfere with an ambient sibling. A parent with three keyed wizards plus one anonymous wizard produces no warning; the descendant's `injectWizard()` unambiguously resolves to the (only) anonymous one.

## When resolution fails

`injectWizard` returns `null` rather than throwing, so descendants are robust to mount-order quirks (a sidebar widget that renders before the wizard's parent setup runs, a conditional wizard ancestor, dynamic imports). Two cases produce `null`:

- **No ambient wizard.** `injectWizard()` called from a tree with no ancestor `useWizard` and no key. Returns `null` silently. Ambient lookup is opportunistic, so a floating widget reading the ambient slot stays quiet in trees that don't have a wizard rather than spamming consumers' consoles.
- **Key not registered.** `injectWizard('checkout-wizard')` called when nothing is registered under that key. Dev mode logs the unresolved key alongside any keys that ARE registered, so a typo surfaces at a glance. If the wizard is created lower in the tree, it registers after this call runs; see [How a key resolves](#how-a-key-resolves).

Guard the return so the consumer disappears cleanly when the wizard isn't mounted:

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

  const wizard = injectWizard('checkout-wizard')
</script>

<template>
  <aside v-if="wizard" class="wizard-status">
    Step {{ wizard.activeIndex + 1 }} of {{ wizard.count }}
  </aside>
</template>
```

## Lifetime

Both resolution modes ref-count the wizard handle in the registry. In practice:

- The wizard survives until every component that reached it unmounts.
- Cleanup is automatic; no explicit dispose call from the consumer.
- A wizard accessed only by `injectWizard(key)` stays alive as long as at least one consumer is mounted, even if the parent `useWizard` owner unmounted first.

Hot-module reload reuses the existing handle when the parent SFC re-mounts (deferred-eviction-cancel within the same microtask). Child `injectWizard` consumers see the same wizard reactive surface they had before, not a freshly created one, so a rail's pre-filled state survives every save.

## Duplicate keys

Two calls to `useWizard({ steps, key: 'checkout-wizard' })` in the same app: the first wizard stays in the registry under that key, the second call dev-warns and the registry entry is left untouched. Any `injectWizard('checkout-wizard')` resolves to the original. The dev-warn names the colliding key so the accidental duplicate setup surfaces at a glance.

## SSR isolation

The wizard registry lives on the per-request `AttaformRegistry` instance created by `createAttaform()`. A wizard registered in one server request does not leak into a sibling request rendering at the same time. The same isolation applies to forms registered through [`injectForm`](/docs/cross-cutting-state/inject-form).

## Where to next

- [`useWizard`](/docs/multistep/use-wizard) for the construction signature and the wizard's full reactive surface.
- [Statuses](/docs/multistep/statuses) for the per-step rollup that drives a progress rail's classes.
- [Step slots](/docs/multistep/step-slots) for the slot kinds that fill the `steps` list.
- [`injectForm`](/docs/cross-cutting-state/inject-form) for single-form sharing across a tree.

_Source: https://attaform.dev/docs/multistep/inject-wizard_

---

# Step slots

> Slots are the entries that fill `useWizard({ steps })`. A flow's shape lives entirely in the array: forms for collection screens, bare strings for affordance screens, functions for runtime branching, and `lazy()` for memoized resolution that re-fires only on its own tracked reactive reads. Each slot compiles into a uniform `{ key, form }` step, so the navigation, status, and submission machinery never has to special-case a kind.


The previous page ([`useWizard`](/docs/multistep/use-wizard)) introduced slots at a glance. This page is the deep dive: what each slot kind brings, the `ctx` shape that function and `lazy()` slots receive, and the rules around drop, dedup, and re-evaluation.

The demo below stitches all four kinds into one flow: a `'welcome'` string, a single attendee form, a function slot that branches by role (and returns a bare string for the no-extras path), another function slot that drops when traveling solo, a `lazy()` resolver for the regional pricing form, and a `'review'` string at the end.


## The four kinds at a glance

```ts
import { useForm, useWizard, lazy } from 'attaform'

const shipping = useForm({ schema: shippingSchema, key: 'shipping' })
const business = useForm({ schema: businessSchema, key: 'business' })
const consumer = useForm({ schema: consumerSchema, key: 'consumer' })

const wizard = useWizard({
  steps: [
    'welcome', // affordance slot (string)
    shipping, // form slot
    (ctx) => (ctx.forms.shipping.values.kind === 'business' ? business : consumer), // function slot
    lazy((ctx) => buildSummaryFormFor(ctx)), // memoized lazy slot
    'congrats', // affordance slot
  ],
})
```

Five positions, all uniform downstream. `wizard.currentStep`, `wizard.statuses[key]`, and `wizard.handleSubmit` operate the same whether the active step came from a form ref or a string. The slot kind shapes _how_ the position resolves, not _what_ it produces.

## Form slots

A form built with `useForm` slotted directly into the array. The wizard surfaces it as-is: the form's `key`, schema, fields, values, and submission pipeline are reachable through `wizard.forms[form.key]`, `wizard.statuses[form.key]`, `wizard.allValues[form.key]`, and friends.

```ts
const shipping = useForm({ schema: shippingSchema, key: 'shipping' })
const payment = useForm({ schema: paymentSchema, key: 'payment' })

const wizard = useWizard({ steps: [shipping, payment] })
```

The same form ref can be shared with anything else in the app (props, `injectForm`, a different wizard). The wizard ref-counts each form for its lifetime; tearing down the wizard releases the consumer count without disposing forms that other components still hold.

## Affordance slots (string)

A bare string. The wizard generates a noop form under that key, backed by an empty `AbstractSchema` that always validates as `{}`. Affordance positions never collect data: welcome cards, terms-and-conditions panels, review surfaces, and confirmation cards each occupy one string in the array.

```ts
const wizard = useWizard({
  steps: ['welcome', shipping, payment, 'order-review', 'confirmation'],
})
```

Every downstream surface treats the string slot identically to a form slot:

- `wizard.steps[i]` reads as `{ key: 'welcome', form: <noopForm> }`.
- `wizard.statuses['welcome']` reads as `{ valid: true, errorCount: 0, ... }`.
- `wizard.allValues['welcome']` is the empty record `{}`.
- `wizard.handleSubmit` validates the affordance step trivially as `{}`, along with every other step.

The noop form is real: it carries a key, sits in the per-app registry, and participates in `injectForm('welcome')` lookups the same way any other form does. Affordance steps are first-class building blocks, not edge cases.

### When two string slots collide on a key

```ts
useWizard({ steps: ['welcome', shipping, 'welcome'] }) // duplicate 'welcome'
```

First occurrence wins. The second dev-warns and drops. The wizard still navigates without crashing.

## Conditional steps

Any position in the array can be `null` or `undefined`, and the wizard drops it from the compiled list. That lets a step appear or disappear on a condition written inline, with no imperative pre-filtering of the array:

```ts
const wizard = useWizard({
  steps: [account, needsShipping ? shipping : null, payment, isGuest ? null : 'account-review'],
})
```

A literal `null` element evaluates once, when the array is built, so it fits a condition that is fixed for the wizard's life: a plan tier, a feature flag. For a condition that changes as the user works, reach for a [function slot](#function-slots) that returns `null`, so the step's presence tracks the value reactively.

`null` and `undefined` are interchangeable here; both mean "no step." The idiom is `cond ? form : null`, not `cond && form`: a bare `&&` yields `false`, and `false` is not a step (nor is there a step a `true` could stand for), so the wizard accepts only the nullish forms.

A form kept behind a conditional stays fully typed: with `steps: [account, show ? shipping : null]`, `wizard.forms.shipping` still resolves to the concrete `shipping` handle. When every position in the array can drop, `wizard.currentStep` reads as `FormKey | undefined`, since the compiled list might be empty.

## Function slots

A function that picks one of the three slot kinds at runtime: `(ctx) => Form | string | null | undefined`. The wizard re-invokes function slots reactively whenever the reads inside them change, so branching logic stays in sync with live form values.

```ts
const account = useForm({ schema: accountSchema, key: 'account' })
const business = useForm({ schema: businessSchema, key: 'business' })
const consumer = useForm({ schema: consumerSchema, key: 'consumer' })

const wizard = useWizard({
  steps: [
    account,
    (ctx) => (ctx.forms.account.values.kind === 'business' ? business : consumer),
    'confirmation',
  ],
})
```

When the user picks `'business'` on the account step, the branching slot resolves to `business`. Switching back to `'consumer'` swaps the resolved form. `wizard.steps`, `wizard.forms`, and the progress rail follow along.

### Return values

| Return               | Result                                                                                                                                                                                       |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| An `AnyForm` ref     | The slot compiles to `{ key: form.key, form }`.                                                                                                                                              |
| A `string` key       | The slot resolves to a noop affordance step under that key. New keys are built on the fly; the same key returned twice reuses the same noop. No pre-declaration needed elsewhere in `steps`. |
| `null` / `undefined` | The slot is dropped from the compiled list. Useful for "this branch isn't relevant right now"; the step rail shortens accordingly.                                                           |

### Reactive re-evaluation

Function slots re-evaluate whenever the wizard's compiled list re-evaluates, which includes the case where _another_ slot's deps changed. Keep slot bodies cheap: a branch on `ctx.forms.<key>.values.<path>` is fine; a `fetch(...)` is not (slot evaluation is synchronous, and re-evaluating an expensive lookup on every keystroke is wasted work). Reach for [`lazy()`](#lazy-slots-lazy) when the resolver is heavy and should only re-fire on its own tracked reads.

### Dropping a slot keeps navigation honest

```ts
const wizard = useWizard({
  steps: [
    account,
    (ctx) => (ctx.forms.account.values.needsId ? idVerification : undefined),
    confirm,
  ],
})
```

When the user toggles `needsId` off, the middle slot drops. `wizard.count` falls from 3 to 2, and navigation buttons reflect the new positions. If the wizard was sitting on the dropped step, the pin slides forward to the step that took its slot, clamping to the new last step when the dropped one was last, so `wizard.currentStep` and `wizard.activeForm` stay on a live step instead of snapping back to the first.

## Lazy slots (`lazy()`)

### What problem `lazy()` solves

Plain function slots re-evaluate whenever the wizard's compiled list re-evaluates, which happens any time _any_ slot's reactive reads move. That's perfect for the common case: cheap branches on live values reading `ctx.forms.<key>.values.<path>` and returning a form or a string. The wizard re-compiles, the function slot runs again, no harm done.

The pattern stops scaling when a resolver is expensive enough that running it on every wizard mutation produces visible thrash. A factory that builds a region-specific schema from already-loaded config. A heavy validator derived from runtime data. A tenant-specific form layout assembled from server-resolved defaults. Plain function slots re-fire that resolver every time the user toggles _any_ field anywhere in the wizard, because every field edit re-triggers the compiled list.

Resolver bodies are synchronous, so async work belongs upstream: load the source data with Nuxt's `useAsyncData` / `useFetch` (which already transfers the result from server to client), then read the resolved ref inside the lazy resolver to derive a form.

`lazy()` is the opt-in cache for those resolvers. Each lazy slot gets its own memoized `computed`: the resolver fires once on the first compile pass, and the result holds until one of the resolver's _own_ tracked reactive reads changes. Reads elsewhere in the wizard (other slots' deps, navigation churn, sibling form mutations) leave the cache intact. It's the same opt-in memoization Vue's `computed` gives you anywhere else, applied at the slot level.

```ts
// Plain function slot: re-fires every time the compiled list re-evaluates,
// which includes unrelated form edits elsewhere in the wizard.
;(ctx) => buildPricingFor(ctx.forms.account.values.region)

// Lazy slot: re-fires only when `region` actually changes.
lazy((ctx) => buildPricingFor(ctx.forms.account.values.region))
```

### How it works

```ts
import { useForm, useWizard, lazy } from 'attaform'

const wizard = useWizard({
  steps: [
    account,
    lazy((ctx) => buildShippingFormForRegion(ctx.forms.account.values.region)),
    confirm,
  ],
})
```

The `buildShippingFormForRegion(...)` call fires on the first compile pass. When the user later edits `region`, the resolver re-fires because `region` is one of its tracked reactive reads, and the rail swaps to the freshly-built form. Changes to _unrelated_ wizard state (a different form's field, another slot's branch) leave the cache untouched. `wizard.reset()` bumps an internal epoch so every lazy resolver re-fires on the next compile pass, regardless of whether any tracked read moved; that's what makes a reset a true reboot.

```ts
// One-shot resolution: read the snapshot outside the resolver so the
// closure has no reactive deps. Then `lazy()` only re-fires on reset.
const initialRegion = account.values.region
lazy(() => buildShippingFormForRegion(initialRegion))
```

### Resolution semantics

| Return               | Behavior                                                                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| An `AnyForm` ref     | The form caches at that position. Subsequent reads reuse it until a tracked dep changes or `reset()` invalidates the cache.                             |
| A `string` key       | Resolves to a noop affordance step under that key, building one on the fly if needed. Result caches under the same dep-tracking rules as a form return. |
| `null` / `undefined` | The slot drops from the compiled list. The drop caches; a tracked dep change or `reset()` re-fires the resolver.                                        |

Use `lazy()` when the resolution is expensive enough that thrash matters. For everyday branching on live values, plain function slots are simpler. They re-evaluate freely with the compiled list, and the wizard pays no cache-bookkeeping cost.

## The `ctx` surface

Function slots and `lazy()` resolvers each receive a single `ctx` argument:

```ts
type WizardCtx = {
  readonly forms: Readonly<Record<FormKey, WizardCtxForm>>
  readonly currentKey: FormKey | undefined
}

type WizardCtxForm = AnyForm & {
  readonly values: Readonly<Record<string, unknown>>
}
```

- `ctx.forms.<key>` is the projection over every form reachable through a top-level slot. Reads are loose-typed (`unknown`), since the wizard does not generically thread each form's schema through this surface. For typed access, close over the original form ref:

  ```ts
  const account = useForm({ schema: accountSchema, key: 'account' })

  const wizard = useWizard({
    steps: [
      account,
      (ctx) => (account.values.kind === 'business' ? business : consumer), // typed!
      // not: ctx.forms.account.values.kind  (loose-typed)
    ],
  })
  ```

  Both forms work at runtime. The closed-over ref keeps the schema type intact through the predicate, which IDEs and review-flag tooling appreciate.

- `ctx.currentKey` is the key of the step currently active. Reads as `undefined` on the first compile pass before activation lands, so guard with `!== undefined` when the slot's decision depends on position.

## The compiled step shape

Each surviving slot compiles to a `CompiledStep`:

```ts
type CompiledStep = {
  readonly key: FormKey
  readonly form: AnyForm
}
```

`wizard.steps[i]` reads as `{ key, form }`. The list is ordered, dedupes by form key (first occurrence wins), and drops any slot whose resolver returned `undefined`. The compiled list is what every downstream surface walks: navigation, the progress rail, statuses, aggregates.

```ts
for (const step of wizard.steps) {
  console.log(step.key, step.form.meta.valid)
}
```

## Drop and dedup semantics

A few rules govern how the source slot list compiles down to the final step list:

- **Duplicate keys.** Two slots producing the same step key (string slot vs form ref, or two functions returning the same form): first occurrence wins. Later duplicates dev-warn and drop. Keeps `wizard.steps` linearly addressable.
- **Literal `null` / `undefined` element.** Dropped when the array compiles, so a `cond ? form : null` conditional needs no pre-filtering. See [Conditional steps](#conditional-steps).
- **`null` / `undefined` from a function slot.** The slot drops; subsequent reads of `wizard.steps` reflect the shortened list. Re-running the slot (a reactive read changed) can reintroduce the position. If the dropped slot was the active step, the pin slides forward to the step that took its place.
- **`null` / `undefined` from a `lazy()` slot.** The slot drops. The drop caches; a tracked-dep change or `reset()` re-fires the resolver, and if it returns nullish again, the slot drops again.
- **Function or `lazy()` slot returns a new string key.** The wizard builds a noop affordance step on the fly under that key and threads it into the compiled list, the statuses surface, and the rail. The same key returned by a later slot reuses the same noop (first-build wins). No pre-declaration anywhere in `steps` is required.
- **Empty compiled list.** If every slot drops (including an array that is entirely nullish), `wizard.currentStep` reads as `undefined`, navigation refuses with a dev-warn, and the surrounding app keeps rendering. See [Degenerate inputs](/docs/multistep/use-wizard#degenerate-inputs).

## Where to next

- [`useWizard`](/docs/multistep/use-wizard) for the construction signature and full reactive surface.
- [Statuses](/docs/multistep/statuses) for the per-step rollup that drives a rail.
- [Aggregates](/docs/multistep/aggregates) for `wizard.allValues`, `wizard.allErrors`, and `wizard.forms`.
- [handleSubmit](/docs/multistep/handle-submit) for the universal submission pipeline that handles every slot kind uniformly.
- [Patterns](/docs/multistep/patterns) for branching, review surfaces, and lazy heavy slots in real flows.

_Source: https://attaform.dev/docs/multistep/step-slots_

---

# Statuses

> `wizard.statuses` is a per-step `FormStatus` rollup that mirrors each form's `meta`. Read it drillably for templates, call it for a snapshot, or seed it up-front with `defaultStatuses` for resume flows that need to render filled rails before per-form data lands.


## The `FormStatus` shape

```ts
type FormStatus = {
  readonly valid: boolean
  readonly dirty: boolean
  readonly submitted: boolean
  readonly errorCount: number
}
```

Each field tracks the per-step form's `meta`. A step's status flips when its meta does. The four scalars are deliberately small. They're what step indicators, navigation gates, and submit summaries reach for.

## Reading patterns

`wizard.statuses` is both a drillable record and a callable accessor. Same data, three call shapes:

```ts
import { useForm, useWizard } from 'attaform'
import { z } from 'zod'

const accountSchema = z.object({ email: z.email() })
const profileSchema = z.object({ name: z.string().min(1) })

const account = useForm({ schema: accountSchema, key: 'signup-account' })
const profile = useForm({ schema: profileSchema, key: 'signup-profile' })

const wizard = useWizard({ steps: [account, profile] })

wizard.statuses // drillable record
wizard.statuses() // { 'signup-account': FormStatus, 'signup-profile': FormStatus }
wizard.statuses('signup-account') // FormStatus for one step
wizard.statuses['signup-account'] // FormStatus for one step (drillable)
wizard.statuses['signup-account'].valid // boolean
```

The drillable form is the template-friendly read; the callable form is convenient in script for one-off reads or destructured snapshots.

## Status rails

The classic use case is a step indicator: one dot per form, painted with its current state. `wizard.steps` walks the compiled positions; `wizard.statuses[step.key]` reads each one's status:

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

  const wizard = useWizard({ steps: [account, profile, review] })
</script>

<template>
  <ol class="wizard-rail">
    <li v-for="step in wizard.steps" :key="step.key">
      <span
        class="dot"
        :class="{
          done: wizard.statuses[step.key].valid,
          dirty: wizard.statuses[step.key].dirty,
          current: wizard.currentStep === step.key,
        }"
      />
      {{ step.key }}
    </li>
  </ol>
</template>
```

Affordance steps (bare-string slots) carry an always-valid status, so the rail can paint every position without special-casing them. See [Step slots](/docs/multistep/step-slots) for the affordance-slot story.

## Seeding with `defaultStatuses`

Resume flows (e-commerce checkouts reopened mid-purchase, partially-completed onboarding, draft restore) often need to render filled rails before any per-form data has loaded. The `defaultStatuses` option seeds `wizard.statuses` up-front. Three shapes mirror the `defaultValues` trichotomy.

A plain object for compile-time-known seeds:

```ts
const wizard = useWizard({
  steps: [account, profile, review],
  defaultStatuses: {
    'signup-account': { valid: true, dirty: false, submitted: true, errorCount: 0 },
    'signup-profile': { valid: false, dirty: true, submitted: false, errorCount: 1 },
    'signup-review': { valid: false, dirty: false, submitted: false, errorCount: 0 },
  },
})
```

A sync factory for seeds derived from synchronous state (a draft snapshot in a Pinia store, a URL parameter, a cookie):

```ts
const wizard = useWizard({
  steps: [account, profile, review],
  defaultStatuses: () => buildStatusesFromDraft(draftStore.snapshot),
})
```

An async factory for seeds that need a server round-trip (saved flow state, a server-rendered status payload):

```ts
const wizard = useWizard({
  steps: [account, profile, review],
  defaultStatuses: async () => fetchSavedFlowStatuses(userId),
})
```

The seed fills in until the real form data lands. Resolution priority per step:

1. The step's form has `defaultsResolved === true` (its async / sync defaults have settled). Status derives from `form.meta`.
2. The step is an affordance (noop form). The built-in always-valid status renders.
3. The step has a seed entry from `defaultStatuses`. The seed value renders.
4. Otherwise, a pending status renders (`valid: false, dirty: false, submitted: false, errorCount: 0`).

Unknown keys in the seed object dev-warn at construction; the wizard ignores them. Known keys still apply, so a partial seed is fine.

## Reacting to status changes

`wizard.statuses` is reactive, so Vue's `watch` is the right tool for one-off side effects (analytics, autosave, a celebration toast when the last step flips valid). The status proxy plugs into Vue's reactivity the same way `form.meta` does:

```ts
import { watch } from 'vue'
import { useForm, useWizard } from 'attaform'

const wizard = useWizard({ steps: [account, profile, review] })

watch(
  () => wizard.statuses['signup-profile'].valid,
  (isValid) => {
    if (isValid) analytics.track('profile_complete', { user: userId })
  }
)
```

For a whole-wizard sweep, watch the callable form and diff against the previous snapshot:

```ts
watch(
  () => wizard.statuses(),
  (next, prev) => {
    for (const [key, status] of Object.entries(next)) {
      if (status.valid && !prev[key]?.valid) {
        analytics.track('step_valid', { key })
      }
    }
  },
  { deep: true }
)
```

## Where to next

- [`useWizard`](/docs/multistep/use-wizard) for the construction signature and the wizard's full reactive surface.
- [Aggregates](/docs/multistep/aggregates) for `wizard.allValues` and `wizard.allErrors`.
- [handleSubmit](/docs/multistep/handle-submit) for the submission pipeline that flips per-form `submitted`.

_Source: https://attaform.dev/docs/multistep/statuses_

---

# Aggregates

> `wizard.allValues` and `wizard.allErrors` are records keyed by step key, ready for review screens and error-summary panels. `wizard.forms` is the typed record of every form in the compiled list. The three surfaces share one shape and one read pattern: indexable, drillable, and reactive end-to-end.


## `allValues` for review screens

The final step of a wizard often shows everything the user entered, gated behind a confirm-and-submit button. `wizard.allValues` is the cross-step read surface, keyed by step key:

```ts
import { useForm, useWizard } from 'attaform'
import { z } from 'zod'

const accountSchema = z.object({ email: z.email(), name: z.string().min(1) })
const profileSchema = z.object({ city: z.string(), country: z.string() })
const reviewSchema = z.object({ tos: z.literal(true) })

const account = useForm({ schema: accountSchema, key: 'signup-account' })
const profile = useForm({ schema: profileSchema, key: 'signup-profile' })
const review = useForm({ schema: reviewSchema, key: 'signup-review' })

const wizard = useWizard({ steps: [account, profile, review] })
```

```vue
<template>
  <section v-if="wizard.currentStep === 'signup-review'">
    <h2>Review</h2>
    <dl>
      <dt>Email</dt>
      <dd>{{ wizard.allValues['signup-account'].email }}</dd>
      <dt>Name</dt>
      <dd>{{ wizard.allValues['signup-account'].name }}</dd>
      <dt>City</dt>
      <dd>{{ wizard.allValues['signup-profile'].city }}</dd>
      <dt>Country</dt>
      <dd>{{ wizard.allValues['signup-profile'].country }}</dd>
    </dl>
    <label>
      <input v-register="review.register('tos')" type="checkbox" />
      I agree
    </label>
  </section>
</template>
```

`wizard.allValues['signup-account'].email` proxies to the underlying form's `values.email`. The proxy is reactive: edits on earlier steps reflect in the review screen without a round trip. Affordance positions contribute empty objects under their key, so iterating the record stays safe even when the path mixes collection and affordance steps.

For typed reads, hold onto each form ref and drill through it directly. `wizard.allValues[key]` is typed `unknown` (the wizard doesn't generically thread each form's schema through the aggregate), so:

```ts
// Typed: the schema follows the ref.
const accountEmail = account.values.email

// Loose-typed: useful in template prose, cast or narrow in script.
const aggregateEmail = wizard.allValues['signup-account']
```

## `forms` for typed cross-step access

`wizard.forms` is the typed record of every form in the compiled list. Statically-known form slots contribute their concrete form type to the record; runtime-resolved positions (function slots, `lazy()` slots) fall under the catch-all `AnyForm` signature.

```ts
const wizard = useWizard({ steps: [account, profile, review] })

// account / profile / review keys typed to their concrete form refs:
wizard.forms['signup-account'].values.email // typed string
wizard.forms['signup-profile'].fields.city.showErrors // typed boolean

// Function-slot positions: AnyForm fallback.
wizard.forms['runtime-resolved-key'].values // typed unknown
```

The `forms` record is the right surface for cross-component reads. A floating-finish-button component reaches `wizard.forms[key]` to inspect any step's state, and the form handle that comes back is identity-equal to the original `useForm` ref. Mutations on one are observable on the other.

## `allErrors` for wizard-wide summaries

`wizard.allErrors` is a record keyed by step key. Each value is the flat list of `AggregateError` entries that step has produced:

```ts
type AggregateError = {
  readonly formKey: FormKey
  readonly path: ReadonlyArray<string | number>
  readonly message: string
  readonly code?: string
}

type AllErrors = Readonly<Record<FormKey, readonly AggregateError[]>>
```

Each entry carries `formKey` and `path` so a wizard-wide summary panel can route a click back to the offending field. Empty steps and unresolved steps contribute empty arrays under their key, keeping the record uniform.

For a wizard-wide summary, flatten the record into one array and render the union:

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

  const wizard = useWizard({ steps: [account, profile, review] })

  const flatErrors = computed(() => Object.values(wizard.allErrors).flat())
</script>

<template>
  <aside v-if="flatErrors.length > 0" class="error-summary">
    <h3>Fix {{ flatErrors.length }} issue(s) before continuing</h3>
    <ul>
      <li v-for="err in flatErrors" :key="`${err.formKey}-${err.path.join('.')}`">
        <button type="button" @click="wizard.goTo(err.formKey)">
          {{ err.message }} ({{ err.formKey }} · {{ err.path.join('.') }})
        </button>
      </li>
    </ul>
  </aside>
</template>
```

A click on any summary row jumps the wizard to the step that produced the error. The consumer wires the focus / scroll behavior from there (see `wizard.activeForm.focusField()` on the form handle).

For a per-step summary, index into the record directly:

```vue
<template>
  <aside v-if="(wizard.allErrors['signup-profile']?.length ?? 0) > 0">
    <h3>Profile step has {{ wizard.allErrors['signup-profile'].length }} issue(s)</h3>
  </aside>
</template>
```

## What contributes to the aggregates

Each surface walks the compiled step list:

- `allValues[key]` is the form's live `values` proxy. Edits land immediately.
- `allErrors[key]` is the form's `meta.errors`, rebuilt as `AggregateError` entries with `formKey` stamped on. A form whose defaults are still resolving contributes an empty array.
- `forms[key]` is the form handle itself, identity-equal to the original `useForm` ref.

Submitting the wizard via `wizard.handleSubmit` is what populates `allErrors` with validation results. See [handleSubmit](/docs/multistep/handle-submit) for the submission lifecycle that drives the aggregate.

## `wizard.submissionAttempts` vs per-form attempts

Each form keeps its own `meta.submissionAttempts`, incremented by `wizard.handleSubmit` for every form, since it always validates the whole step list. A gated Next built on `wizard.activeForm.handleSubmit(...)` bumps only the active form. The wizard-level `wizard.submissionAttempts` increments once per `handleSubmit` invocation, regardless of how many forms were involved. For "did the user submit the wizard?" reach for `wizard.submissionAttempts`; for "has the user tried this step?" reach for the form's own `meta.submissionAttempts`.

## Where to next

- [`useWizard`](/docs/multistep/use-wizard) for navigation and `activeForm`.
- [Statuses](/docs/multistep/statuses) for the per-step `FormStatus` rollup that feeds rails and progress.
- [handleSubmit](/docs/multistep/handle-submit) for the submission pipeline that populates `allErrors`.

_Source: https://attaform.dev/docs/multistep/aggregates_

---

# `handleSubmit`

> `wizard.handleSubmit(onSubmit, onError?)` returns one event handler that validates the entire step list, no matter which step is active, and calls `onSubmit` once with every step's parsed values. It never advances the wizard. Gating a Next button on the active step's validity is a one-line composition, so submission and navigation stay separate verbs.


## `handleSubmit` submits the whole wizard

`wizard.handleSubmit` returns an event handler. It validates every step in parallel, and on a clean pass calls `onSubmit` once with the full values map. Bind it to your Finish button, or any submit-everything action:

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

  const wizard = useWizard({ steps: [shipping, payment, review] })

  const onFinish = wizard.handleSubmit(async (ctx) => {
    await api.checkout({
      shipping: ctx.get(shipping),
      payment: ctx.get(payment),
    })
  })
</script>

<template>
  <form @submit="onFinish">
    <!-- step body -->
    <button :disabled="wizard.submitting" type="submit">Finish</button>
  </form>
</template>
```

Because it validates the whole wizard from any step, you can call it the moment every step is filled, whether or not the user has walked to the last one. The handler accepts an optional `Event` and calls `preventDefault()` when one is passed, so `@submit` and `@click` both work. Bare imperative calls (`onFinish()` with no event) are fine too; the handler just skips the prevent step.

## The submit context

The `onSubmit` callback receives one `ctx` argument:

```ts
type WizardSubmitContext = {
  readonly values: Readonly<Record<FormKey, unknown>>
  readonly get: <F extends AnyForm>(form: F) => F extends { readonly values: infer V } ? V : unknown
  readonly currentKey: FormKey
  readonly isFinal: boolean
}
```

- `ctx.values` is the namespaced parsed payload, keyed by step key, carrying every step (since `handleSubmit` validates them all). Affordance steps contribute an empty record.
- `ctx.get(formRef)` is the typed accessor: pass a form ref, get back the parsed output narrowed to that form's schema. The handy shape when you have already closed over the form refs at construction.
- `ctx.currentKey` is the key of the step that fired this submission.
- `ctx.isFinal` is `true` when `currentKey` is the last position in `wizard.steps`. It is positional information only: it tells you where the submit fired, never what got validated. A user who steps back, edits, and submits from the middle sees `isFinal === false`, and the whole wizard is still processed.

```ts
const onFinish = wizard.handleSubmit(async (ctx) => {
  const order = await api.checkout({
    shipping: ctx.get(shipping),
    payment: ctx.get(payment),
  })
  router.push(`/orders/${order.id}`)
})
```

## Gating advance per step

`wizard.handleSubmit` submits; navigation is a separate verb. `wizard.next()`, `wizard.back()`, and `wizard.goTo()` move the pin and never validate. To advance a step only when it is valid, reach for `wizard.tryNext()`:

```vue
<template>
  <button type="button" @click="wizard.tryNext()">Next</button>
</template>
```

`wizard.tryNext()` validates the active step, advances only on a clean pass, and reveals the step's errors in place when it fails. No captured handler and no setup `const`: it binds straight to the button. To advance unconditionally (an autosave-style flow that defers the error waterfall to the final submit), call `wizard.next()` directly.

The choice of verb is the blocking policy: `wizard.tryNext()` for a blocking Next, `wizard.next()` for a non-blocking one. There is no mode flag and no `{ validate }` option to remember.

`tryNext()` resolves to whether the pin moved, so it doubles as the seam for post-advance work. Moving focus to the new step is the common one: the pin flips synchronously, but the new step's DOM lands a tick later, so await `nextTick()` before reaching for the element (and give a heading or container focus target `tabindex="-1"`, since those are not focusable on their own).

```ts
if (await wizard.tryNext()) {
  await nextTick()
  heading.value?.focus()
}
```

### Custom valid or invalid handling

`tryNext()` is the shorthand for composing the active step's own submit with `next()`. When you want custom valid or invalid callbacks (a toast, an analytics ping, a different advance target), compose them directly:

```ts
const onNext = wizard.activeForm.handleSubmit(
  () => wizard.next(),
  (errors) => toast.error(`${errors.length} to fix before continuing.`)
)
```

`wizard.activeForm` is a live view of the current step, so this one `const`, captured once, is correct on every step: it validates whichever step is active when invoked and advances only on a clean pass.

> `wizard.handleSubmit`, `wizard.activeForm.handleSubmit`, and `wizard.tryNext()` are one verb at three reaches: submit every step, submit the active step, or submit-and-advance the active step. Reach for the wizard's when you want the whole thing, the active form's (or `tryNext`) when you want to gate one step.

## Error aggregation with `onError`

The optional `onError` callback receives every error the submission produced, flat, across every step:

```ts
const onFinish = wizard.handleSubmit(
  async (ctx) => {
    await api.checkout(ctx.values)
  },
  (errors) => {
    toast.error(`${errors.length} issue(s) before you can finish.`, {
      description: errors.map((e) => `${e.formKey}: ${e.message}`).join('\n'),
    })
  }
)
```

Each error carries `formKey`, `path`, `message`, and an optional `code`. Because `handleSubmit` validates the whole wizard, the list spans every failing step at once, not just the active one, plus any errors the callback set with `setErrors` and any activation failures (e.g., a form whose async `defaultValues` rejected). For wizard-wide error summaries that persist between submissions, drive them off [`wizard.allErrors`](/docs/multistep/aggregates#allerrors-for-wizard-wide-summaries) instead.

## `focusFirstError`

When a submission produces errors, the wizard jumps to the first failing form and invokes its `applyInvalidSubmitPolicy()` (focus / scroll per the form's own `onInvalidSubmit` configuration). The behavior is on by default; opt out by passing `focusFirstError: false` on the wizard:

```ts
const wizard = useWizard({
  steps: [shipping, payment, review],
  focusFirstError: false,
})
```

With the focus jump disabled, the wizard stays where it is and leaves navigation to the consumer's `onError` callback. Useful when you have built a custom error-summary panel that owns the click-to-jump behavior.

## `wizard.submitting` for re-entrance

`wizard.handleSubmit` guards against re-entrant calls: while a prior submission is still in flight (the `onSubmit` promise hasn't settled), subsequent calls dev-warn and resolve no-op. The `submitting` flag is the gate:

```vue
<template>
  <button :disabled="wizard.submitting" type="submit">
    {{ wizard.submitting ? 'Submitting…' : 'Finish' }}
  </button>
</template>
```

Disabling the button is belt-and-braces; the wizard refuses re-entry on its own. The flag also gates navigation: `wizard.next()`, `wizard.back()`, and `wizard.goTo()` all refuse while `submitting` is true so an in-flight submit can't be torn out from underneath itself.

## Degenerate inputs

- **Empty steps list.** `handleSubmit` dev-warns and resolves no-op. `onSubmit` and `onError` are never invoked.
- **Re-entrant submission.** The second call dev-warns and resolves no-op; the first call continues to settle.
- **No `Event` argument.** Imperative calls (`onFinish()` with no event) work the same as `<form @submit>`; the `preventDefault` step is skipped.

## Where to next

- [`useWizard`](/docs/multistep/use-wizard) for the construction signature and the full wizard handle.
- [Aggregates](/docs/multistep/aggregates) for `wizard.allValues` and `wizard.allErrors`, which mirror the data `ctx.values` carries.
- [Statuses](/docs/multistep/statuses) for the per-step `FormStatus` rollup that flips `submitted: true` when the callback succeeds.
- [Patterns](/docs/multistep/patterns) for branching flows and the gated-advance composition in context.

_Source: https://attaform.dev/docs/multistep/handle-submit_

---

# URL sync

> A wizard with no extra options reads its starting step from `?step=<key>` on the URL and writes the active step back as the user navigates. Reloads land on the same step, deep links render the right step on the first byte under SSR, and the URL stays shareable. To rename the param, scope it across wizards on the same page, or wire the state to non-URL storage, pass `restore` and `persist` callbacks.


## The default behavior

`useWizard` does URL sync out of the box. Construct a wizard with nothing but `steps`, and the wizard reads `?step=<key>` from the URL at construction and mirrors `currentStep` back to it on every navigation:

```ts
import { useForm, useWizard } from 'attaform'

const wizard = useWizard({
  steps: ['welcome', shipping, payment, 'final-review'],
})
```

- Landing on `/checkout?step=payment` boots the wizard with `currentStep === 'payment'`.
- `wizard.next()` and `wizard.goTo('shipping')` update the URL as the active step changes.
- Reloading the page lands on the same step.
- The URL is shareable: paste `/checkout?step=payment` into another tab and that tab opens on the payment step.

The default write uses `history.replaceState`, so a single back-button press leaves the wizard's host page rather than walking backward through every step the user visited. If you want push semantics (back button retreats one step), see [Pushing each navigation](#pushing-each-navigation) below.

## SSR hand-off

Under SSR (Nuxt or any framework wired through `createAttaform()`), the default restore reads the incoming request's `?step` from a server-side resolver provided by the integration, so the first byte rendered on the server matches what the URL asked for. The wizard exposes nothing extra here: with default `restore` and the Nuxt module installed, deep links render the right step on the first paint with no consumer wiring.

A bare-Vue SPA without the Nuxt integration still gets the client-side default: `window.location` is read on construction once the page hydrates, and the wizard navigates to the matching step before the user sees the first render.

## Disabling URL sync

Pass `false` to either side to opt out of the default. The two switches are independent:

```ts
const wizard = useWizard({
  steps: [shipping, payment, review],
  restore: false, // don't read the URL at construction
  persist: false, // don't write the URL on navigation
})
```

- `restore: false`. The wizard ignores the URL at construction and boots on `steps[0]`. Useful when the consumer drives initial step from a custom source (a Pinia store, a feature flag, a server-rendered prop) and doesn't want a stray `?step=` in the URL to override it.
- `persist: false`. Navigation never writes to the URL. The wizard's active step stays in memory only. Useful for embedded wizards inside a modal, a popover, or any context where the URL belongs to the surrounding page.
- Both `false`. The wizard is fully URL-blind: starts on `steps[0]`, leaves the URL untouched, never reads from it.

## Custom callbacks

The `restore` and `persist` options take callbacks for non-URL storage:

```ts
type WizardRestoreState = { readonly step?: string }
type WizardRestoreFn = () => WizardRestoreState | undefined
type WizardPersistFn = (state: WizardRestoreState) => void
```

A localStorage example:

```ts
const STORAGE_KEY = 'checkout:active-step'

const wizard = useWizard({
  steps: [shipping, payment, review],
  restore: () => {
    const step = localStorage.getItem(STORAGE_KEY)
    return step === null ? undefined : { step }
  },
  persist: ({ step }) => {
    if (step === undefined) return
    localStorage.setItem(STORAGE_KEY, step)
  },
})
```

The restore callback is invoked at construction and re-evaluated reactively (its tracked reads decide the dep set); the persist callback fires on every `currentStep` change, diffed to break the restore-persist loop. The wizard handles the loop break, so a persist write that triggers a restore re-read converges in one round.

## Renaming the param

The default `?step=<key>` works fine until two wizards land on the same page. Then the second wizard's writes overwrite the first's. Give each wizard its own param via custom callbacks:

```ts
import { useForm, useWizard } from 'attaform'

const checkout = useWizard({
  steps: [shipping, payment, review],
  restore: () => {
    const url = new URL(window.location.href)
    const step = url.searchParams.get('checkout-step')
    return step === null ? undefined : { step }
  },
  persist: ({ step }) => {
    const url = new URL(window.location.href)
    if (step === undefined) {
      url.searchParams.delete('checkout-step')
    } else {
      url.searchParams.set('checkout-step', step)
    }
    history.replaceState(history.state, '', url.toString())
  },
})

const support = useWizard({
  steps: [shipping, payment, review],
  restore: () => {
    const url = new URL(window.location.href)
    const step = url.searchParams.get('support-step')
    return step === null ? undefined : { step }
  },
  persist: ({ step }) => {
    const url = new URL(window.location.href)
    if (step === undefined) {
      url.searchParams.delete('support-step')
    } else {
      url.searchParams.set('support-step', step)
    }
    history.replaceState(history.state, '', url.toString())
  },
})
```

Each wizard owns its own search param; the two never collide.

## Pushing each navigation

The default `persist` uses `replaceState` so the browser's back button leaves the host page in one press. To get push semantics (back walks the visited steps), swap in a custom persist that calls `pushState`:

```ts
const wizard = useWizard({
  steps: [shipping, payment, review],
  persist: ({ step }) => {
    const url = new URL(window.location.href)
    if (step === undefined) {
      url.searchParams.delete('step')
    } else {
      url.searchParams.set('step', step)
    }
    history.pushState(history.state, '', url.toString())
  },
})
```

The matching restore (the default one) already listens to `popstate` and re-reads the URL, so the back button retreats one step at a time once persist pushes.

## Where to next

- [`useWizard`](/docs/multistep/use-wizard) for the construction signature and the wizard handle.
- [Patterns](/docs/multistep/patterns) for the per-form `persist` option that keeps each step's field values across reloads.
- [`injectWizard`](/docs/multistep/inject-wizard) for cross-component access to a wizard with a named `key` (a separate identifier from `?step=`).

_Source: https://attaform.dev/docs/multistep/url-sync_

---

# Patterns

> Each step of a wizard is a regular `useForm` call. The wizard is a thin orchestrator over the `steps` array. Linear flows, branching graphs, dynamic terminals, active-step persistence, and per-step undo all compose through the same primitives the rest of Attaform exposes, without special wizard knobs.


## Linear wizards

The default shape: a list of forms in reading order. `wizard.next()` advances and `wizard.back()` retreats; neither validates (navigation and submission are separate verbs). Out-of-bounds calls dev-warn and no-op.

```ts
import { useForm, useWizard } from 'attaform'
import { z } from 'zod'

const accountSchema = z.object({ email: z.email() })
const profileSchema = z.object({ name: z.string().min(1) })
const reviewSchema = z.object({ tos: z.literal(true) })

const account = useForm({ schema: accountSchema, key: 'signup-account' })
const profile = useForm({ schema: profileSchema, key: 'signup-profile' })
const review = useForm({ schema: reviewSchema, key: 'signup-review' })

const wizard = useWizard({ steps: [account, profile, review] })
```

To advance only when the active step is valid, reach for `wizard.tryNext()`. It validates the active step and advances on a clean pass, binding straight to the button:

```vue
<button v-if="wizard.canAdvance" @click="wizard.tryNext()">Next</button>
```

For custom valid or invalid handling, compose the active step's submit with `next()` instead. `wizard.activeForm` is a live view of the current step, so one `const` captured here stays correct on every step:

```ts
const onNext = wizard.activeForm.handleSubmit(() => wizard.next())
```

For a non-blocking flow (autosave, deferring the error waterfall to the final submit), wire the button to plain `wizard.next()` instead.

Mix in affordance steps (bare strings) wherever the flow benefits from a screen that presents rather than collects:

```ts
const wizard = useWizard({
  steps: ['welcome', account, profile, 'review-summary', review, 'congrats'],
})
```

See [Step slots](/docs/multistep/step-slots) for the affordance-slot story.

## Branching wizards

When the next step depends on a live value on an earlier form, use a function slot. The slot is a `(ctx) => Form | string | undefined` callback that re-evaluates reactively as its tracked reads change:

```ts
import { useForm, useWizard } from 'attaform'
import { z } from 'zod'

const accountSchema = z.object({ kind: z.enum(['user', 'organization']) })
const userProfileSchema = z.object({ name: z.string().min(1) })
const orgSchema = z.object({ orgName: z.string().min(1), seats: z.number().int().positive() })
const reviewSchema = z.object({ tos: z.literal(true) })

const account = useForm({ schema: accountSchema, key: 'signup-account' })
const userProfile = useForm({ schema: userProfileSchema, key: 'signup-user' })
const orgProfile = useForm({ schema: orgSchema, key: 'signup-org' })
const review = useForm({ schema: reviewSchema, key: 'signup-review' })

const wizard = useWizard({
  steps: [
    account,
    (ctx) =>
      ctx.forms['signup-account'].values.kind === 'organization' ? orgProfile : userProfile,
    review,
  ],
})
```

When the user picks `'organization'` on the account step, the function slot resolves to `orgProfile`. Toggling back to `'user'` swaps the resolved form. `wizard.steps`, `wizard.forms`, `wizard.statuses`, and the progress rail all follow along.

For typed reads, close over the original form ref instead of routing through `ctx.forms`:

```ts
const wizard = useWizard({
  steps: [
    account,
    () => (account.values.kind === 'organization' ? orgProfile : userProfile), // typed!
    review,
  ],
})
```

`account.values.kind` carries the Zod-derived `'user' | 'organization'` type through the predicate, where `ctx.forms['signup-account'].values.kind` reads as `unknown`. Both work at runtime; the closed-over ref keeps the IDE happy.

## Dynamic terminals

A function slot that returns `undefined` drops its position from the compiled list. Combine that with a terminal step to get a wizard that ends early on a live condition:

```ts
const accountSchema = z.object({ email: z.email(), willTakeSurvey: z.boolean() })
const surveySchema = z.object({ rating: z.number().int().min(1).max(5) })
const reviewSchema = z.object({ tos: z.literal(true) })

const account = useForm({ schema: accountSchema, key: 'signup-account' })
const survey = useForm({ schema: surveySchema, key: 'signup-survey' })
const review = useForm({ schema: reviewSchema, key: 'signup-review' })

const wizard = useWizard({
  steps: [account, () => (account.values.willTakeSurvey ? survey : undefined), review],
})
```

Users who decline the survey see two steps (`account`, `review`); users who opt in see three (`account`, `survey`, `review`). The function slot re-evaluates whenever `willTakeSurvey` flips, so a late toggle is respected on the next navigation. `wizard.count`, `wizard.isFinalStep`, and the progress rail recompute against the live list.

For heavier branching (a slot whose resolver is expensive enough that re-evaluating on every wizard mutation produces visible thrash), reach for [`lazy()`](/docs/multistep/step-slots#lazy-slots-lazy) instead.

## Manual jumps with `goTo`

`wizard.goTo(key)` skips the validation gate. Use it when the user explicitly clicked a rail item:

```vue
<button type="button" @click="wizard.goTo(step.key)">Jump to {{ step.key }}</button>
```

`wizard.handleSubmit` catches the upstream validation gaps that `goTo` lets through. Clicking Finish on a step the user jumped to without filling earlier forms validates everything, surfaces every error, and (with `focusFirstError: true`, the default) jumps the wizard back to the first failing step.

## Persisting the active step

What the wizard persists is the active step, via `?step=<key>` on the URL by default (see [URL sync](/docs/multistep/url-sync)). A refresh lands the user back on the step they were on, with the navigation cursor intact.

```ts
const account = useForm({ schema: accountSchema, key: 'signup-account' })
const profile = useForm({ schema: profileSchema, key: 'signup-profile' })
const review = useForm({ schema: reviewSchema, key: 'signup-review' })

const wizard = useWizard({ steps: [account, profile, review] })
```

## Per-step undo

Same composition: each step gets its own `history` chain.

```ts
const cargo = useForm({
  schema: cargoSchema,
  key: 'cargo',
  history: true, // unlimited undo / redo across the cargo step
})

const billing = useForm({
  schema: billingSchema,
  key: 'billing',
  history: { max: 25 }, // capped chain
})

const wizard = useWizard({ steps: [cargo, billing] })
```

A keyboard shortcut bound to the active step:

```vue
<script setup lang="ts">
  function onKeydown(event: KeyboardEvent) {
    if (!wizard.activeForm) return
    if (event.metaKey && event.key === 'z') {
      event.shiftKey ? wizard.activeForm.history.redo() : wizard.activeForm.history.undo()
    }
  }
</script>

<template>
  <div @keydown="onKeydown">
    <!-- step content -->
  </div>
</template>
```

`wizard.activeForm` is a live view of the current step's form, so undo / redo always dispatches to the active chain. It is no longer identity-equal to `wizard.forms[wizard.currentStep]`; reach for that record when you need a specific step's raw handle.

Each step's history is independent: undoing on the `cargo` step doesn't retreat changes the user made on `billing`. That matches the user's mental model: "undo what I just typed here," not "undo the entire flow."

## Cross-component access

Pass a `key` to `useWizard` so a deep-tree component (a floating finish button, a sticky progress rail) can reach the same wizard without prop-threading:

```ts
const wizard = useWizard({
  steps: [account, profile, review],
  key: 'signup',
})
```

A descendant component reaches it via `injectWizard('signup')`. See [`injectWizard`](/docs/multistep/inject-wizard) for the cross-component story (ambient resolution, keyed lookup, null-on-miss).

## Where to next

- [`useWizard`](/docs/multistep/use-wizard) for the navigation surface, `activeForm`, and `handleSubmit`.
- [Step slots](/docs/multistep/step-slots) for the four slot kinds (form, string, function, `lazy()`).
- [`injectWizard`](/docs/multistep/inject-wizard) for cross-component access to the wizard handle.
- [URL sync](/docs/multistep/url-sync) for wizard-level `?step=<key>` round-tripping.
- [Undo & redo](/docs/cross-cutting-state/undo-redo) for the per-form history chain.

_Source: https://attaform.dev/docs/multistep/patterns_

---

# SSR hydration: Nuxt

> The fastest path to server-rendered form values that don't flicker on hydrate. Install the module, write `useForm` normally, and the round-trip wires itself.


This page is code-only; SSR happens at the server runtime, and the docs site can't demo a hydration round-trip without bootstrapping a separate server. The setup is small enough to verify in your own Nuxt project; see [SSR hydration: bare Vue](/docs/server-and-ssr/ssr-bare-vue) for the equivalent without the Nuxt convenience.

## Nothing to wire

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

```vue
<script setup lang="ts">
  const form = useForm({ schema, key: 'signup' })
</script>
```

That's the whole setup. Values, errors, and field interaction flags (touched / focused / blurred / connected) survive the server → client round-trip through `nuxtApp.payload`. Need to peek? Open the rendered HTML and look for the Nuxt payload `<script>` block; `attaform` is a top-level key.

## What crosses the wire

| Surface                    | Round-trips? | Notes                                                                   |
| -------------------------- | ------------ | ----------------------------------------------------------------------- |
| `form.values`              | ✅           | Whole tree, including nested objects and arrays.                        |
| `errors`                   | ✅           | Every entry in the error map, keyed by path.                            |
| `fields`                   | ✅           | `touched` / `focused` / `blurred` / `connected` / `updatedAt` per path. |
| `blankPaths`               | ✅           | Numeric-blank state survives the boundary.                              |
| `history` chain            | ❌           | Each tab walks its own undo timeline.                                   |
| Validation in-flight state | ❌           | Re-runs locally on the client.                                          |

The client-side form is identical to the server one; no second round of validation kicks in unless the user interacts.

## Auto-imports

The Nuxt module auto-imports the form composables you reach for inside `<script setup>`: `useForm`, `useWizard`, `injectForm`, `injectWizard`, `fieldMeta`, `withMeta`, and `lazy`. No `import` statement needed:

```vue
<script setup lang="ts">
  const form = useForm({ schema, key: 'signup' })
</script>
```

Everything else stays an explicit import from `attaform`: the plugin (`createAttaform`), the custom-input composable (`useRegister`), the `unset` sentinel, and the `defaultDisplayState` reducer.

```vue
<script setup lang="ts">
  import { defaultDisplayState, unset, useRegister } from 'attaform'
</script>
```

Toggle the whole set with the module's `autoImports` option (default on); see [Installation](/docs/getting-started/installation#auto-imports) for the full list.

## App-wide defaults under Nuxt

The Nuxt module surfaces the same `AttaformDefaults` you'd pass to `createAttaform({ defaults })`:

```ts
export default defineNuxtConfig({
  modules: ['attaform/nuxt'],
  attaform: {
    defaults: {
      validateOn: 'change',
      debounceMs: 100,
      onInvalidSubmit: 'focus-first-error',
    },
  },
})
```

See [App-wide defaults](/docs/cross-cutting-state/app-defaults) for the full option list and merge semantics.

## Common issues

### "The form is empty on the client even though the server rendered values."

- Does the form's `key` match between server and client? Hard-code it as a string literal; `uuidv4()` or `Math.random()` produces a fresh key per render and breaks the round-trip lookup.
- Was the form created in `setup`? Forms created in `onMounted` or event handlers aren't in the SSR snapshot.

### "Field errors from the server disappear on first interaction."

By design. Any mutation re-runs validation, which can replace the errors. To keep server-provided errors around until the user dirties the field, gate the display on `form.fields.<path>.touched` or `form.meta.dirty`:

```vue
<small v-if="form.errors.email?.[0] && !form.fields.email.touched">
  {{ form.errors.email[0].message }}
</small>
```

### "Some fields look right, others don't."

Forms created in `onMounted` or event handlers aren't in the SSR snapshot. Create forms during `setup` so the server sees them.

## DevTools panel

The Nuxt module auto-wires the [Attaform DevTools panel](/docs/devtools-and-debugging/devtools-panel) into the Nuxt DevTools sidebar. The panel inspects every registered form including the SSR-rendered ones, useful for confirming the server-rendered shape matches your expectation before the user touches anything.

## Where to next

- [SSR hydration: bare Vue](/docs/server-and-ssr/ssr-bare-vue): the same round-trip without the Nuxt module, when you're not on Nuxt.
- [Performance](/docs/server-and-ssr/performance): what SSR hydration costs in practice.

_Source: https://attaform.dev/docs/server-and-ssr/ssr-nuxt_

---

# SSR hydration: bare Vue

> Two helper functions bridge the server → client boundary for `@vue/server-renderer` projects. Render the state on the server, escape it for an inline `<script>`, replay it before mount on the client.


This page is code-only; bare-Vue SSR runs on a Node server you provide. The end-to-end test at [`test/ssr-bare-vue/round-trip.test.ts`](https://github.com/attaform/Attaform/blob/main/test/ssr-bare-vue/round-trip.test.ts) exercises exactly the pattern below and is the fastest way to read it working.

## Server (`entry-server.ts`)

```ts
import { createSSRApp } from 'vue'
import { renderToString } from '@vue/server-renderer'
import { createAttaform, escapeForInlineScript, renderAttaformState } from 'attaform'
import App from './App.vue'

export async function render(url: string) {
  const app = createSSRApp(App)
  app.use(createAttaform())

  const html = await renderToString(app)

  const attaformState = renderAttaformState(app)
  // escapeForInlineScript keeps </script> and U+2028 / U+2029
  // separators out of the inline payload so it can't break out of
  // the <script> tag.
  const payload = escapeForInlineScript(JSON.stringify(attaformState))

  return { html, payload }
}
```

## Server template + injection

The HTML shipped to the browser carries two placeholders: one for the rendered app HTML, one for the inline payload:

```html
<body>
  <div id="app"><!--app-html--></div>
  <!--app-payload-->
  <script type="module" src="/src/entry-client.ts"></script>
</body>
```

The request handler swaps both in:

```ts
import fs from 'node:fs/promises'
import { render } from './entry-server'

app.use('*', async (req, res) => {
  const template = await fs.readFile('index.html', 'utf-8')
  const { html, payload } = await render(req.originalUrl)
  const final = template
    .replace('<!--app-html-->', html)
    .replace('<!--app-payload-->', `<script>window.__ATTAFORM_STATE__ = ${payload};</script>`)
  res.status(200).set({ 'Content-Type': 'text/html' }).end(final)
})
```

## Client (`entry-client.ts`)

```ts
import { createSSRApp } from 'vue'
import { createAttaform, hydrateAttaformState } from 'attaform'
import App from './App.vue'

const app = createSSRApp(App)
app.use(createAttaform())

// Replay the server's form state BEFORE mounting; forms read from
// the hydration bag during setup.
const serialized = (window as { __ATTAFORM_STATE__?: unknown }).__ATTAFORM_STATE__
if (serialized !== undefined) hydrateAttaformState(app, serialized)

app.mount('#app')
```

That's it. Every `useForm` call on the client resolves to the same values the server rendered.

## Why `escapeForInlineScript`

Embedding JSON in an inline `<script>` looks safe, until the JSON contains a literal `</script>` or a U+2028 / U+2029 line separator that breaks JavaScript string parsing. `escapeForInlineScript`:

- Replaces `</script>` with `<\/script>`.
- Escapes U+2028 / U+2029 as `
` / `
`.
- Leaves the JSON valid for `JSON.parse` on the client.

Skip it and a `notes` field containing `</script>` would close the inline tag mid-payload, breaking the page. Defense in depth: the escape runs unconditionally, even when the data "couldn't" contain those bytes.

## What crosses the wire

Same surfaces as the [Nuxt path](/docs/server-and-ssr/ssr-nuxt):

- `form.values`: whole tree, including nested objects and arrays.
- `errors`: every entry in the error map, keyed by path.
- `fields`: `touched` / `focused` / `blurred` / `connected` / `updatedAt` per path.
- `blankPaths`: numeric-blank state survives the boundary.

NOT on the wire:

- History chain (each session walks its own undo timeline).
- Validation in-flight state (re-runs locally on hydrate).

## Vite plugin

For bare Vue + Vite, install `attaform/vite` to ensure `v-register` bindings compile correctly under SSR:

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { attaform } from 'attaform/vite'

export default defineConfig({
  plugins: [vue(), attaform()],
})
```

The plugin rewrites `v-register` directives to a SSR-correct form so the directive's element-tracking machinery matches between server and client renders. Without it, the directive can emit hydration mismatches on first paint.

## Common issues

### "The form is empty on the client even though the server rendered values."

- Did you call `hydrateAttaformState(app, payload)` before `app.mount(...)`? It has to land before `setup` runs.
- Does the form's `key` match between server and client? Hard-code it as a string literal. `uuidv4()` or `Math.random()` produces a fresh key per render and breaks the match.

### "Field errors from the server disappear on first interaction."

By design. Any mutation re-runs validation. Gate the display on `form.fields.<path>.touched` or `form.meta.dirty` to keep server-provided errors visible until the user touches the field.

### "Hydration mismatch on a `<input v-register>` element."

Install the `attaform/vite` plugin (see above). The runtime renders consistent attributes on server and client, but the directive's element-tracking emits identity markers that the compiler needs help to align between SSR and hydration phases.

## Where to next

- [SSR hydration: Nuxt](/docs/server-and-ssr/ssr-nuxt): the same round-trip with zero wiring.
- [Performance](/docs/server-and-ssr/performance): what hydration costs at scale.
- [Server-side errors](/docs/submitting/server-side-errors): turn server 4xx responses into reactive form errors with `form.setErrors`.

_Source: https://attaform.dev/docs/server-and-ssr/ssr-bare-vue_

---

# Performance

> Notes on the hot paths and what to look at if a form starts feeling slow. Real-browser numbers, sizing guidance, and the array-helper gotcha worth knowing.


This page is reference material; no demo. CI runs the benchmark suite under [`bench/`](https://github.com/attaform/Attaform/tree/main/bench) on every PR, so the numbers below come from a known-good environment and ride alongside the code.

For how Attaform compares across the Vue form-library field on the same scenarios, in a real browser, see [Benchmarks](/docs/comparison/benchmarks).

## Measured numbers

Real-browser numbers from `pnpm bench`, single-threaded on contemporary hardware. Your machine will land elsewhere on the number line; the orders of magnitude won't.

| Operation                                                     | Cost    |
| ------------------------------------------------------------- | ------- |
| Single-field keystroke, 100-leaf form                         | 6 µs    |
| Single-field keystroke, 500-leaf form                         | 30 µs   |
| Validation overhead per keystroke (`validateOn: 'change'`)    | 5 µs    |
| Submit lifecycle (validate → submit → setErrors)              | 3.4 µs  |
| Path canonicalization (cache hit)                             | 60 ns   |
| Sensitive-name check (common pattern, early hit)              | 70 ns   |
| Persistence write, `'local'` / `'session'` (100-leaf payload) | 2.8 µs  |
| Persistence write, `'indexeddb'` (100-leaf payload)           | 62 µs   |
| Debounced-writer schedule (steady-state typing)               | 0.18 µs |
| Discriminated union, write into active variant                | 19 µs   |
| Discriminated union, cross-variant flip                       | 25 µs   |
| Reset, 100-leaf object form                                   | 678 µs  |
| Field-array append, 100-item                                  | 2.5 ms  |
| Field-array append, 1000-item                                 | 9 ms    |
| Field-array swap on 500-item                                  | 3.9 ms  |

A 60 fps frame is **16.7 ms**. Single-keystroke work clears the budget by three orders of magnitude on a 100-leaf form and by two on a 500-leaf form; Vue's render gets the rest of the frame to itself.

## Hot-path characteristics

- **Keystrokes**: the `register` → form-state path runs against a per-PR threshold; see [`bench/keystroke.bench.ts`](https://github.com/attaform/Attaform/blob/main/bench/keystroke.bench.ts) for the measured scenarios (100-leaf and 500-leaf forms, single-leaf mutation).
- **`form.meta.dirty`**: iterates the tracked leaves with no per-leaf parse cost.
- **Path resolution**: dotted-string paths are LRU-cached (128 entries), so repeat canonicalization reduces to a map lookup.

Sub-500-leaf forms don't surface in profiling.

## Sizing guidance

| Scale              | Guidance                                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ≤ 500 leaves       | Default. No tuning needed.                                                                                                                                               |
| 500 – 5,000 leaves | Still fine. Watch out for templates that render every leaf's `form.fields.<path>.dirty` in a hot scope.                                                                  |
| 5,000+ leaves      | Consider splitting into sub-forms with distinct `key`s, composed via [`injectForm`](/docs/cross-cutting-state/inject-form) or [`useWizard`](/docs/multistep/use-wizard). |

## Array helpers are O(N)

`append` / `prepend` / `insert` / `remove` / `swap` / `move` all copy the target array before mutating. That's cheap in the common case (dozens of items), fine at hundreds, but **quadratic if you loop `append` to seed a large list**. For a large seed, assign the whole array in one shot:

```ts
form.setValue('items', preBuiltArray) // O(N): one allocation
```

For incremental population (the user appends one item at a time), per-append cost is the only thing that matters and the amortized total is linear over the user's interactions.

## Keying `v-for` rows

Use a stable per-row key: either an ID carried on the data or a client-generated `crypto.randomUUID()` stored when you append. Keying by index re-renders more than necessary when rows move and flickers focus / scroll state on reordered rows.

```vue
<!-- Good: stable key follows the item -->
<div v-for="item in form.values.items" :key="item.id">…</div>

<!-- Avoid for reorderable lists: index changes when items move -->
<div v-for="(_, i) in form.values.items" :key="i">…</div>
```

The index pattern is fine for append-only or short-lived lists; reach for stable IDs when the list can reorder.

## Discriminated unions vs. plain unions

Discriminated unions (`z.discriminatedUnion`) walk only the active branch. Plain unions (`z.union`) walk every branch unconditionally; use a DU when you have a shared key. The cost difference grows with the number of branches; for a 5-branch plain union, validation does 5x the work of the equivalent DU.

## `form.meta.dirty` in hot templates

`form.meta.dirty` is a whole-form aggregate; it invalidates whenever any tracked leaf's `updatedAt` ticks. If you render it in a hot path (a header that re-renders on every keystroke), derive a more specific predicate instead:

```ts
// Faster than gating on the whole-form form.meta.dirty:
const isEmailDirty = computed(() => form.fields.email.dirty)
```

The pattern: read at the smallest granularity that gives you the answer you need.

## Reset cost

`reset()` is sub-millisecond on a 100-leaf form (~680 µs in the suite; see the table above). `resetField(path)` scales with the subtree; prefer it for localized reversions.

## Benching your own form

Clone the repo and drop a bench in `bench/`:

```ts
import { bench, describe } from 'vitest'
import { z } from 'zod'
// import your form setup

describe('my form: typical interaction', () => {
  bench('the operation I care about', () => {
    // ...
  })
})
```

Run with `pnpm bench`. The regression gate only fires on benches that follow the `old: / new:` pairing convention; informational benches run without gating.

## Peer-dep coverage

Per-PR CI runs the suite on the current Node LTS (22.x today; the `engines.node` floor is Node 22) against the devDep-pinned peer versions. A weekly workflow sweeps Vue 3.5 through 3.6, Vite 5 / 6, Nuxt 3.16 through Nuxt 4. Jobs fail independently; versions not yet released surface as failed cells without blocking the main CI.

## Where to next

- [Benchmarks](/docs/comparison/benchmarks): the same scenarios run across the Vue form-library field, with bundle size, supply-chain scores, and per-scenario runtime tables.
- [Field-array mutations](/docs/writing-and-mutating/field-arrays): the O(N) characteristics in full, including amortized analysis.
- [How values are stored](/docs/schemas/storage-shape): the slim write shape that keeps reads fast.
- [SSR hydration: Nuxt](/docs/server-and-ssr/ssr-nuxt): hydration costs depend on form size; pair this page with the SSR pages when sizing.

_Source: https://attaform.dev/docs/server-and-ssr/performance_

---

# The Attaform DevTools panel

> A first-class native tab in the Nuxt DevTools sidebar. Every form's value, errors, aggregates, and event timeline, with an editable JSON tree for the values.


This page is code-only; the panel lives in your browser's Nuxt DevTools overlay, not inside the docs site. Open any Nuxt-powered Attaform consumer in dev (`Shift + Option + D` opens the overlay) and pick **Attaform** in the sidebar to see it.

## Installing

The integration is automatic; adding `attaform/nuxt` to your Nuxt config wires the tab:

```ts
// nuxt.config.ts: no devtools-specific config needed
export default defineNuxtConfig({
  modules: ['attaform/nuxt'],
  devtools: { enabled: true },
})
```

No peer dependency to add, no extension to install, no Vite plugin to configure. Open the Nuxt DevTools overlay (`Shift + Option + D` or click the Nuxt logo in the bottom corner) and select **Attaform** from the sidebar.

The tab is dev-only; production builds skip the route injection and the `@nuxt/devtools-kit` import entirely. Nothing ships in production.

## What you see

### Form list

One entry per registered form, keyed by the form's `key`. Click a form to inspect it.

### Form value

The current `form.values` as an interactive JSON tree. **Editable from the panel:** your edit flows through `setValueAtPath` and drives the whole reactive pipeline (validation, history). The panel writes back into the same store the form reads from, so a value edited in DevTools is indistinguishable from one typed into an input.

Values render verbatim. The panel is dev-only, so it doesn't mask passwords / tokens / secrets; debugging a credential flow typically needs the actual value. Close the panel before a screen share if a value would be sensitive on camera, the same hygiene as the browser's own DevTools console.

### Schema Errors / User Errors

The error map keyed by path, split by source:

- **Schema Errors**: what the validator (Zod adapter) produced. Cleared by `reset()` / `handleSubmit` success.
- **User Errors**: the manual error layer you wrote via `setErrors` (server errors included). Persists across revalidation and successful submits.

Splitting them tells you instantly whether validation or your application code emitted each error.

### Aggregates

The reactive bundle:

- `submitting`
- `submissionAttempts`
- `submitError`
- `activeValidations`

Useful for confirming your loading-state wiring is reading the right reactive thing.

### Timeline

A scrollable log of recent events. Each entry shows a timestamp, an event type, and the form key, with the form value at the moment of fire available on click.

| Event            | Fires on                                                                 |
| ---------------- | ------------------------------------------------------------------------ |
| `form.change`    | Every mutation: register inputs, `setValue`, array helpers, undo / redo. |
| `submit.success` | A submit handler's `onSubmit` callback resolves.                         |
| `reset`          | `reset()` completes.                                                     |

Capacity is capped at 200 events per session; older entries fall off the back. Hit **clear** to wipe the log mid-debug.

## Sensitive data and the panel

The panel renders form values raw. DevTools is a dev-only surface, and redacting across every place a value surfaces (panels, logs, network tabs, breakpoints, source maps) is impractical security theater, not a real safeguard. For production-data spelunking on a sensitive surface, use a non-prod environment with synthetic data instead.

## What's coming

- **Field flags** (touched / focused / blurred) in the inspector: values + errors are surfaced today, UI interaction state isn't.
- **History stack visualization.** Undo / redo snapshots show on the timeline via `form.change` entries; the stack itself isn't a separate node yet.

## Caveats

- **Panel edits bypass your component bindings.** Fine for poking at state during debugging; don't rely on the path mirroring production interaction exactly.
- **Multi-app setups.** The Nuxt overlay panel reads from the most recent `createAttaform()` install; micro-frontend setups with parallel apps will only see one app's forms in the Nuxt panel. Reach for [Vue DevTools integration](/docs/devtools-and-debugging/vue-devtools) when you need per-app inspection.
- **Screen-share hygiene.** The panel renders raw values. Close it before screen-sharing, the same way you'd close the browser DevTools console.

## Where to next

- [Vue DevTools integration](/docs/devtools-and-debugging/vue-devtools): the alternative for Vite / bare-Vue projects, or as a complement on Nuxt.
- [Troubleshooting](/docs/devtools-and-debugging/troubleshooting): what the panel surfaces, in narrative form.

_Source: https://attaform.dev/docs/devtools-and-debugging/devtools-panel_

---

# Vue DevTools integration

> For Vite and bare-Vue projects, install one optional peer dep and the Vue DevTools extension shows an **Attaform** inspector + timeline alongside Pinia / Vue Router / components.


This page is code-only; the Vue DevTools surface lives in your browser's extension panel, not inside the docs site. Install the extension, open any Vite / bare-Vue Attaform consumer in dev, and pick **Attaform** in the DevTools sidebar to see it.

## Installing

The extension is the same one Vue itself uses; install it once per browser:

```bash
# Chrome / Edge / Firefox web stores
# https://devtools.vuejs.org
```

Then add the peer dep to the project (dev-only):

```bash
npm install -D @vue/devtools-api
```

Attaform auto-wires the inspector + timeline when the dep is present at runtime:

```ts
// main.ts
import { createApp } from 'vue'
import { createAttaform } from 'attaform'
import App from './App.vue'

createApp(App)
  .use(createAttaform()) // devtools: true by default
  .mount('#app')
```

If the peer dep isn't installed at runtime, nothing breaks; the inspector simply doesn't register, and the form library works as usual. Treating the integration as optional means a freshly-cloned project doesn't fail to start just because `@vue/devtools-api` isn't on disk.

## Production builds

Gate the wiring off explicitly in production:

```ts
const attaform = import.meta.env.PROD ? createAttaform({ devtools: false }) : createAttaform()
```

For a zero-overhead production build:

1. Pass `{ devtools: false }` to `createAttaform`.
2. Keep `@vue/devtools-api` in `devDependencies`, not `dependencies`.

The wire-up is code-split, so the chunk isn't pulled in when `devtools: false`; production bundles stay clean even without dropping the peer dep.

## What you see

The Vue DevTools panel surfaces the same data as the [Nuxt panel](/docs/devtools-and-debugging/devtools-panel): form list, editable JSON value tree, schema/user error split, aggregates, and the event timeline. Both surfaces render values raw; DevTools is a dev-only surface, so the sensitive-name list gates persistence, not display.

| Surface              | What it is                                                              |
| -------------------- | ----------------------------------------------------------------------- |
| Form list            | One entry per registered form, keyed by `form.key`.                     |
| Form value           | Editable JSON tree; writes flow through the same store-mutation path.   |
| Schema / User errors | Split by source.                                                        |
| Aggregates           | `submitting`, `submissionAttempts`, `submitError`, `activeValidations`. |
| Timeline             | `form.change` / `submit.success` / `reset` events with value snapshots. |

The only difference is location: instead of the Nuxt DevTools overlay's sidebar, the panel appears in the Vue DevTools' inspector list under **Attaform**.

## Multi-app setups

Each Vue app registers its own inspector entry in the extension. Micro-frontend setups with parallel Vue apps each get their own **Attaform** node; the extension reads from `getCurrentApp()` per panel switch.

This is the practical advantage over the Nuxt panel for multi-app monorepos: pick the app in the DevTools' app-selector dropdown, the Attaform panel re-binds to that app's forms.

## When to pick which

- **Nuxt project, single app** → [Nuxt DevTools panel](/docs/devtools-and-debugging/devtools-panel). Zero install, dev-only by default.
- **Vite / bare-Vue project** → Vue DevTools extension (this page). One peer dep, extension already useful for unrelated Vue debugging.
- **Multi-app setup (micro-frontend, embedded apps)** → Vue DevTools. Per-app inspection.
- **Both surfaces in one Nuxt project** → both work simultaneously. The Nuxt overlay surfaces the latest `createAttaform` install; the extension surfaces every app.

## Caveats

- **Extension version mismatch.** The Vue DevTools extension and `@vue/devtools-api` evolve in tandem; keep both reasonably current. An outdated extension may not surface newer inspector node types; an outdated peer dep may emit events the extension doesn't render.
- **Privacy across reloads.** The timeline doesn't persist across reloads; reloading the page wipes the visible history. Persistent debug requires copying events out manually.
- **Screen-share hygiene.** Values render raw. Same advice as the browser DevTools console: close before sharing the screen.

## Where to next

- [The Attaform DevTools panel](/docs/devtools-and-debugging/devtools-panel): the Nuxt-native alternative, same data surface.
- [Troubleshooting](/docs/devtools-and-debugging/troubleshooting): what to look for in the panels when forms misbehave.

_Source: https://attaform.dev/docs/devtools-and-debugging/vue-devtools_

---

# Troubleshooting

> Symptom first, fix second. The most common stumbling blocks readers hit in the first month.

## "My field doesn't validate"

Three independent causes:

- **The schema doesn't include the field.** A `z.string().optional()` wrapper without an inner refinement accepts everything. Verify the schema.
- **You're in `strict: false` and watching `validate()`.** Lax mode strips refinements during default-values derivation so the form mounts with empty values without failing; refinements re-apply on submit. Drop the `strict: false` opt-out if you want `validate()` to fire refinements immediately.
- **The path doesn't match the schema.** `'items.0.name'` and `['items', 0, 'name']` canonicalize to the same path. But `['items', '0', 'name']` (string `'0'`) does NOT; emit numbers when the position is an array index.

## "`register('email')` returns a `never`-typed value"

The schema generic couldn't be inferred. Two likely causes:

- Your schema is typed as bare `ZodObject` without its concrete shape. Use the literal (`z.object({ email: z.string() })`) or give the variable a precise type.
- You imported `useAbstractForm` from `attaform/abstract` and passed a Zod schema without wrapping it in an adapter. `useAbstractForm` expects an `AbstractSchema`; for a Zod schema, import `useForm` from `attaform` (or `attaform/zod`), which wraps it for you.

## "`handleSubmit` doesn't run when I submit the form"

`form.handleSubmit(onSubmit)` returns the **handler function**, not a Promise. Bind the returned value:

```vue
<script setup lang="ts">
  const form = useForm({ schema })
  const onSubmit = form.handleSubmit(async (values) => {
    await api.signup(values)
  })
</script>

<template>
  <form @submit="onSubmit">...</form>
</template>
```

## "v-register on my component does nothing"

`<MyComponent v-register="...">` works only when the component's rendered root element is one Vue's directive can bind: `<input>`, `<textarea>`, or `<select>`. For components whose root is a `<div>` / `<label>` / styled wrapper, the directive skips listener attachment to avoid the bubbled-write bug.

The fix: call `useRegister()` in the child's setup and re-bind `v-register` onto an inner native element:

```vue
<!-- StyledInput.vue -->
<script setup lang="ts">
  import { useRegister } from 'attaform'
  const rv = useRegister()
</script>

<template>
  <div class="wrapper">
    <input v-register="rv" />
  </div>
</template>
```

The dev-mode console warning `v-register on <div> is a no-op …` points here.

## "Console warns that a `:value` / `:checked` is redundant beside v-register"

`v-register` already drives the field's value, so a co-located `:value` / `v-model` (text or `<select>`), `:checked` (checkbox or radio), or `:selected` (`<option>`) is redundant, and the two can fight over the DOM. Drop the extra binding and keep `v-register` alone:

```vue
<!-- Before -->
<input v-register="form.register('email')" :value="form.values.email" />
<!-- After -->
<input v-register="form.register('email')" />
```

A `:value` that gives a radio or an `<option>` its identity is expected and never flagged. The warning fires in the dev console for every app, and at build time (including CI) when you run Attaform's [Vite or Nuxt plugin](/docs/server-and-ssr/ssr-bare-vue). See [Let v-register own the value](/docs/binding-inputs/v-register#let-v-register-own-the-value) for the full rundown.

## "Submit fails with 'No value supplied' on a field the user can leave blank"

The path is in the form's `blankPaths` set and bound to a required schema. Three resolutions:

- **The field is genuinely optional.** Wrap the schema: `z.string().optional()`, `z.number().nullable()`, or `z.string().default('')`.
- **The field is required but `''` should count as "filled".** Supply an explicit default: `defaultValues: { email: '' }`. Attaform reads this as "empty string is intentional" and skips the auto-mark for that leaf.
- **Attaform should treat a blank field as "user didn't fill it."** Working as intended; the synthesized error (`code: 'atta:no-value-supplied'`) prevents silently submitting `0` / `''` / `false` for an unfilled required field.

## "Hydration mismatch after SSR"

Three usual suspects:

- **Did you call `hydrateAttaformState(app, payload)` before `app.mount(...)`?** It has to land before setup runs. Nuxt does this automatically.
- **Non-JSON-safe value in the form?** `Date`, `Map`, `Set`, `BigInt`, and circular refs don't survive `JSON.stringify`. Coerce at the form boundary (`z.date().transform((d) => d.toISOString())`) or use Nuxt's `devalue`-based payload (automatic under Nuxt).
- **`escapeForInlineScript` missing on the bare-Vue side?** A form value containing `</script>` breaks the inline payload. Wrap `JSON.stringify(payload)` in `escapeForInlineScript`. Not required under Nuxt.

## Where to next

- [The form](/docs/reading-the-form/the-form): the full reactive surface.
- [`errors`](/docs/reading-the-form/errors): per-path error reads.

_Source: https://attaform.dev/docs/devtools-and-debugging/troubleshooting_

---

# Types reference

> Every public type Attaform exports, grouped by purpose. Inference handles the common cases; these are for advanced wiring (custom adapters, deeply nested generic helpers, type-safe consumer libraries).


This page is reference material, alphabetical-ish by purpose. Most consumers never reach for these directly; the [Inference-first DX](/docs/schemas/contract) doctrine means `useForm` + a schema gives you autocomplete on every reactive surface without naming the types.

## Form configuration

| Type                                | Source                  | Purpose                                                                                   |
| ----------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------- |
| `UseFormConfiguration<Form>`        | runtime/types/types-api | The options bag passed to `useForm`.                                                      |
| `UseFormReturnType<Form, GetValue>` | runtime/types/types-api | The whole reactive return: values, fields, errors, meta, methods.                         |
| `AttaformPluginOptions`             | runtime/core/plugin     | Options for `createAttaform({ defaults, devtools })`.                                     |
| `AttaformDefaults`                  | runtime/types/types-api | The fields settable via `createAttaform({ defaults })`.                                   |
| `HistoryConfig`                     | runtime/types/types-api | `useForm({ history })` shape.                                                             |
| `OnInvalidSubmitPolicy`             | runtime/types/types-api | `'none'` \| `'focus-first-error'` \| `'scroll-to-first-error'` \| `'both'`.               |
| `ValidateOn` / `ValidateOnConfig`   | runtime/types/types-api | `validateOn` field and its discriminated config.                                          |
| `DisplayState` / `GetDisplayState`  | runtime/types/types-api | The display-state verdict (`idle` \| `pending` \| `error` \| `success`) and its resolver. |

## Reactive surfaces

| Type                            | Source                  | Purpose                                                   |
| ------------------------------- | ----------------------- | --------------------------------------------------------- |
| `FieldState<Value>`             | runtime/types/types-api | The 31-property per-leaf reactive bundle.                 |
| `FieldStateMap<Form>` / `Entry` | runtime/types/types-api | The proxy shape exposing `form.fields`.                   |
| `FormMeta<Form>`                | runtime/types/types-api | Form-level aggregates over every field's state.           |
| `FormErrorsSurface<Form>`       | runtime/types/types-api | The proxy shape exposing `form.errors`.                   |
| `FormErrorRecord`               | runtime/types/types-api | The per-path error array shape.                           |
| `ErrorsProxyShape<Form>`        | runtime/types/types-api | Type-level view of the errors proxy for advanced helpers. |
| `WriteMeta`                     | runtime/types/types-api | Metadata attached to a mutation (source, batch flags).    |

## Validation

| Type                                                  | Source                  | Purpose                                                                                                                                                                                |
| ----------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ValidationError`                                     | runtime/types/types-api | The error shape (`{ path, message, code, formKey, data? }`).                                                                                                                           |
| `ErrorInput`                                          | runtime/types/types-api | What `form.setErrors` accepts: an `Error` or `{ message?, path?, code?, data? }`. `formKey` is also accepted but ignored (the form stamps its own), so `ValidationError` is a subtype. |
| `Json`                                                | runtime/types/types-api | JSON-serialisable value; the type of the optional `data` payload.                                                                                                                      |
| `ValidationResponse<Form>`                            | runtime/types/types-api | Discriminated success-or-failure validation result with parsed data.                                                                                                                   |
| `ValidationResponseWithoutValue<Form>`                | runtime/types/types-api | Same shape minus the `data` payload (used by `validateAsync`).                                                                                                                         |
| `ReactiveValidationStatus<Form>`                      | runtime/types/types-api | Discriminated pending-vs-settled reactive validation status.                                                                                                                           |
| `PendingValidationStatus` / `SettledValidationStatus` | runtime/types/types-api | The two branches of `ReactiveValidationStatus`.                                                                                                                                        |
| `HandleSubmit` / `OnSubmit` / `OnError`               | runtime/types/types-api | The `handleSubmit` callback signatures.                                                                                                                                                |
| `SubmitHandler<Form>`                                 | runtime/types/types-api | Generic handler type for typed user submit functions.                                                                                                                                  |

## Schema contract

| Type                             | Source                  | Purpose                                                          |
| -------------------------------- | ----------------------- | ---------------------------------------------------------------- |
| `AbstractSchema<Form, GetValue>` | runtime/types/types-api | The 12-method + 2-optional contract custom adapters implement.   |
| `DefaultValuesResponse<Form>`    | runtime/types/types-api | What `getDefaultValues` returns.                                 |
| `SlimPrimitiveKind`              | runtime/types/types-api | `'string'` \| `'number'` \| … (typeof-style kinds).              |
| `SlimRuntimeOf<T>`               | runtime/types/types-api | Type-level helper to compute the slim primitive set for a type.  |
| `FieldMetaPayload`               | runtime/types/types-api | Schema-attached metadata: label, description, placeholder, meta. |

## Path types

| Type                           | Source                   | Purpose                                                  |
| ------------------------------ | ------------------------ | -------------------------------------------------------- |
| `FlatPath<Form>`               | runtime/types/types-core | Every reachable dotted path through the form.            |
| `PartialFlatPath<Form>`        | runtime/types/types-core | Same but allowing partial-prefix paths.                  |
| `ArrayPath<Form>`              | runtime/types/types-core | Every reachable path whose value is an array.            |
| `JoinSegments<Segments>`       | runtime/types/types-core | Type-level join of a segment tuple into a dotted string. |
| `Path` / `PathKey` / `Segment` | runtime/core/paths       | Canonicalized runtime path representation.               |

## Shape helpers

| Type                                                              | Source                   | Purpose                                                          |
| ----------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------- |
| `GenericForm`                                                     | runtime/types/types-core | The most-permissive form shape; used in generics that constrain. |
| `DeepPartial<T>`                                                  | runtime/types/types-core | Every leaf made optional, recursively.                           |
| `DefaultValuesInput<Schema>` / `DefaultValuesShape<Form>`         | runtime/types/types-core | The `defaultValues` argument shape vs. the resolved tree.        |
| `WriteShape<Schema>`                                              | runtime/types/types-core | The shape `setValue` accepts (`z.input`-equivalent).             |
| `NestedReadType<T, P>` / `NestedType<T, P>`                       | runtime/types/types-core | Walk a type to the value at a path.                              |
| `LiftedValueShape<T>`                                             | runtime/types/types-core | Helper for variant-memory and discriminated-union plumbing.      |
| `ArrayItem<T>`                                                    | runtime/types/types-core | Element type of an array.                                        |
| `IsTuple<T>` / `IsUnion<T>` / `KeyofUnion<T>` / `ValueOfUnion<T>` | runtime/types/types-core | Type-level predicates and unions over generic values.            |
| `Primitive`                                                       | runtime/types/types-core | The base primitive set.                                          |

## Binding

| Type                                              | Source                           | Purpose                                                          |
| ------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------- |
| `RegisterDirective`                               | runtime/types/types-api          | The `v-register` directive type.                                 |
| `RegisterValue` / `RegisterOptions`               | runtime/types/types-api          | The value the directive accepts; the per-register options shape. |
| `RegisterFlatPath<Form>`                          | runtime/types/types-api          | Paths bindable through `register`.                               |
| `RegisterTextModifier` / `RegisterSelectModifier` | runtime/types/types-api          | The `.lazy` / `.trim` / `.number` modifier types.                |
| `RegisterTransform<V>`                            | runtime/types/types-api          | Custom DOM ↔ value transform shape.                              |
| `CustomDirectiveRegisterAssignerFn`               | runtime/types/types-api          | The `assignKey` custom-assigner signature.                       |
| `UseRegisterReturn<V>`                            | runtime/composables/use-register | What `useRegister<V>()` returns.                                 |

## Set / mutate

| Type                     | Source                  | Purpose                                                      |
| ------------------------ | ----------------------- | ------------------------------------------------------------ |
| `SetValuePayload<Form>`  | runtime/types/types-api | Whole-form merge payload shape.                              |
| `SetValueCallback<Form>` | runtime/types/types-api | The `(prev) => next` callback signature.                     |
| `MetaTrackerValue`       | runtime/types/types-api | Internal "I'm mutating" flag exposed for advanced consumers. |
| `Unset`                  | runtime/core/unset      | The `unset` sentinel's brand type.                           |

## SSR payload

| Type                      | Source                 | Purpose                         |
| ------------------------- | ---------------------- | ------------------------------- |
| `SerializedAttaformState` | runtime/core/serialize | The SSR payload shape.          |
| `SerializedFormData`      | runtime/core/registry  | Single form's serialized state. |

## Wizard

| Type                                         | Source                     | Purpose                                                 |
| -------------------------------------------- | -------------------------- | ------------------------------------------------------- |
| `UseWizardReturnType<Forms>`                 | runtime/types/types-wizard | The whole wizard return: current, statuses, navigation. |
| `WizardOptions<Forms>`                       | runtime/types/types-wizard | The options bag.                                        |
| `AnyForm` / `FormKeyOf<F>` / `KeysOf<Forms>` | runtime/types/types-wizard | Helpers for typing forms passed to `useWizard`.         |
| `WizardNavOptions`                           | runtime/types/types-wizard | Options forwarded to `next` / `back` / `goTo`.          |

## DevTools

| Type                     | Source                       | Purpose                                               |
| ------------------------ | ---------------------------- | ----------------------------------------------------- |
| `AttaformDevtoolsBridge` | runtime/core/devtools-shared | The window-bridge contract the Nuxt overlay consumes. |

## Coercion

| Type                                                    | Source                  | Purpose                            |
| ------------------------------------------------------- | ----------------------- | ---------------------------------- |
| `CoercionEntry` / `CoercionRegistry` / `CoercionResult` | runtime/types/types-api | The schema-driven coercion shapes. |

## Internal-only (not for direct consumption)

These types ride on internal helpers and are exported for advanced custom-adapter authors. The [Inference-first DX](/docs/schemas/contract) doctrine means everyday consumers never need them:

- `StorageLeaf` / `StorageShape`: the slim-write-shape internal representations the runtime walks.
- `PartialFlatPath<Form>`: used by the path-prefix matchers inside the runtime.
- `LiftedValueShape<T>`: variant-memory plumbing.

Treat them as appendix items: stable enough to reference, but the public-facing surfaces (`UseFormReturnType`, `FieldState`, `ValidationError`) are what consumer code should depend on.

## Where to next

- [The schema contract](/docs/schemas/contract): the high-level model these types implement.
- [`AbstractSchema`](/docs/schemas/abstract-schema): when you need the contract for a non-Zod schema library.
- [Entry-point reference](/docs/reference/entry-points): which subpath each type ships from.

_Source: https://attaform.dev/docs/reference/types_

---

# Errors reference

> Every Attaform-emitted error class with the failure mode it represents, plus the small set of stable `code` identifiers for `ValidationError` entries Attaform produces.


This page is reference material. Two surfaces: throw-class errors (caught with `instanceof`) and `ValidationError.code` strings (matched in template / handler logic). Both follow the `atta:` prefix convention for Attaform-emitted entries; consumer codes use whatever prefix you pick (`api:`, `auth:`, `myapp:`).

## Catching errors polymorphically

Every Attaform-emitted throw extends `AttaformError`, so a single polymorphic catch works:

```ts
import { AttaformError } from 'attaform'

try {
  // useForm setup, register call, etc.
} catch (err) {
  if (err instanceof AttaformError) {
    // It's one of ours; log and handle.
    console.error('[attaform]', err.name, err.message)
  } else {
    throw err
  }
}
```

Branch on the subclass for targeted handling:

```ts
import { AttaformError, OutsideSetupError } from 'attaform'

try {
  // …
} catch (err) {
  if (err instanceof OutsideSetupError) {
    // Move the call into a Vue setup function
  } else if (err instanceof AttaformError) {
    // Catch-all
  } else {
    throw err
  }
}
```

## Error classes

### `AttaformError`

Base class; never thrown directly, only via subclasses. Provides the polymorphic-catch entry point.

```ts
class AttaformError extends Error {}
```

### `InvalidPathError`

A path string can't be canonicalized against the form's schema. Typical cause: a typo in `register('parh')` or `setValue('a.bb.c')` against a schema with no `.bb`.

### `InvalidUseFormConfigError`

`useForm` received an invalid configuration, most often a schema passed directly instead of inside an options object (`useForm(schema)` rather than `useForm({ schema })`).

### `SubmitErrorHandlerError`

The `onError` callback passed to `handleSubmit` threw. Caught and re-thrown wrapped in this class so the wrapping submit lifecycle can distinguish "user error handler crashed" from "validation failed."

### `RegistryNotInstalledError`

An Attaform API needs the registry attached to a Vue app, but it isn't installed. Auto-install kicks in for the lazy bootstrap path, so this usually means `useRegistry()` was called from outside a Vue app's lifecycle.

### `OutsideSetupError`

`useForm` / `injectForm` / similar composable called outside Vue setup. Move the call inside a `setup()` function or `<script setup>` block.

### `ReservedFormKeyError`

The `__atta:` namespace is reserved for internal use; passing a form key starting with `__atta:` throws. Pick a different prefix.

## `AttaformErrorCode`

A small, stable enum for Attaform-emitted `ValidationError.code` values. The codes follow the `atta:` prefix convention, so templates can branch on `code` rather than matching message strings.

```ts
import { AttaformErrorCode } from 'attaform'

if (form.errors.email?.[0]?.code === AttaformErrorCode.NoValueSupplied) {
  // …
}
```

| Code value               | Constant                             | Emitted when                                                                      |
| ------------------------ | ------------------------------------ | --------------------------------------------------------------------------------- |
| `atta:no-value-supplied` | `AttaformErrorCode.NoValueSupplied`  | A required leaf is in `blankPaths` (numeric auto-mark or `unset`).                |
| `atta:adapter-threw`     | `AttaformErrorCode.AdapterThrew`     | An `AbstractSchema` method (validate, getDefaults, etc.) threw.                   |
| `atta:validator-threw`   | `AttaformErrorCode.ValidatorThrew`   | User code inside a `z.preprocess` / `.refine` / `.transform` threw.               |
| `atta:hydration-failed`  | `AttaformErrorCode.HydrationFailed`  | A function-form `defaultValues` factory threw or its promise rejected.            |
| `atta:path-not-found`    | `AttaformErrorCode.PathNotFound`     | A path canonicalization rejected the input as not reachable.                      |
| `atta:activation-failed` | `AttaformErrorCode.ActivationFailed` | A walked form's async `defaultValues` factory threw inside `wizard.handleSubmit`. |

Don't expect every internal failure mode to surface as a stable code; the codes are reserved for cases where consumer templates legitimately want to branch on a specific failure mode without matching message strings.

## The `ValidationError` shape

Every error in `form.errors.<path>`, `form.meta.errors`, and the parser's result has this shape:

```ts
type ValidationError = {
  readonly path: ReadonlyArray<string | number>
  readonly message: string
  readonly code: string
  readonly formKey: string
  readonly data?: Json | null
}
```

- `path`: the canonical segment tuple (`['profile', 'email']`). Field errors carry their field's path; global, form-level errors (a root `.refine()`, a path-less `setErrors` call) carry the empty root path `[]` and read through `form.meta.ownErrors`.
- `message`: the human-readable error text.
- `code`: stable identifier (`atta:no-value-supplied`, `zod:invalid_type`, `api:duplicate-email`, etc.).
- `formKey`: which form emitted the error. Useful for cross-form aggregation in wizards.
- `data`: optional, opaque JSON payload a server attached to the error (a captcha challenge, a lockout `unlocks_at` timestamp, an MFA step-up descriptor). Attaform carries it untouched; your UI reads it. Typed as `Json` (the JSON-serialisable value shape).

The `code` is what consumers branch on; the `message` is what templates render. Avoid matching `message` strings; they're localized and may change over time without breaking the public contract.

## Code prefixes by source

| Prefix  | Source                                                                                                                 |
| ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `atta:` | Attaform-emitted (the `AttaformErrorCode` values).                                                                     |
| `zod:`  | Zod adapter (computed from `issue.code`: `zod:invalid_type`, `zod:too_small`, etc.).                                   |
| `api:`  | Conventional prefix for consumer-emitted server errors. Pick whatever convention fits the app: `auth:`, `myapp:`, etc. |

The prefix tells you where the error came from without parsing the rest of the string.

## Where to next

- [The `blank` field-state bit](/docs/validation/blank): the side-channel that surfaces `atta:no-value-supplied`.
- [Server-side errors](/docs/submitting/server-side-errors): the full flow from API failure to reactive `form.errors`.

_Source: https://attaform.dev/docs/reference/errors_

---

# Entry-point reference

> Every public export, grouped by the package subpath it ships from. Use this as the "which import line do I need?" lookup; the rest of the docs cover what each surface does.


New projects pick `attaform`. The other subpaths cover explicit Zod pins, the bring-your-own-adapter escape hatch, the Nuxt and Vite integrations, the compiler internals, the DevTools panel, and the type-only surface.

## `attaform`: the recommended entry

The default entry, and the one new projects reach for. `useForm` here takes a Zod schema and infers every field type from it. It auto-detects the installed Zod major (v3 or v4) and routes to the matching adapter: under the `attaform/vite` plugin (or `attaform/nuxt`, which installs it) that resolution happens at build time so the bundle ships one adapter, and without a plugin the entry dispatches at runtime instead.

```ts
import { createAttaform, useForm } from 'attaform'
```

The Zod-default form surface:

- `useForm`: the Zod wrapper that infers field types from your schema.
- `useWizard`, `lazy`: the multistep orchestrator and its lazy-step helper.
- `injectForm`, `injectWizard`: reach a provided form or wizard from a descendant component.
- `useRegister`: the composable behind `v-register`, for building custom input components.
- `fieldMeta`, `withMeta`: schema-attached field metadata (label, description, placeholder), backed by a cross-adapter store.
- `unset`, `isUnset`: the blank-anywhere sentinel and its type guard.

On top of that surface, `attaform` re-exports the framework-agnostic toolkit (the plugin, the directive layer, the SSR bridge, the error classes, the path primitives) that every entry carries. It's listed in full under [The framework-agnostic toolkit](#the-framework-agnostic-toolkit).

What `attaform` does NOT ship: the version-specific Zod internals (`zodAdapter`, `kindOf`, `ZodKind`, `assertZodVersion`, `UnsupportedSchemaError`). Those diverge between v3 and v4, so they live only on the pinned `attaform/zod-v3` and `attaform/zod-v4` subpaths.

## `attaform/zod`: the explicit Zod pin

The same surface as `attaform`, named explicitly. It is byte-identical: `attaform` is defined as `attaform/zod` re-exported. Reach for it when you want the import line to name Zod out loud, or when a codebase already standardized on it. New projects don't need the extra characters, and existing `attaform/zod` code keeps working with no change.

```ts
import { useForm } from 'attaform/zod'
```

## `attaform/zod-v3`

The Zod v3 adapter, pinned with no runtime dispatch, for projects still on v3.

```ts
import { useForm, withMeta } from 'attaform/zod-v3'
```

Ships the same form surface as `attaform`, plus the v3 `zodAdapter` and the `isZodSchemaType` guard. Its runtime introspection is leaner than v4's; see [`AbstractSchema`](/docs/schemas/abstract-schema#zod-v3-vs-zod-v4-an-introspection-asymmetry) for the discussion.

## `attaform/zod-v4`

The Zod v4 adapter, pinned explicitly. It's the same adapter `attaform` selects when it detects zod@4, committed at the import instead of by detection.

```ts
import { useForm } from 'attaform/zod-v4'
```

Ships the richer v4 introspection set on top of the shared form surface: `zodAdapter`, `kindOf`, `ZodKind`, `assertZodVersion`, `UnsupportedSchemaError`, and the `PathInput` / `PathOutput` type helpers.

## `attaform/abstract`: bring your own adapter

The schema-agnostic escape hatch. `useAbstractForm` works against any object implementing [`AbstractSchema`](/docs/schemas/abstract-schema): a custom adapter, a non-Zod validation library, or a hand-rolled shape. The Zod entries wrap their schema for you; this entry hands you the unwrapped composable and expects an adapter.

```ts
import { useAbstractForm } from 'attaform/abstract'
```

Ships `useAbstractForm`, the `AbstractSchema` contract type, `FieldMetaPayload`, and the same framework-agnostic toolkit every entry carries. There is deliberately no `useForm` alias here: a same-named wrong-variant export fails deep at the first schema call instead of at the import site, and removing that footgun is the whole reason the escape hatch is its own entry. This is a lower-level surface than the Zod entries; reach for it only when you're integrating a schema library Attaform doesn't ship an adapter for.

## The framework-agnostic toolkit

Every entry re-exports the same schema-agnostic core, so this set is identical whether you import it from `attaform`, `attaform/zod`, or `attaform/abstract`. Pick the entry by which form composable you want; the toolkit rides along.

```ts
import {
  // Plugin + registry
  createAttaform,
  useRegistry,
  // Multistep, injection, custom inputs
  useWizard,
  lazy,
  injectForm,
  injectWizard,
  useRegister,
  // Directive layer
  vRegister,
  assignKey,
  defaultCoercionRules,
  defineCoercion,
  // SSR
  renderAttaformState,
  hydrateAttaformState,
  escapeForInlineScript,
  // The unset sentinel
  unset,
  isUnset,
  // Error classes (every Attaform throw extends AttaformError)
  AttaformError,
  InvalidPathError,
  InvalidUseFormConfigError,
  OutsideSetupError,
  RegistryNotInstalledError,
  ReservedFormKeyError,
  SubmitErrorHandlerError,
  // Validation-error codes
  AttaformErrorCode,
  // Display-state heuristic default
  defaultDisplayState,
  // Path primitives (custom adapters only)
  canonicalizePath,
  parseDottedPath,
  isPathPrefix,
  ROOT_PATH,
  ROOT_PATH_KEY,
  // DevTools shared
  DEVTOOLS_WINDOW_KEY,
} from 'attaform'
```

Also re-exports every public type from `runtime/types/types-api` and `runtime/types/types-core`. See [Types reference](/docs/reference/types) for the full list.

## `attaform/nuxt`

The Nuxt module. Auto-installs the plugin, auto-imports the form composables, and wires the DevTools panel.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['attaform/nuxt'],
  attaform: {
    defaults: { validateOn: 'change', debounceMs: 100 },
  },
})
```

After installing, `useForm`, `useWizard`, `injectForm`, `injectWizard`, `fieldMeta`, `withMeta`, and `lazy` are all global auto-imports (toggle with the module's `autoImports` option). `useAbstractForm`, `createAttaform`, and `useRegister` stay explicit imports by design. See [Installation](/docs/getting-started/installation#auto-imports) for the full setup and [SSR hydration: Nuxt](/docs/server-and-ssr/ssr-nuxt) for the server wiring.

## `attaform/vite`

The Vite plugin. Required under bare Vue + Vite for SSR-correct `v-register` bindings, and the piece that rewrites `attaform` / `attaform/zod` to a single Zod adapter at build time.

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { attaform } from 'attaform/vite'

export default defineConfig({
  plugins: [vue(), attaform()],
})
```

The same plugin ships for other bundlers at `attaform/rollup`, `attaform/esbuild`, `attaform/webpack`, and `attaform/rspack`. See [SSR hydration: bare Vue](/docs/server-and-ssr/ssr-bare-vue) for the matching server and client wiring.

## `attaform/transforms`

Raw Vue compiler-core node transforms. Use only when wiring a custom bundler pipeline; the Vite plugin already wraps these for the common case.

```ts
import { vRegisterHintTransform, vRegisterPreambleTransform } from 'attaform/transforms'
```

## `attaform/devtools-panel`

The DevTools panel internals. The [Attaform DevTools panel](/docs/devtools-and-debugging/devtools-panel) is auto-wired by `attaform/nuxt`; this entry is exposed for advanced consumers building their own panel hosts.

## `attaform/types`

Type-only subpath. Re-exports every type from the runtime, useful when you want types in a `.d.ts` consumer file without pulling in the runtime barrel:

```ts
import type { UseFormReturnType, FieldState, ValidationError } from 'attaform/types'
```

For runtime imports under typical app code, import directly from `attaform`; the type re-exports there are equivalent.

## Which subpath for which job?

| You want to…                                          | Import from         |
| ----------------------------------------------------- | ------------------- |
| Build a form in a Vue 3 / Nuxt app (Zod v3 or v4)     | `attaform`          |
| Pin the Zod v3 adapter explicitly                     | `attaform/zod-v3`   |
| Pin the Zod v4 adapter explicitly                     | `attaform/zod-v4`   |
| Wire a custom or non-Zod schema library               | `attaform/abstract` |
| Install the Nuxt module                               | `attaform/nuxt`     |
| Install the Vite plugin under bare Vue + Vite         | `attaform/vite`     |
| Reach directive symbols (`vRegister`, `assignKey`, …) | `attaform`          |
| Use SSR helpers (`renderAttaformState`, etc.)         | `attaform`          |
| Catch an Attaform-thrown error by class               | `attaform`          |
| Type-only imports in a `.d.ts` file                   | `attaform/types`    |

## The Zod-default story

`attaform` and `attaform/zod` are the same surface: the barrel re-exports the unified Zod binding, so `useForm` infers your field types from a Zod schema out of the box. The abstraction underneath stays schema-agnostic. `attaform/abstract` exposes it directly through `useAbstractForm`, which takes an `AbstractSchema` adapter instead of a Zod schema, and every Zod entry is a thin typed wrapper over that same core. If you're integrating a schema library Attaform doesn't ship an adapter for, [`AbstractSchema`](/docs/schemas/abstract-schema) is the contract to implement.

## Where to next

- [The schema contract](/docs/schemas/contract): the bridge between the typed entries and the schema-agnostic core.
- [Types reference](/docs/reference/types): every type, grouped by purpose.
- [Errors reference](/docs/reference/errors): every Attaform-thrown error class.
- [`AbstractSchema`](/docs/schemas/abstract-schema): the contract for non-Zod schema libraries.

_Source: https://attaform.dev/docs/reference/entry-points_

---

# AI agents

> Attaform hands your coding assistant the same map the humans get. Three artifacts, all kept honest by the build: a curated `llms.txt` index, a full-text `llms-full.txt` dump, and an installable Attaform skill. Point an agent at them and the first form it writes reaches for `useForm`, binds with `v-register`, and submits through `handleSubmit`, no correction round needed.


Large language models are excellent Attaform authors when they can see the surface. Left to guess, a low-context model reaches for whatever it assumes a form library looks like: the wrong import, a hand-rolled `v-model`, a write straight through `values`. Every artifact on this page exists to replace that guess with the real shape.

## `llms.txt`: the curated index

[attaform.dev/llms.txt](/llms.txt) is the front door for an agent. It opens with the mental model, lists every documentation page as a titled link, and carries a compact API cheat-sheet plus the core idioms. It is small enough to drop into a prompt whole.

It is a build artifact, regenerated from the live documentation on every deploy. The links come from the site's own navigation and the headline code comes from a type-checked snippet, so the index cannot silently drift from the site it points at. When an agent needs more than the index gives, the links carry it into the full docs.

## `llms-full.txt`: every page, concatenated

[attaform.dev/llms-full.txt](/llms-full.txt) is every documentation page stitched into one file, in reading order, with the site's markup stripped back to plain prose and code. Reach for it when a model has the context budget to hold the whole manual at once, or when you want to hand off Attaform's complete documentation in a single paste. Like the index, it regenerates on every build, so it is always the current docs.

## The Attaform skill

Attaform ships an Agent Skill: a `SKILL.md` that teaches an assistant how to actually build a form, distilled from real Attaform apps into a short list of recipes and rules. Where `llms.txt` is a reference an agent reads, the skill is guidance an agent follows while it writes.

It is built for progressive disclosure. The main file covers the common case end to end: the import surface, the build-a-form shape, the core rules, and short wizard and SSR summaries. It links five reference files an agent loads only when the task reaches their area, served alongside it under `references/`: wizards, errors, custom components, SSR, and validation. The lean main keeps the everyday case cheap, and the depth is one hop away when a form needs it.


Read or copy it above, or fetch it directly at [attaform.dev/skill.md](/skill.md).

### Install it into your project

The skill travels inside the package, so one command copies it into place. From your project root:

```sh
npx attaform skill
```

That drops the whole skill, the main file and its `references/`, into `.claude/skills/attaform/`. Run it again after you upgrade Attaform to refresh the skill in place: because it ships inside the package, running it in a project that has Attaform installed copies that exact version's skill. Aiming at another assistant's skills folder is a trailing path away, for example `npx attaform skill .cursor/skills`.

Prefer to place it by hand? The skill sits at `node_modules/attaform/skills/attaform/`, so you can copy the folder yourself:

```sh
cp -r node_modules/attaform/skills/attaform .claude/skills/
```

Either way, the assistant then loads the Attaform skill whenever it works on a form in your repo.

## Pointing an agent at Attaform

- **A quick task in a chat.** Paste the contents of `llms.txt`, or link it, and ask for the form. The index is sized to fit.
- **A capable agent with room to spare.** Hand it `llms-full.txt` for the complete documentation in one file.
- **An assistant working in your codebase.** Install the skill so every form it touches follows the idioms without a reminder.

All three point the same direction: the schema is the form, `v-register` binds it, and `handleSubmit` ships it. Give an agent that map and it builds Attaform forms the way you would.

_Source: https://attaform.dev/docs/reference/ai-agents_

---

# Custom schema adapters

> Attaform is schema-agnostic at the core. Wire any schema library (Valibot, ArkType, Effect-Schema, a hand-rolled validator) into the runtime by implementing the `AbstractSchema` contract.


This page is the contract reference. The Zod adapters under `attaform/zod` and `attaform/zod-v3` are reference implementations; read their source when you need a concrete example of any of the methods below.

## The contract

```ts
type AbstractSchema<Form, GetValueFormType = Form> = {
  // Identity
  fingerprint(): string

  // Defaults
  getDefaultValues(config): DefaultValuesResponse<Form>
  getDefaultAtPath(path: Path): unknown

  // Shape introspection
  arrayShapeAtPath(path: Path): number | null | undefined
  isLeafAtPath(path: Path): boolean
  isRequiredAtPath(path: Path): boolean
  getSchemasAtPath(path: Path): AbstractSchema<unknown, GetValueFormType>[]
  getSlimPrimitiveTypesAtPath(path: Path): Set<SlimPrimitiveKind>
  getUnionDiscriminatorAtPath(path: Path): UnionDiscriminatorContext | undefined

  // Validation
  validateAtPath(
    data: unknown,
    path: Path | undefined,
    options?: ValidateOptions
  ): MaybePromise<ValidationResponse<Form>>

  // Optional hooks
  getFieldMetaAtPath?(path: Path): ResolvedFieldMeta
  needsAsyncValidation?(): boolean
}
```

Twelve required methods. Two optional hooks. The runtime fills in sensible fallbacks for the optional hooks; omit them when your library doesn't model the feature.

## Identity

### `fingerprint()`

Structural signature of the schema. Two schemas with the same shape return the same string; different shapes return different strings. Used to catch shared-key mismatches in dev: two `useForm({ key: 'x' })` calls with different schemas warn.

Must NOT throw. If it does, Attaform catches the exception, logs it via `console.error` in dev, and skips the shared-key mismatch check for that call. An opaque stable string (`'custom-adapter:v1'`) is a valid fallback; opaque fingerprints make every schema look identical to the mismatch check (the key never changes), so prefer a real structural hash if your library exposes the metadata.

## Defaults

### `getDefaultValues(config): DefaultValuesResponse<Form>`

Returns `{ data, errors, success, formKey }`. Called at form creation and on `reset()`. The `config` argument carries `useDefaultSchemaValues`, `constraints`, and `strict` flags.

### `getDefaultAtPath(path: Path): unknown`

Returns the schema-prescribed default at a structured path. The runtime calls this on every `setValue` to fill structural gaps:

- Empty path → whole-form default.
- Object property → property's default.
- Array index → element default.
- Tuple position → position's default.
- Optional / nullable around a structural inner → inner default.
- Optional / nullable around a primitive → `undefined` / `null` (preserve the wrapper's semantic).
- `.default(x)` wrapper → `x`.

Return `undefined` for paths that don't exist in the schema. Must NOT throw; the runtime skips filling on `undefined`.

## Shape introspection

### `arrayShapeAtPath(path: Path): number | null | undefined`

- `number`: tuple's fixed length.
- `null`: unbounded array.
- `undefined`: non-array path.

The runtime caches the answer to skip per-write probe loops on array writes.

### `isLeafAtPath(path: Path): boolean`

`true` for primitive paths, `false` for object / array / map / set containers. Drives the proxy's descend-vs-terminate decision; reserved leaf-prop names (`dirty`, `errors`, `valid`, `label`, …) inject only at the FieldState terminal.

### `isRequiredAtPath(path: Path): boolean`

`true` when the leaf is required (no `.optional()` / `.nullable()` / `.default()` / `.catch()` wrapper around it). Used by the blank validation augmentation to raise `'No value supplied'` for unfilled required fields.

### `getSchemasAtPath(path: Path): AbstractSchema[]`

List of candidate sub-schemas at `path`. Multiple results are expected for discriminated-union branches. `path` is a canonical `Segment[]`. Return `[]` if your library doesn't model union-style multi-candidates.

### `getSlimPrimitiveTypesAtPath(path: Path): Set<SlimPrimitiveKind>`

Set of primitive `typeof`-style kinds the path's leaf accepts at write time (`'string'`, `'number'`, `'boolean'`, `'bigint'`, …). Drives the slim-primitive write gate. Return a permissive fallback (`new Set(['string', 'number', 'boolean', 'bigint', 'symbol', 'date', 'undefined', 'null'])`) for paths the schema doesn't declare; over-rejecting writes breaks dynamic / SSR rehydration.

### `getUnionDiscriminatorAtPath(path: Path): UnionDiscriminatorContext | undefined`

For discriminated-union containers, return `{ discriminatorKey, getVariantDefault }`. Used by the variant-reshape pipeline so a discriminator-key write swaps the active branch without leaking old keys. Return `undefined` if your library doesn't model DUs.

## Validation

### `validateAtPath(data, path?, options?): MaybePromise<ValidationResponse>`

Returns `MaybePromise<ValidationResponse>`. `path` is a `Segment[]` or `undefined` (whole-form validation). Honor `options.sync` when the schema is sync-capable; the runtime uses it to batch error writes inside DU variant reshape.

Must NOT throw. Return `{ success: false, errors }` for validation failures.

## Optional hooks

### `getFieldMetaAtPath(path: Path): ResolvedFieldMeta` _(optional)_

Resolves schema-attached metadata (label, description, placeholder, full payload). Drives `form.fields(p).label` / `.description` / `.placeholder` / `.meta`. Omit if your library doesn't model metadata yet; consumers see humanized fallbacks.

### `needsAsyncValidation(): boolean` _(optional)_

Return `true` if `validateAtPath` may need a Promise to surface every error this schema can produce. The runtime uses this to decide whether to schedule a one-shot construction-time async pass.

## A minimal Valibot-ish adapter

Assume your library exposes:

- `schema.defaultValues()` returning the schema's typed defaults.
- `schema.parse(data)` returning `{ success: true, data }` or `{ success: false, issues: { path: string[]; message: string }[] }`.

```ts
import type {
  AbstractSchema,
  DefaultValuesResponse,
  GenericForm,
  SlimPrimitiveKind,
  ValidationError,
  ValidationResponse,
} from 'attaform/abstract'

const PERMISSIVE: ReadonlySet<SlimPrimitiveKind> = new Set<SlimPrimitiveKind>([
  'string',
  'number',
  'boolean',
  'bigint',
  'symbol',
  'date',
  'undefined',
  'null',
])

export function myLibAdapter<F extends GenericForm>(schema: MyLibSchema<F>): AbstractSchema<F, F> {
  return {
    fingerprint() {
      return schema.signature?.() ?? 'my-lib:v1'
    },

    getDefaultValues({ constraints }): DefaultValuesResponse<F> {
      const defaults = schema.defaultValues()
      const merged = mergeDeepPartial(defaults, constraints)
      return { data: merged, errors: undefined, success: true, formKey: '' }
    },

    getDefaultAtPath(path) {
      return walkSchemaToDefault(schema, path)
    },

    arrayShapeAtPath(path) {
      return walkSchemaToArrayShape(schema, path)
    },

    isLeafAtPath(path) {
      const kinds = walkSchemaToSlimPrimitives(schema, path)
      if (kinds === undefined) return false
      return ![...kinds].some((k) => k === 'object' || k === 'array' || k === 'map' || k === 'set')
    },

    isRequiredAtPath(path) {
      const leaf = walkSchemaToLeaf(schema, path)
      return leaf?.isRequired ?? false
    },

    getSchemasAtPath() {
      return []
    },

    getSlimPrimitiveTypesAtPath(path) {
      return walkSchemaToSlimPrimitives(schema, path) ?? PERMISSIVE
    },

    getUnionDiscriminatorAtPath() {
      return undefined
    },

    validateAtPath(data, path) {
      const result = path !== undefined ? schema.parseAtPath(data, path) : schema.parse(data)

      if (result.success) {
        return { success: true, data: result.data, errors: [], formKey: '' }
      }

      const errors: ValidationError[] = result.issues.map((issue) => ({
        path: issue.path,
        message: issue.message,
        code: `my-lib:${issue.code ?? 'unknown'}`,
        formKey: '',
      }))

      return { success: false, errors, data: undefined, formKey: '' }
    },
  }
}
```

Wire your adapter through `useAbstractForm`:

```ts
import { useAbstractForm } from 'attaform/abstract'
import { myLibAdapter } from './my-adapter'

const form = useAbstractForm({ schema: myLibAdapter(mySchema) })
```

## Zod-v3 vs. Zod-v4: an introspection asymmetry

Worth knowing if you're studying the reference implementations: the v4 adapter exports `kindOf`, `ZodKind`, and `assertZodVersion` for runtime introspection of Zod nodes; the v3 adapter exports `isZodSchemaType` but not the broader set. Both adapters implement the full `AbstractSchema` contract; the difference is in the consumer-facing diagnostic helpers above the contract surface. If you're forking a Zod adapter as a starting point, the v4 source is the richer reference; the v3 source is the leaner one.

## Where to next

- [The schema contract](/docs/schemas/contract): the high-level mental model `AbstractSchema` implements.
- [Types reference](/docs/reference/types): every type the contract references.
- [Entry-point reference](/docs/reference/entry-points): which subpath ships `AbstractSchema` (`attaform/abstract`).

_Source: https://attaform.dev/docs/reference/custom-adapters_