Original fishing-dog mascot for jaspr_hooks jaspr_hooks

useQuery

Shared server state with query and mutation hooks.

What it does

Observe typed data with structured keys and a shared QueryClient. Key changes replace the subscription.

Signature and parameters

QueryResult<T> useQuery<T>(QueryOptions<T> options, {QueryClient? client})

Live demo

Interactive useQuery demo

Cached count: 0; fetching: false

Ownership and lifecycle

The app owns QueryClient and disposes it on logout or identity replacement. Hooks remove subscriptions and browser listeners on unmount. The final query unsubscribe cancels in-flight reads and schedules cache garbage collection. Mutation callbacks finish cache updates even after their component unmounts.

Server rendering

Hooks read prefetched data without starting I/O. Restore the dehydrated cache before the first client render. Use a request-scoped server client and explicit codecs; never put tokens into cached data. Mutations cannot execute in SSR hooks.

Common mistakes

Include every input in query keys. Do not mutate cached protobuf objects as form drafts. Read retries require explicit allowlisting and an error classifier; mutations never retry. Repository transports enforce the supplied deadline and register cancellation. Keep uncertain-save and version-conflict handling in the editor.

See the query guide for complete examples, defaults, prefetching, invalidation, optimistic updates and SSR hydration. QueryClientProvider, useQuery, useMutation, useQueryClient and useQueryLifecycle work together.