fields

A reactive Proxy keyed by schema paths. Every leaf surfaces a 31-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.

Category

Return property

Type

FieldStateMap<ReadShape<Schema>>

Reactive

Yes

Read shape per leaf

FieldState (31 properties)

form.fields.<path> is the per-leaf companion to form.values.<path>. 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:

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:

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:

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

What FieldState carries

Each leaf exposes a 31-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.

Value reads

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

Validation reads

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

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.

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.

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

import { withMeta } from 'attaform/zod'

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:

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