Field types

Field key: the RHF register name, and the identifier that conditions, copyFrom/countryFrom/optionsFrom, and dependsOn target by name. Must not contain a dot (validator-enforced — dots are read as nested paths by RHF and the condition engine).

Visible label text.

static and submit ignore it (their own content/text prop is the visible text instead).

Helper text rendered under the label and wired into aria-describedby alongside any error.

Short annotation rendered beside the label — "Required in Germany" — so a conditionally-revealed field can say why it appeared. Part of the field's accessible name, unlike the required mark, which is aria-hidden because the control already exposes required-ness on its own.

needs a label to annotate: no label, no badge — which also means static, submit, and hidden ignore it, since they render none.

The control's autocomplete attribute — "name", "email", "street-address", "postal-code", "address-level2", "bday". WCAG 2.2 SC 1.3.5 (AA) requires one on every field collecting information about the person filling the form; a label alone does not carry the purpose, since "Postleitzahl" and "ZIP" are the same purpose to a person and neither to a parser. Typed as a plain string rather than an enum of the WCAG purposes because the attribute is a grammar around one purpose token — "section-owner-1 name", "shipping street-address", "mobile tel" and "off" are all valid and an allowlist would reject them.

reaches the DOM on text, email, password, textarea, number, masked, time, phone and otp — the types whose control is a native text-entry input. date, select and country render a popover behind a button, and HTML ignores the attribute on file, checkbox/switch, radio and segmented; set there it is inert, not an error. phone and otp already default to "tel" and "one-time-code", which an unset value leaves alone.

Placeholder/prompt text; meaning is per-control (input placeholder, empty-select prompt, unset-date prompt).

on group it overrides the "Add" button's label instead of a text placeholder; on file it replaces the dropzone's "Drag files here, or browse" prompt, which is part of the file input's accessible name — so it is read aloud after the label, not just shown; has no effect on radio, segmented, checkbox group, rating, slider, or signature.

Marks the field mandatory: shows a required mark and drives the generated zod schema.

on rating it also changes clear behavior (clicking the current value clears it only when optional); radio, segmented, and country can never be cleared once set, regardless of required. No effect on static/submit (no user input) or hidden (always has a value).

Statically disables the control; disabledWhen/enabledWhen layer on top of (not instead of) this flag.

Hides the field and excludes it from validation and the submit payload while the spec doesn't match. Value operators only (equals/notEquals/in) — isValid is rejected here, since visibility itself decides which schema gets built.

Disables the field while the spec matches. The only base prop where isValid is allowed (checking a sibling's own schema validity). Mutually exclusive with enabledWhen (validator-enforced).

Inverse of disabledWhen — disabled while the spec does NOT match; reads straight for "enabled once X is valid". Mutually exclusive with disabledWhen.

Keeps the field disabled until the named sibling otp field's code is verified.

must reference a sibling of type otp; rejected inside a group (validator-enforced).

Mirrors a same-type sibling's value until the user edits this field, then the source wins again on its next change (same semantics as phone's countryFrom).

not supported on phone, otp, password, file, signature, group, hidden, static, or submit fields (validator-enforced); a select pair must also match multiple, and a date pair must also match range.

'full' | 'half' | 'third' | 'quarter', or a per-breakpoint object, on the 12-col grid; unset breakpoints fall back to full rather than cascading from a smaller breakpoint.

Length/pattern/trim/allow/matches constraints — see the shared TextRules shape below.

Same TextRules shape as text — the email-format check itself is built in, not part of rules.

Same TextRules shape as text/email — length/pattern/trim/allow/matches, layered on top of complexity.

Adds a live pass/fail checklist (uppercase/lowercase/number/special/minLength) under the input while typing; only the currently-failing rules render, and the checklist replaces (never duplicates) the schema's error text.

Same TextRules shape as text — see the shared TextRules shape below.

Pattern made of '#' (digit), 'A' (letter), '*' (alphanumeric) token chars — every other character is a literal; must contain at least one token char (validator-enforced).

Custom error for an incomplete value; defaults to the "Incomplete value" message.

Native min constraint.

Native max constraint.

Native step constraint (also the spinner increment).

Number of code digits/characters rendered as input-otp slots.

Sibling field whose value gates this code: changing it invalidates any already-verified code (generation-stamped) and resets the send/verify flow. Rejected inside groups.

