Imperative helpers are useful when the form participates in a bigger flow: wizard steps, route changes, modal close guards, inline autosave, custom field chrome, or external events.
Actions.tsts
| 1 | await form.validate(names?) |
| 2 | form.resetFields(values?) |
| 3 | form.setValue('firstName', 'Ava') |
| 4 | form.getValue('firstName') |
| 5 | form.getValues() |
| 6 | form.setError('email', 'Already used') |
| 7 | form.clearErrors(['email']) |
| 8 | form.watch('email') |
| 9 | form.watchAll() |
| 10 | await form.submit() |
| 11 | const email = form.fieldController('email') |
| 12 | email.onChange('ops@runilib.dev') |
| 13 | email.focus() |
| 14 | await form.saveDraftNow() |
| 15 | await form.clearDraft() |
| 16 | form.visibility.company?.visible |
Complete helper surface
Complete imperative helper surface. Each entry below is exposed on the object returned by useFormBridge() and runs through the same pipeline as the built-in UI (validation, analytics, conditional rules, persistence):
| Method | Type | Description |
|---|---|---|
validate | (name? | name[]) => Promise<boolean> | Trigger validation imperatively. Pass one name, an array, or nothing for the whole form. Resolves true when every targeted field is valid |
resetFields | (partialValues?) => void | Reset to schema defaults (or merge a partial on top). Clears errors, touched, and dirty flags and re-runs conditional rules |
setValue | (name, value) => void | Imperatively write into one field. Goes through the normal change pipeline (validation timing, analytics, conditional re-evaluation) |
getValue | (name) => value | Read one field on demand without subscribing the caller to updates |
getValues | () => Values | Read the full typed value object without subscribing - ideal for building payloads or logging |
setError | (name, message) => void | Push a manual error onto one field. Used to project server-side errors back onto the form |
clearErrors | (name? | name[]) => void | Clear errors for one field, a subset, or the whole form |
watch | (name) => value | Reactive single-field read - subscribes the caller so it re-renders on change |
watchAll | () => Values | Reactive full-values read - heavier than watch, use for summary bars or debug panels |
submit | () => Promise<void> | Imperatively trigger submission through the same pipeline as <Form.Submit> (validation, onSubmit / onError / onSubmitError, analytics) |
fieldController | (name) => Controller | Returns a headless controller for one field (reactive value, error, touched, visible, change/blur/focus handlers, imperative helpers, focus bridge) |
saveDraftNow | () => void | When persist is configured, flush current values to storage immediately, bypassing the debounce window |
clearDraft | () => void | When persist is configured, delete the saved draft for this form |
visibility[name] | { visible, required, disabled } | Computed per-field conditional flags - drive surrounding layout without re-implementing the rule engine |
Field-scoped imperative control
Use form.fieldController(name) when the action belongs to one field rather than the whole form.
- Examples: opening a custom picker, focusing a masked input from another button, mapping server validation back to a single custom field, or building your own review shell around one schema key
Complete fieldController(name) surface:
| Method | Type | Description |
|---|---|---|
name | string | Field name as declared in the schema |
value | unknown | Current field value (reactive) |
label / placeholder / hint | string | Copy strings resolved from the schema |
error | string | undefined | Current error message for this field |
touched / dirty / validating | boolean | Per-field interaction + validation flags |
disabled / required / visible | boolean | Computed conditional flags |
options? | SelectOption[] | Options (select/radio/async) when applicable |
otpLength? | number | OTP length (OTP fields only) |
allValues | Record<string, unknown> | Snapshot of every current form value |
descriptor | FieldDescriptor | Raw descriptor produced by the builder |
renderProps | RenderContext | Context object passed to custom render(fn) hooks |
setValue | (value) => void | Imperative value write (goes through change pipeline) |
onChange | (value) => void | Change handler expected by most controlled inputs |
onBlur / onFocus | () => void | Blur / focus event handlers |
focus / blur | () => void | Imperative focus / blur (uses the focus bridge) |
validate | () => Promise<boolean> | Run validation for this field only |
setError | (message) => void | Push an error on this field |
clearError | () => void | Clear this field error |
registerFocusable | (target) => void | Register a DOM node, TextInput, or { focus?, blur? } object for the focus bridge |