Chapter 25: Form

Core Idea

The one-part submission container that composes with Field.Root children — collects their values, runs/aggregates validation, and merges server-side errors into client field state; this chapter is the API-reference companion to the full workflow already covered in ch009 (Forms).

Key Concepts

• Anatomy: Form wraps Field.Root children directly — no sub-parts of its own.
• errors: object of { [fieldName]: string | string[] } merged into client-side field state — the server-side validation display mechanism (ch009).
• onFormSubmit: receives parsed form values as a plain object plus eventDetails, and auto-calls preventDefault() — the alternative to handling native onSubmit/FormData yourself.
• validationMode: sets the default validation mode inherited by every child Field.Root that doesn't override it individually (onSubmit default, or onBlur/onChange).
• actionsRef: imperative handle for the form, analogous to the actionsRef pattern seen on Dialog/Menu/etc.

Reference Tables

Part	Notable props
Form	errors, onFormSubmit, validationMode, actionsRef

Key Takeaways

1. Set validationMode once on Form to establish the project-wide default, and override per-field only where a specific control needs different timing (e.g. an async-validated username field using onChange while the rest of the form uses onSubmit).
2. Prefer onFormSubmit over hand-rolling FormData extraction unless you specifically need the raw native SubmitEvent/FormData object (e.g. for multipart/form-data file uploads).
3. errors is additive/mergeable, not exclusive — passing server errors here doesn't replace client-side validation, both display through the same Field.Error.

Connects To

• ch009 (Forms): full narrative guide — naming, constraint/custom/server validation, RHF/TanStack integration — this chapter is its condensed API reference.
• ch023 (Field): the child component Form is built to compose with.