`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.
## Values that land as you type
Some components commit their model only at the end of an edit. A formatted number input is the usual case: PrimeVue's `InputNumber` emits `update:modelValue` on blur, and reports each keystroke through an `input` event whose payload carries the parsed `value`. Attaform listens for that event too, so the form follows every keystroke:
```vue
```
A component that reports keystrokes this way updates the form as you type, and one that reports nothing until it commits updates the form when it commits. Attaform reads an `input` payload only when it is an object holding its own `value`, so a component that forwards the plain DOM event is left to its model.
A handler of your own on that event runs after Attaform's write, so an `@input` on the component reads committed state, the same [listener ordering](/docs/binding-inputs/v-register#listen-without-binding) a native input gives you.
## The same write rules as a native input
Every value a component writes back takes the path a value typed into a native input takes:
- [Modifiers](/docs/binding-inputs/modifiers#on-a-component): `.lazy`, `.trim`, and `.number` work on the component, timed to focus leaving it.
- [Register transforms](/docs/binding-inputs/transforms) run on each write, left to right.
- [Schema-driven coercion](/docs/binding-inputs/coercion) turns a string the component emits into the number or boolean the leaf declares, so a text component can back a `z.number()` field.
```vue
```
## 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, scroll-to-error, and the focus edge that `.lazy` and `.trim` wait for. 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
```
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 and nothing else; its return value lands in storage. Equivalent to reading `form.values.
`, computing the next value, and writing it, in one step.
Spread `prev` in a whole-form callback. The return replaces the entire form, and a key the return leaves out is refilled from the **schema's** declared defaults, not carried over: against `profile: z.object({ city: z.string().default('Lusaka') })`, a return of `{ name: 'Ada' }` lands `city: 'Lusaka'` no matter what the user had typed or what `defaultValues` declared. `(prev) => ({ ...prev, name: 'Ada' })` is the shape that keeps the rest of the form.
## Returns `boolean`
`setValue` returns `true` when the write was accepted, `false` when it was rejected by the slim-type gate (the value didn't match the leaf's accept set, for example a number written to a string field). A `false` return leaves form state untouched.
The gate is about the leaf's **kind**, not its constraints. An out-of-enum string, a failing email format, a below-`.min()` number all write successfully and return `true`; they surface as field errors instead. So a `false` return means the call site has the wrong type, not that the user has the wrong value. Reach for it when a downstream action depends on the write landing:
```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, variant memory, history, and change listeners. 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 '', blankPaths.value 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 `DefaultValuesInput