#useQuery

#Import

typescript

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

#Overview

Hook for declarative data fetching with automatic execution and refetch.

Thin wrapper over 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 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  { 4    handler: async ({ signal }) => { 5      const res = await client.fetch("/api/users", { signal }); 6      return res.data; 7    }, 8  }, 9  [],10);

Re-fetch when a dep changes

tsx

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

Polling

tsx

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