Fields
The field object, inputProps, number and optional inputs, and binding component libraries.
form.Field takes a field name and passes that field’s object to its child.
The object holds the field’s state and commands, and inputProps turns it
into the props an input needs. Type a number with a trailing . and watch
the line under Age.
<form.Field name="age">
{(field) => <input {...inputProps(field, { kind: "number" })} />}
</form.Field>The field object
FieldApi<T> holds the field’s current state, its commands, and the pieces
that bind an element. A new object arrives with each change.
| Member | What it is |
|---|---|
value |
The value the store holds. |
name |
The dotted name with array indexes, such as tasks.0.title. |
errors, shownErrors |
Every error, and the ones the show setting lets through now. |
userErrors |
The errors set with setErrors. They come last in errors. |
touched, edited, dirty |
Blurred once, changed by the user, different from the baseline. dirty needs the dirty() plugin. |
invalid, validating |
Has any error, has a validator running. |
disabled, readOnly |
Set on this field or one above it. |
setValue, setTouched, setErrors, handleBlur, reset, validate |
The handle’s commands. Arrays add push, insert, remove and move. |
text, setText, setNumberText, ref |
The pieces for binding an element. See below. |
handle |
The field’s handle, to pass to another component or keep for later. |
id, errorId |
Ids for the input and its error list. |
inputProps
For plain HTML, inputProps(field) puts every piece on the element and
adds the rest an <input> needs: name, id, value, the change and blur
handlers, ref, disabled, readOnly, and aria-invalid and
aria-describedby while errors show. It is a function, not a member, so a
form that never calls it doesn’t ship it. Pass options for other kinds of
input. The compiler checks them against the field’s value type.
| Call | Element | Field type |
|---|---|---|
inputProps(field) or inputProps(field, { type: "email" }) |
<input> |
string |
inputProps(field, { kind: "textarea" }) |
<textarea> |
string |
inputProps(field, { kind: "select" }) |
<select> |
string |
inputProps(field, { kind: "number" }) or { kind: "range" } |
<input type="number"> or "range" |
number |
inputProps(field, { kind: "checkbox" }) |
<input type="checkbox"> |
boolean |
inputProps(field, { kind: "checkbox", value }) |
one box of a group | array of strings or numbers |
inputProps(field, { kind: "radio", value }) |
one radio | string, number or boolean |
Number inputs take empty, the value an empty input writes. It defaults to
undefined and is required when the field’s type has no undefined.
A component given only a handle records its element with fieldRef(handle)
and gets the props from createInputProps(handle).
Number inputs
A number field bound with inputProps(field, { kind: "number" }), or with
field.setNumberText, holds a number, or undefined while the input is
empty. Some text on the way to a number isn’t one yet:
| Typed | Input shows | Field holds |
|---|---|---|
12. |
12. |
12 |
- |
- |
the value it held before |
| nothing | nothing | undefined, or the empty option |
field.text keeps the typed text while the field still holds the value that
text wrote, so the caret and the . don’t jump. Once the input loses focus,
or something else writes a different value, it shows the number again.
Optional fields
An optional field such as nickname?: string starts out undefined.
inputProps shows undefined as an empty input, and a checkbox shows it
unticked. Type the form with define<T>() to have optional keys, since
defaultValues can’t leave a key out and still name it:
interface Profile {
name: string;
nickname?: string;
}
const profile = forms.define<Profile>({ defaultValues: { name: "" } });Components that take a field
The child of form.Field can hand the field to your own component. Type its
prop as FieldApi<T>, where T is the value type it edits:
import { type FieldApi, inputProps } from "@lunarhue/forms-solid";
function TextInput(props: { field: FieldApi<string>; label: string }) {
return (
<label>
{props.label}
<input {...inputProps(props.field)} />
</label>
);
}
<form.Field name="name">{(field) => <TextInput field={field} label="Name" />}</form.Field>;Read the field through props.field. Destructuring it reads each member once
and the component stops updating.
To skip the form.Field wrapper and get <form.TextInput name="name" /> on
every form, register the component. See
Reusable field components.
Binding an element
Component libraries such as Base UI, Radix and React Aria own their labels, ids and aria, and take a value with a change callback. Give them the pieces of the field object and leave the rest to them:
| Piece | What it does |
|---|---|
text |
The text to show: number text the user is typing, else the display text a plugin such as a mask gives, else the value. |
setText(text, from?) |
Writes typed text. With a mask, it also puts the formatted text in the element and places the caret. from is the element or an event whose target is the element. Without it, the focused element ref recorded is used. |
setNumberText(text, empty?) |
Writes text typed in a number field. - writes nothing yet, 12. writes 12, and empty text writes empty. |
handleBlur |
Marks the field touched, runs blur validation, and drops typed number text. |
ref |
Records the element, so an invalid submit can focus it. |
Checkboxes, switches, selects and radio groups hold a value, not text, so
bind value and setValue.
The demo binds plain elements the same way a primitive library takes a
field. Type 1. in Boxes, submit it empty, and clear it.
<input
ref={field.ref}
value={field.text}
onInput={(event) => field.setText(event.currentTarget.value, event)}
onBlur={field.handleBlur}
/>
<input type="checkbox" ref={field.ref} checked={field.value} onChange={(event) => field.setValue(event.currentTarget.checked)} />A primitive bound this way shows a reset or a value persist restored, since
it reads text or value on every change. A primitive that keeps its own
text, such as Base UI’s NumberField, needs value and its own change
callback instead of text.
A browser can fill inputs back in from before a reload, after the server
markup arrives and before Solid hydrates. ref writes the field’s state
into a native input, textarea or select when they differ, so the input shows
what the form holds.
Ids
field.id is the form’s id followed by the field’s path. It stays the same
for the life of the field, including when an array row moves, so it works as
a DOM id and as a list key. The input gets it as id, so a
<label htmlFor={field.id}> points at the input.
field.errorId is the id for the element that lists the field’s errors.
inputProps(field) points aria-describedby at it while errors show, so
screen readers read them with the input. A primitive library that renders
its own error element points at that one instead.
Last updated