alepha@docs:~/docs/reference/react-hooks$
cat useQuery.md | pretty
1 min read
Last commit:

#useQuery

#Import

typescript 
1import { useQuery } from "alepha/react";

#Overview

Hook for declarative data fetching with automatic execution and refetch.

Thin wrapper over {@link useAction}: it pre-applies runOnInit: true, exposes the last result as data, and provides a stable refetch() to re-run the query on demand. For optimistic mutations and side-effects, use {@link useAction} directly — useQuery is for the read path.

Request deduplication and AbortSignal cancellation come from useAction + HttpClient.

Pass a key to opt into the shared query cache: components using the same key read one entry rather than each fetching, staleTime serves a fresh entry without hitting the network, and a mutation declaring invalidates: [["folios"]] drops every entry under that prefix and makes mounted queries refetch. The cache lives in a registered atom, so server-rendered results hydrate on the client for free.

Without a key, none of that applies and the hook behaves exactly as it always has — no cache reads, no cache writes, no shared state.

#Examples

Basic

tsx 
1const client = useInject(HttpClient);2const { data, loading, error, refetch } = useQuery({3  handler: async ({ signal }) => {4    const res = await client.fetch("/api/users", { signal });5    return res.data;6  },7}, []);

Re-fetch when a dep changes

tsx 
1const { data } = useQuery({2  handler: async () => api.getUser(userId),3}, [userId]);

Polling

tsx 
1const { data } = useQuery({2  handler: async () => api.getStatus(),3  runEvery: [5, "seconds"],4}, []);