Guide

Supported form controls

Exact getValue, setValue, validation, and serialization behavior for every supported native form control.

The controller manages named inputs, selects, and textareas. Use this page when choosing field names or interpreting getValue() and setValue() results.

Reading values

ControlgetValue(name)
Text-like input or textareaFirst matching value as string.
Single selectSelected value as string.
Multiple selectSelected option values as string[].
Radio groupChecked value as string; '' when none is checked.
One checkboxChecked value as string; '' when unchecked.
Checkbox group with a bare nameOne checked value collapses to string; several become string[]; none becomes ''.
File inputSelected files as File[], including an empty array.
Missing nameundefined.

The name="field[]" convention

The [] suffix explicitly requests collection behavior when more than one matching field exists.

GroupResult
Repeated text, select, or textareaOne string per control in DOM order.
Repeated checkboxesAlways string[] of checked values, including [].
Radio groupRemains scalar because a radio group represents one choice.
Repeated file inputsConcatenated File[] from every input.
A single field ending in []Uses its normal scalar/control-specific behavior.

Bare repeated text fields keep legacy behavior: getValue() reads the first and setValue() broadcasts one value to every match.

Writing values

ControlsetValue(name, value)
Text-like input or textareaWrites String(value); null/undefined become ''.
Multiple selectSelects options matching a scalar or any item in an array.
Checkbox groupAn array checks matching values; a scalar checks only its matching value.
Radio groupChecks the option matching the scalar string. Arrays are stringified and should not be used.
File inputBrowsers forbid assigning files. Pass [] only to clear the field.
Repeated name="field[]" text/select/textareaDistributes array items by index; clears surplus controls and drops surplus values.
Missing nameNo-op; returns the controller.

After writing, setValue() dispatches one bubbling input event from the first matching field. That single event enters error clearing, validation, watchers, subscribers, visual sync, and auto-submit once.

To change which options a <select> offers, use setOptions() instead of rewriting its markup. It keeps the current value when it is still listed and runs the same pipeline only when the selected value changes. Options added or removed by your own code are detected too: if the selected value changes, the controller revalidates, fires watchers and notifies subscribers.

DOM lookup and external controls

getField(name) returns one element, an array for repeated names, or null. It uses form.elements, so controls associated through form="id" are included even when they sit outside the form subtree. Delegated input handling also listens for those controls.

The form’s MutationObserver watches only the form subtree. Adding an external form="id" control does not itself create a mutation notification, but its later input events are handled normally.

Serialization differs from field reads

getData() and parseFormData() use native FormData semantics:

  • Disabled controls and unnamed controls are omitted.
  • Repeated names become arrays in the plain data object.
  • Empty file placeholders are removed from both outputs.
  • A successful named submit button is included only when supplied as the submitter.
  • File values remain files and are not directly JSON-serializable.
  • Reserved keys such as constructor and __proto__ are safe own properties.

getState().values is controller-oriented rather than a submission payload: it includes tracked validator names and normalized field reads. Use getData() for network submission.

Validation notes

  • Arrays use item count for minLength and maxLength.
  • Required checkbox groups pass when at least one value is selected.
  • A multiple select returns an array and follows the same array rules.
  • File arrays pass required when at least one file exists.
  • Pattern validation converts arrays to a comma-joined string; file entries use filenames.
  • numeric, min, and max validate non-empty scalar signed decimal strings; bounds are inclusive.

Per-control validation with each

Repeated controls can share one exact name and still receive independent rules:

form('signers', {
  validators: {
    'signer_email[]': {
      minLength: 1,
      each: {
        required: true,
        pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
      },
    },
  },
})

Group rules such as the outer minLength use the aggregate value. Rules inside each use each concrete field value. On controller validation, only the members that fail each receive css-error and aria-invalid; group-level and manual errors still mark every control in the named group. Public errors stay flat as FormErrors[name]: string[], with member messages appended in DOM order.