Original fishing-dog mascot for jaspr_hooks jaspr_hooks

useFormState

Subscribe to a selected slice of form state.

Subscribe to a selected slice of form state.

Interactive useFormState demo

Unsaved: false; status: idle; saved:

Navigation requires confirmation: false

Signature and usage

import 'package:jaspr_hooks/form.dart';

final pending = useFormState(form, (state) => state.isSubmitting);
final unsaved = useFormState(form, (state) => state.hasUnsavedChanges);

Ownership and lifecycle

The owning hook disposes subscriptions, validation signals and pending timers on unmount. Use stable keys for a record identity; rebuilds update callbacks without resetting edits. Explicitly reset after loading a different record. Keep request/cache operations in Query.

State and errors

isDirty records whether the user changed values since reset; hasUnsavedChanges compares current values with the last confirmed save. Reverting an edit clears unsaved state while dirty remains true. Field errors retain their onChange, onBlur, onSubmit and onServer source. Keep unknown API violations in the form summary.

Server rendering

Initial values and selected snapshots render on the server. Effects, network submissions, validation and autosave do not execute there. Browser navigation listeners belong to the app adapter, not the portable form module.

Common mistakes

Do not mutate draft objects without a copy strategy. Do not reset from every query refresh or mark newer edits as saved when an older request completes. Handle invalid and uncertain writes explicitly. Autosave does not automatically retry failures. Navigation must use the unsaved baseline and pending/uncertain state, not sticky dirty.

See the form guide for full signatures, typed field lenses, asynchronous validators, error mapping, autosave and routing responsibilities.