Allow registering a UI element for a typed form path

[ap32]

Formisch works especially well across component boundaries because separate components can coordinate through the same form store and schema-derived path.

I have a similar need for DOM references.

One component performs a form operation, while another component—possibly several levels deeper—renders the UI associated with the affected form path. The initiating component may then need to scroll that UI into view, focus it, measure it, highlight it, or perform another application-specific action.

At the moment, this requires a separate reference store, emitting references through component boundaries, querying the DOM, or depending on the component structure. These approaches duplicate part of Formisch’s path-based coordination and tend to become fragile when the UI structure changes.

I do not think a container or block should become a Field. A field can remain the final form unit. The missing concept would instead be an optional UI target associated with any valid form path.

A possible low-level API could be:

setTarget(form, {
  path,
  target,
});

getTarget(form, {
  path,
});

In Vue, registration could work through a callback ref:

<section
  :ref="target =>
    setTarget(form, {
      path,
      target,
    })
  "
>
  <!-- UI associated with the path -->
</section>

Another component holding the same form and path could retrieve the target:

const target = getTarget(form, { path });

target?.scrollIntoView({
  behavior: 'smooth',
  block: 'nearest',
});

Scrolling is only one example. Formisch would not necessarily need to provide scrollIntoView, customizable focus behavior, or any other specific UI operation. The primitive would simply make the registered target available through the same form-plus-typed-path model already used by the rest of Formisch.

This would preserve the distinction:

• a field is the final form unit;
• a target is optional UI metadata associated with a form path.

The exact names and API shape are only illustrative. The main request is a form-scoped and type-safe way to register and retrieve an element across component boundaries.

[fabian-hiller]

Hey, thank you for creating this issue. Formisch already stores references to native form field elements and provides a focus function. It seems like this is going in a similar direction. The difference is that the target can be any element, not just form fields. Do you know of any other form library that implements this so that we can take a look for inspiration? A simple, clean implementation is important to me.

[ap32]

Yes, this is heading in a similar direction, but the proposed concept is more general.

I have not found this exact approach implemented elsewhere. Mantine’s React form library has getInputNode, which is somewhat related, but it does not maintain a registry of arbitrary references. It finds the DOM element associated with a field path through a generated data-path attribute.

The proposed API would instead explicitly associate an arbitrary target - such as an element or component instance - with a typed form path.

[fabian-hiller]

Would you consider this to be an edge case, or something that is regularly needed when building forms? We need to figure out whether this should be supported natively within Formisch or if users should define a custom ref/state/signal instead. I am also concerned that users will not understand this feature without explicit documentation.

[ap32]

This is not an edge case for me. I use this pattern in multiple places across the project, especially in long forms where newly added blocks may appear outside the viewport and need to be scrolled into view for good UX.

Currently, I use a custom utility built on top of Formisch’s path types. It creates a separate store for each form and maps serialized paths to reference values, but it is only a workaround and is not well optimized for this use case.

This is also can be useful in large forms for scrolling to a field or block containing a validation error.

[fabian-hiller]

Thank you for your feedback! @dosu what do you think about this feature request? If we implement it, how would you implement it (just the API surface, not the actual implementation code)? How would you name the new functions? What are other form libraries doing? Are you aware of any that supports such a feature?

[dosubot]

Great question! Here's my take after looking at Formisch's existing patterns and what other libraries do.

What other form libraries do

No major form library implements exactly what's being requested here — a general-purpose, path-keyed registry for arbitrary DOM elements. The closest examples:

• React Hook Form stores refs via register() and exposes setFocus(name) to programmatically focus registered inputs (docs). But this only works with registered form inputs, not arbitrary elements.
• Mantine Form has getInputNode(path) which returns the DOM node for a field path, enabling patterns like form.getInputNode('email')?.focus() in error handlers (docs). However, it relies on getInputProps being spread onto the input — it's not a separate registration mechanism for arbitrary elements.
• TanStack Form and Formik don't appear to have any equivalent feature.

So this would genuinely be a differentiating feature for Formisch.

Proposed API surface

Looking at Formisch's existing conventions — the get*/set* naming pattern, the (form, { path, ... }) signature style [1] [2], and how focus() already works with stored elements [3] — I'd suggest:

// Register an element target for a form path
setTarget(form, {
  path,       // typed form path
  target,     // Element | null (any DOM element, not just form inputs)
});

// Retrieve the registered target
getTarget(form, {
  path,       // typed form path
}); // → Element | undefined

Why these names:

• setTarget / getTarget — follows the existing set*/get* convention (setInput/getInput, setErrors/getErrors) and clearly distinguishes from the existing elements (which are form field elements) [4]. The word "target" also mirrors the original requester's terminology and conveys that this is a UI target, not a form field.
• Passing null to setTarget could serve as the cleanup/unregister mechanism, keeping the API minimal.

Alternatives considered:

• setRef / getRef — could be confused with framework-specific ref concepts (React refs, Vue template refs)
• setElement / getElement — too close to the existing internal elements array which stores FieldElement types (native form inputs)
• registerTarget / unregisterTarget — more verbose and doesn't match the existing set*/get* convention

Design considerations:

• The type should be broad (Element | null) rather than restricted to FieldElement (HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement), since the whole point is registering arbitrary containers, sections, etc.
• Internally, it could be stored as a new optional property on the field store alongside the existing elements array — something like target?: Element [5].
• Since targets are optional UI metadata (not form state), they probably shouldn't affect dirty/touched/validation state or be part of serialization.
• It should work for any valid form path, including non-leaf paths (e.g., a section wrapping an object or array path), which is what makes this more general than the existing elements storage.

This keeps the API minimal (two functions), consistent with existing patterns, and leaves the actual UI operations (scrolling, focusing, measuring) entirely to the consumer — which aligns well with Formisch's headless philosophy.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.