
jaspr_hooks
Lifecycle, local state, cached queries, mutations and typed form hooks for native Jaspr components.
jaspr_hooks brings the composability of flutter_hooks to Jaspr's own
component and element tree. It does not embed Flutter and produces normal Jaspr
HTML on the server and in the browser.
0.3.0-beta.3is a preview. The API is intentionally being validated in real Jaspr applications before0.3.0.
Install
dependencies:
jaspr: ^0.24.0-beta.0
jaspr_hooks: ^0.3.0-beta.3
This preview supports Dart >=3.13.0 <4.0.0 and Jaspr
>=0.24.0-beta.0 <0.25.0. Jaspr 0.23 applications can keep using
jaspr_hooks: ^0.2.0 with Dart 3.8 or later.
Three modules, one package
| Import | Responsibility |
|---|---|
package:jaspr_hooks/hooks.dart |
Component lifecycle, local state, subscriptions and effects |
package:jaspr_hooks/query.dart |
Cached server state, mutations, retries, hydration and invalidation |
package:jaspr_hooks/form.dart |
Typed drafts, fields, validation, submissions, dirty state and autosave |
The existing jaspr_hooks.dart umbrella remains compatible and exports all three.
Forms do not import queries: submit callbacks can call mutation.mutateAsync, a
repository, or another asynchronous persistence API.
Forms, inspired by TanStack Form
The headless native Dart module follows TanStack Form concepts and naming. Typed field lenses replace TypeScript deep-key inference. It has no JavaScript, schema-library, protobuf, router or design-system dependency.
final form = useForm(FormOptions<String>(
defaultValues: '',
onSubmit: (context) async {
await repository.saveName(context.value);
return const FormSubmitResult.success();
},
));
final name = useField(form, FormFieldKey<String, String>(
'name', read: (value) => value, write: (_, value) => value,
), validators: FieldValidators<String, String>(
onChange: (value, _) => value.trim().isEmpty
? [const FormIssue('Enter a name.', code: 'required')]
: [],
));
final submitting = useFormState(form, (state) => state.isSubmitting);
// Bind name.value, name.handleChange, name.handleBlur and name.meta.errors
// to existing accessible controls. Submit with form.handleSubmit().
- Typed drafts and fields:
FormController<T>,FormFieldKey<T, V>andFieldController<T, V>. Keep partially entered numeric/date text in the draft; parse it through domain validation and request mapping. - Validation: field/form
onChange,onBlur,onSubmitand async equivalents, debounce, linked fields (listenTo), cancellation signals and stale-result protection. Multiple errors can retain indexed paths and backend rule codes. - Error ownership:
errorMapseparates validation events and server errors. Editing one field retains errors on other fields. Put unknown backend paths inFormErrors.form; transport exceptions remain separate from field validation. - Submission:
handleSubmitvalidates, prevents duplicate writes, awaits the callback and records failures. Return.invalid(errors)for server rejection or.uncertain()when a write may have committed;allowRetry()acknowledges uncertainty. Mutations never retry automatically. - Baselines:
isDirtyrecords edit history;isDefaultValuecompares with defaults.hasUnsavedChangescompares against the last confirmed save. Saving an older revision never clears edits made in flight.reset(newValues)is an explicit replacement of the draft and baseline. - Subscriptions:
useFormowns the controller;useFieldanduseFormStatesubscribe consumers. Use stable selectors or an equality function for allocated selections. Defaults changing on rebuild never replace edited values. - Optional autosave:
useFormAutosave/FormAutosavedebounce and serialize writes.canSavecan defer saving while focused; callflush()on blur. Failed revisions remain dirty and require a new edit or explicit retry. - Navigation:
useFormNavigationGuardregisters a live predicate with the router-neutralFormNavigationGuard. App adapters cover routes/history, browser unload and dialog dismissal usingstate.shouldBlockNavigation. - SSR: form hooks do not submit, validate asynchronously, start autosave or register blockers on the server. Subscriptions and timers dispose on unmount.
Use immutable drafts or supply FormOptions.copy and equals. Backend mapping,
localization, focus management and business validation stay in app adapters;
transport deadlines and cache updates stay in mutations. See the
forms guide.
API state management, inspired by React Query
jaspr_hooks also provides query and mutation hooks for API data, inspired by
TanStack Query (React Query).
Use useQuery for server reads and useMutation for writes, with a shared
QueryClient managing the cache independently of your components.
- Keyed caching and request deduplication: components with the same
QueryKeyshare data and in-flight requests. - Freshness and revalidation: configure
staleTime, inactive-cachegcTime, polling, and refetching on mount, window focus, or reconnection. - Query and mutation state: distinguish initial loading from background fetching, retain cached data while refetching, and expose success/error state.
- Writes and invalidation: update cached results, invalidate key prefixes, and use mutation callbacks for optimistic updates and rollback.
- Cancellation, deadlines, and read retries: propagate cancellation and per-attempt deadlines to your transport. Retries require an explicit read-only declaration and an error classifier; mutations never retry automatically.
- SSR and hydration: prefetch into a request-scoped cache, serialize typed data and fetch timestamps, then restore the cache before browser hydration.
// Inside a HookComponent beneath QueryClientProvider:
final client = useQueryClient();
final productsKey = QueryKey(['products']);
final products = useQuery(QueryOptions<List<Product>>(
key: productsKey,
queryFn: (context) => repository.listProducts(
signal: context.signal,
timeout: context.timeout,
),
));
final saveProduct = useMutation(MutationOptions<Product, ProductDraft>(
mutationFn: (draft, context) => repository.saveProduct(
draft,
timeout: context.timeout,
),
onSuccess: (_, _, _) => client.invalidateQueries(productsKey),
));
// Read products.data / products.isLoading / products.isFetching / products.error.
// Call saveProduct.mutate(draft), or await saveProduct.mutateAsync(draft).
The app owns the QueryClient: provide it with QueryClientProvider, call
useQueryLifecycle(client) once in the browser shell, and dispose it on logout
or identity changes. Server rendering uses a separate client for each request.
Keep editable form drafts separate from cached server data.
These APIs implement the server-state model in native Dart, following Jaspr's component lifecycle. The linked guide describes the supported behavior. See the query and mutation guide for cache setup, repositories, transport integration, and SSR examples.
A counter without a State class
import 'package:jaspr/dom.dart';
import 'package:jaspr/jaspr.dart';
import 'package:jaspr_hooks/jaspr_hooks.dart';
class Counter extends HookComponent {
const Counter({super.key});
@override
Component build(BuildContext context) {
final count = useState(0);
return button(
onClick: () => count.value++,
[Component.text('Count: ${count.value}')],
);
}
}
Hooks must be called unconditionally and in the same order on every build.
Reusable custom hooks are ordinary functions whose names begin with use:
ValueNotifier<int> useTrackedCount([int initialValue = 0]) {
return useState(initialValue);
}
For lower-level lifecycle objects, extend Hook<R> and
HookState<R, YourHook> and register them with use.
Included hooks
| Category | Hooks |
|---|---|
| Framework | use, useContext, useId, useEvent |
| Foundation | useLatest, useDisposable, useExternalStore, useInherited, useImperativeHandle, useTimeout, useInterval |
| Primitives | useState, useGuardedState, useEffect, usePostFrameEffect, useMemoized, useCallback, useRef, useValueChanged |
| Lifecycle/state | usePrevious, useReducer, useIsMounted, useDebounced |
| Convenience state | useToggle, useCounter, useList, useMap, useSet, useQueue, useEffectOnce, useMount, useUnmount, useUpdateEffect, usePostFrameUpdateEffect |
| API/server state | useQuery, useMutation, useQueryClient, useQueryLifecycle |
| Async | useFuture, useStream, useStreamController, useOnStreamChange |
| Actions | useAsyncAction, useOptimistic |
| Listenables | useListenable, useListenableSelector, useValueNotifier, useValueListenable, useOnListenableChange |
| Browser lifecycle | useDocumentVisibility, useOnDocumentVisibilityChange, usePreferredColorScheme, useOnPreferredColorSchemeChange, useMediaQuery, useOnMediaQueryChange, usePreferredMotion, useOnPreferredMotionChange, useLocation, useBrowserRoute, useOnWindowFocus |
| Browser DOM | useNodeKey, useFocus, useFocusWithin, useActiveElement, useAbortController, useAnimationFrame, useHistoryState, useClipboard, useElementSize, useWindowSize, useIntersection, useEventListener, useOnClickOutside, useHover, useMutationObserver |
The universal entry point contains every hook except direct DOM integrations:
import 'package:jaspr_hooks/jaspr_hooks.dart';
When a component needs DOM node, observer, or native-event types, import the web entry point instead. It re-exports the universal API:
import 'package:jaspr_hooks/web.dart';
import 'package:universal_web/web.dart' as web;
Use HookComponent in place of StatelessComponent,
StatefulHookComponent when a Jaspr State is still useful, or HookBuilder
for a small hook-enabled subtree.
Server rendering and hydration
Jaspr renders a new component tree on the server and hydrates with a separate tree in the browser. Hook state is therefore not serialized automatically.
For IDs inside a hydrated @client boundary, put a HookIdScope above the
hook host and pass its document-unique seed as a serialized property:
return HookIdScope(
seed: idScope,
child: HookBuilder(builder: (_) {
final id = useId();
return Component.element(tag: 'input', id: id);
}),
);
Nested client islands need their own scopes. Unscoped useId values require
matching complete element trees to match across server and client.
Await server data in AsyncStatelessComponent or AsyncBuilder, then return a
synchronous hook host. StatefulHookComponent also works with Jaspr's
PreloadStateMixin. Ordinary Jaspr async builds do not establish a hook session. Keep
server children mounted in the initial HTML and toggle their visibility from
the client wrapper. See the server components guide.
useDisposable cleanup follows replacement and element unmounting. Server
response completion does not guarantee unmount; manage request resources
explicitly with try/finally in their caller.
Development hot reload preserves matching state, refs, IDs and node keys.
Memoized values, callbacks, effects and disposable resources refresh on the
next build; custom hooks can override HookState.reassemble. Use hot restart
for structural hook changes. See the hot reload guide.
Experimental AsyncHookComponent and AsyncHookBuilder support hooks across
sequential awaits in server scope:
import 'package:jaspr/server.dart';
import 'package:jaspr_hooks/server.dart';
class UserDetails extends AsyncHookComponent {
const UserDetails({required this.userId, super.key});
final String userId;
@override
Future<Component> build(BuildContext context) async {
final source = useRef(userId);
final user = await loadUser(source.value);
final label = useMemoized(() => formatUser(user), [user]);
return Component.text(label);
}
}
Each build has its own session, which closes on completion, failure or unmount. Call hooks in one awaited chain; parallel branches and detached callbacks must not call hooks. State hooks are read-only initial snapshots, effects stay inactive, and live Future/Stream sources remain unsupported. Successful builds retain resources until unmount; request cleanup remains caller-owned. See the async server hooks guide.
| API | Server/static rendering | Browser |
|---|---|---|
useEffect |
Effect is skipped | Runs synchronously during build; state it assigns renders after the frame |
usePostFrameEffect, usePostFrameUpdateEffect |
Effect is skipped | Runs after the frame |
useFuture, useStream, useOnStreamChange |
Source must be null |
Subscribes normally |
| Listenable hooks | Read initial value, attach no listener | Attach listeners |
useDebounced, useTimeout, useInterval |
Create no timer | Run timers normally |
useExternalStore |
Reads getServerSnapshot, or getSnapshot without one |
Hydrates from the server snapshot, then subscribes |
| Async and optimistic actions | Read deterministic initial state; do not mutate | Dispatch and mutate from event handlers |
| Browser lifecycle value hooks | Return unknown |
Synchronize after the first frame |
useLocation, useBrowserRoute |
Return null or the server route |
Synchronize after the first frame |
| Browser DOM value hooks | Return inert state, null, or an unattached key |
Attach after the first frame |
Pass async sources conditionally:
final future = useMemoized(
() => kIsWeb ? loadFromBrowser() : null,
const [],
);
final snapshot = useFuture(future);
Use Jaspr's PreloadStateMixin, AsyncStatelessComponent, serialized
@client properties, or jaspr_riverpod for server-loaded data. Keep initial
state and memoized values deterministic so the server and first client build
produce compatible markup.
Use usePostFrameEffect for DOM reads or writes. useEffect intentionally
matches flutter_hooks synchronous client timing.
Differences from flutter_hooks
flutter_hooks cannot be imported by native Jaspr components because its
runtime is coupled to Flutter widgets and elements. This package adapts its
ordered-hook design to public Jaspr element APIs.
- Jaspr
Component,BuildContext,ValueNotifier,AsyncSnapshot, andConnectionStatereplace Flutter types. - Effects and live subscriptions are SSR-aware.
- Document visibility and preferred color scheme replace Flutter application lifecycle and platform brightness hooks.
- Flutter animation, ticker, scroll, focus, text editing, overlay, Material,
Cupertino, keep-alive, controller, and
reassemblehooks are intentionally absent. - The internal element mixin is not public;
HookandHookStateare the supported custom-hook extension points.
Documentation and example
The example/ directory is a static Jaspr Content application with
one guide and interactive demo for every hook. It is also the source deployed
to GitHub Pages and displayed in pub.dev's Example tab.
AI coding agents
The documentation home page includes an AI install prompt button that copies compatibility, installation, hook-rule, and SSR instructions for a coding agent.
The machine reference documents every exported hook and is checked against the canonical hook catalog and package version constraints in CI.
Status and releases
pub.dev releases are prepared by the repository's release checks and published manually from a clean local checkout.
Credits and license
jaspr_hooks is inspired by and partially adapted from
flutter_hooks, copyright
Remi Rousselet, under the MIT License. The exact source baseline and full
license are recorded in THIRD_PARTY_NOTICES.md.
This is an independent project. It is not maintained, sponsored, or endorsed
by the Jaspr or flutter_hooks projects. The fishing-dog artwork is an original
project mascot and is not derived from Jaspr's mascot.
The package itself is available under the MIT License in LICENSE.
Libraries
- form
- Headless typed forms, validation, submission and optional autosave.
- hooks
- Component lifecycle and local-state hooks, independent of queries and forms.
- jaspr_hooks
- Ordered lifecycle and state hooks for native Jaspr components.
- query
- Cached server state, queries, mutations and hydration.
- server
- Experimental server-only async hook hosts for Jaspr.
- web
- Jaspr hooks that integrate with browser DOM APIs.