Typed names and handles
Field names the compiler checks, and handles you can pass around.
Every name prop is checked against the form’s value type. A typo, or a
field the component can’t edit, fails the build. For the parts of a form you
pass around, use a handle: a typed object for one field.
Names
A name is a dotted path through the value, such as "shipping.city". With
the form above, a typo gets this:
<form.TextField name="shipping.cty" label="City" />error TS2769: No overload matches this call.
...
Type '"shipping.cty"' is not assignable to type '"billing.street"
| "billing.city" | "shipping.street" | "shipping.city"'.
Did you mean '"shipping.city"'?The list holds only the names TextField can edit. shipping is a name too,
but its value is an object and TextField takes a FieldApi<string>, so it
isn’t offered.
Names go through objects and stop at arrays. tasks names the array, but
there is no tasks.0.title. Rows are reached through
handles, see Arrays. A name has at most 8 segments.
Handles
form.root is the handle of the whole value. at(key) returns a child’s
handle, typed from the value, and also catches typos:
const shipping = form.root.at("shipping"); // handle to { street, city }
const city = shipping.at("city"); // handle to a string
form.root.at("shiping");
// Argument of type '"shiping"' is not assignable to parameter of type
// '"billing" | "shipping"'.A handle holds no state. It is the same object on every call, it carries the
field’s commands (setValue, reset, validate, push on arrays and so
on), and peek() reads the current snapshot in event handlers. Pass one as
handle instead of name:
<form.TextField handle={form.root.at("shipping").at("city")} label="City" />To render something from a handle’s state, read it with useField(handle),
or useField(handle, select) to re-render only when the selected part
changes.
Next
A component that renders a whole part of a form, such as an address, takes a handle. Fieldsets and scopes types it.
Last updated