Initial calling code shown before the user picks or types a number.

Pins these countries, in this order, above the rest (which stay name-sorted) in the flag dropdown.

Sibling country or single-value select field this phone re-syncs its calling code from on every change — see the shared countryFrom shape below.

Static option list. Exactly one of options or optionsFrom is required — set neither or both and validateFormConfig throws.

Derives the option list from a sibling field's current value instead of a static array — see the shared optionsFrom shape below.

Renders a filterable combobox instead of the native <select>.

Value becomes Option["value"][] instead of a single value; also switches rendering to the combobox (like searchable).

Restricts the combobox to this subset; defaults to every ISO 3166-1 alpha-2 country (libphonenumber-js getCountries()).

Pins these countries, in this order, above the rest; must be a subset of countries when both are set (validator-enforced).

Choices rendered as a radix RadioGroup; at least one option is required (validator-enforced).

Choices rendered as a joined button group with radio semantics (radix RadioGroup, not a toggle group) — guaranteed radiogroup/radio roles and arrow-key roving focus; at least one option is required.

Presence of options renders a checkbox GROUP (value becomes Option["value"][] of the checked entries); omit it for a single boolean checkbox.

Inherited from the shared checkbox/switch config shape but NOT functionally supported on switch (known issue) — a switch always renders and stores a single boolean regardless of options; use checkbox for a group.

Renders a range calendar and switches the value to { from?; to? } instead of a single "yyyy-MM-dd" string.

Earliest selectable date; also biases the calendar's initial month.

Latest selectable date; also biases the calendar's initial month.

What minDate/maxDate do to the calendar — they always constrain the value. "restrict" (default) disables out-of-range days and clamps month navigation, for a range that is genuinely unavailable. "validate" leaves those days selectable by mouse and keyboard so picking one fails with message instead, which is how an age cutoff says "You must be 18 or older" rather than greying out most of the calendar. Governs these two bounds only — minDateField/maxDateField never shape the calendar either way.

Bounds this date to be on/after a sibling non-range date field's current value (form-level refine, not this field's own schema); rejected together with range: true (validator-enforced).

Bounds this date to be on/before a sibling non-range date field's current value; same range: true restriction as minDateField.

Custom error for a minDate/maxDate violation, replacing "Must be at least/at most <date>" — the way to say "You must be 18 or older" instead of a bare bound. One sentence covers both bounds, and with range: true both endpoints; unparseable values and the minDateField/maxDateField rules keep their own messages.

Earliest selectable time — zero-padded 24h, compared lexicographically.

Latest selectable time; must not be before minTime (validator-enforced).

Minute increment; converted to seconds for the native input's step attribute.

Bounds this time to be on/after a sibling time field's current value (form-level refine).

Bounds this time to be on/before a sibling time field's current value (form-level refine).

Highest star value (1..max); defaults to 5 when unset. Must be between 2 and 10 (validator-enforced).

Lower bound of the range.

Upper bound of the range.

Increment between selectable values.

Ink color; defaults to signature_pad's own default (black). Treated as static config — changing it at runtime recreates the pad and only restores the value captured at mount.

Canvas height in pixels; defaults to 160.

Native accept attribute (MIME types / extensions), e.g. ".pdf,.doc,.docx". Also enforced by the generated schema — a file the browser could not type matches no MIME token, so list the extension too (".pdf,application/pdf") if those must get through — and written out as the dropzone's hint ("PDF, DOC or DOCX").

Rejects files larger than this via the generated schema (a field error, not a manual setError, so it survives the next resolver run); unset means no size limit.

Value becomes File[] instead of a single File; also allows picking more than one file at once.

The static value carried through with the rest of the form's values; must not appear in a step's fieldNames (validator-enforced — it's exempt from step assignment).

The block's text; may contain an allowlisted inline <a href> or <br> (safe schemes only) via the field's rich-text renderer.

Element to render as; omit for a plain paragraph. "divider" ignores content and renders a separator instead.

Recursive — any field type documented on this page (not expanded here to avoid infinite recursion in this table). Known v1 limitation: visibleWhen/disabledWhen conditions on fields nested inside a group are NOT skipped by validation.

Minimum rows; defaults to 0. The remove button disables once row count reaches this floor.

Maximum rows; defaults to unbounded. The add button disables once row count reaches this ceiling.

Button label.

'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link' (shadcn Button variant).