# `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.

## Modifiers come along

[Modifiers](/docs/binding-inputs/modifiers) the parent writes on the wrapper reach the inner control:

```vue
<FieldRow v-register.trim="form.register('email')" label="Email" />
```

The `<input v-register="rv">` inside `FieldRow` now trims exactly as if `.trim` were written on it. Modifiers on the inner binding still apply, and the two sets combine: `.trim` on the parent with `v-register.lazy="rv"` inside gives the input `.lazy.trim`. When the inner control is itself a component, the parent's modifiers reach it the same way, [timed to focus leaving it](/docs/binding-inputs/modifiers#on-a-component).

## 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.

A wrapper meant to work both ways says so, and the warn stands down:

```ts
const rv = useRegister({ optional: true })
```

Leave it off for a wrapper that always expects a binding. There the warn earns its keep: a parent that forgot `v-register` renders a field that looks fine and stores nothing, and only the author knows which of the two a given component is.

`rv?.isBound` is the test for "did a parent bind me", and it is the one to reach for. Script code holds the hybrid Proxy, which is an object and so always truthy; a template holds the unwrapped ref, which is `undefined` when unbound. Those two disagree, and `isBound` reads the same on both:

```ts
const rv = useRegister()
if (rv?.isBound) {
  // a parent bound this wrapper to a field
}
```

It is reactive in both directions, because the answer can change after mount. A parent is free to bind on a later render, which is also why `useRegister` cannot simply return `undefined` when nothing has bound yet: at setup time it does not know, and giving up the Proxy would sever the binding that arrives later.

```vue
<AddressField v-register="ready ? form.register('street') : undefined" />
```

## One component, bound and unbound

A wrapper that calls `useRegister({ optional: true })` still works when nobody binds it, and it does not need a second copy of its markup to manage that. Write the plain binding you would write without Attaform, and `v-register` takes over whenever a field resolves:

```vue
<select v-register="rv" :value="modelValue" @change="onChange">
  <option value="">None</option>
  <option v-for="o in options" :key="o.value" :value="o.value">{{ o.label }}</option>
</select>
```

Bound, the field drives the control and the `:value` is inert. Unbound, the `:value` is the whole binding and behaves exactly as it would on a bare `<select>`. The same holds for `:value` on a text input or textarea and for `:checked` on a checkbox or radio.

An `<option>`'s own `:selected` works the same way, so a hand-marked option list keeps its marks when nobody binds the `<select>`.

One edge to know: `v-model` is not a substitute for `:value` here. It installs Vue's own model directive beside `v-register`, so two writers drive one element, and that still warns.

## 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), save `injectForm<Form>()` into a `form` handle and call `form?.register(path)` for each one. 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.
