useQuery

Bridges TanStack Query with Legend-State. Returns query state as an Observable, and accepts Observable values anywhere in the options — including individual elements inside queryKey. When an observable value changes, the query automatically re-fetches. Options follow TanStack Query’s standard UseQueryOptions — refer to TanStack Query docs for full option details. Each option field accepts MaybeObservable<T> for reactive control.

Both variants require a QueryClientProvider ancestor — the client is injected from context.

Demo

useQuery

Loading

Select a category — the query auto-refetches via Observable queryKey.

electronicsclothingbooks

Fetching...

Refetch

Usage

Basic query

Hook

import { For, Show, useObservable } from "@usels/core";
import { useQuery } from "@usels/tanstack-query";

function ProductList() {
  const query = useQuery({
    queryKey: ["products"],
    queryFn: () => fetch("/api/products").then((r) => r.json()),
  });

  const products$ = useObservable(() => query.data.get() ?? []);

  return (
    <div>
      <Show if={query.isLoading}>
        <p>Loading...</p>
      </Show>
      <Show if={query.isError}>
        <p>Error: {query.error.get()?.message}</p>
      </Show>
      <For each={products$}>{(p$) => <div>{p$.name.get()}</div>}</For>
    </div>
  );
}

Scope

import { For, observable, Show } from "@usels/core";
import { createQuery } from "@usels/tanstack-query";

function ProductList() {
  "use scope";
  const state$ = createQuery({
    queryKey: ["products"],
    queryFn: () => fetch("/api/products").then((r) => r.json()),
  });

  const products$ = observable(() => state$.data.get() ?? []);

  return (
    <div>
      <Show if={state$.isLoading}>
        <p>Loading...</p>
      </Show>
      <Show if={state$.isError}>
        <p>Error: {state$.error.get()?.message}</p>
      </Show>
      <For each={products$}>{(p$) => <div>{p$.name.get()}</div>}</For>
    </div>
  );
}

Observable in queryKey (auto-refetch)

When an element inside queryKey is an Observable, the query automatically re-fetches whenever its value changes. Use .peek() in queryFn to read the current value without registering an extra reactive dependency.

Hook

import { useQuery } from "@usels/tanstack-query";
import { observable } from "@usels/core";

const id$ = observable("1");

function UserProfile() {
  const user$ = useQuery({
    queryKey: ["users", id$],
    queryFn: () => fetchUser(id$.peek()),
  });
  return <p>{user$.data.get()?.name}</p>;
}

Scope

import { createQuery } from "@usels/tanstack-query";
import { observable } from "@usels/core";

const id$ = observable("1");

function UserProfile() {
  "use scope";
  const state$ = createQuery({
    queryKey: ["users", id$],
    queryFn: () => fetchUser(id$.peek()),
  });
  return <p>{state$.data.get()?.name}</p>;
}

The resolved queryKey is a plain array (e.g. ['users', '1']), so cache lookups via queryClient.getQueryData(['users', '1']) work as expected.

Observable inside a nested object in queryKey

Observable values nested inside plain objects within queryKey are also resolved reactively.

Hook

import { useQuery } from "@usels/tanstack-query";
import { observable } from "@usels/core";

const filter$ = observable({ category: "electronics" });

function ProductList() {
  const list$ = useQuery({
    queryKey: ["products", { filter: filter$.category }],
    queryFn: () => fetchProducts(filter$.category.peek()),
  });
  return <div>{list$.data.get()?.length} items</div>;
}

Scope

import { createQuery } from "@usels/tanstack-query";
import { observable } from "@usels/core";

const filter$ = observable({ category: "electronics" });

function ProductList() {
  "use scope";
  const state$ = createQuery({
    queryKey: ["products", { filter: filter$.category }],
    queryFn: () => fetchProducts(filter$.category.peek()),
  });
  return <div>{state$.data.get()?.length} items</div>;
}

Per-field Observable options

Individual options like enabled, staleTime, etc. also accept Observable values.

Hook

import { useQuery } from "@usels/tanstack-query";
import { observable } from "@usels/core";

const enabled$ = observable(false);

function Dashboard() {
  const data$ = useQuery({
    queryKey: ["dashboard"],
    queryFn: fetchDashboard,
    enabled: enabled$,
  });
  return <div>{data$.status.get()}</div>;
}

Scope

import { createQuery } from "@usels/tanstack-query";
import { observable } from "@usels/core";

const enabled$ = observable(false);

function Dashboard() {
  "use scope";
  const state$ = createQuery({
    queryKey: ["dashboard"],
    queryFn: fetchDashboard,
    enabled: enabled$,
  });
  return <div>{state$.status.get()}</div>;
}

Manual refetch

Hook

import { useQuery } from "@usels/tanstack-query";

function DataPanel() {
  const query = useQuery({ queryKey: ["stats"], queryFn: fetchStats });
  return (
    <div>
      <p>Updated: {new Date(query.dataUpdatedAt.get()).toLocaleTimeString()}</p>
      <button onClick={() => query.refetch()}>Refresh</button>
    </div>
  );
}

Scope

import { createQuery } from "@usels/tanstack-query";

function DataPanel() {
  "use scope";
  const state$ = createQuery({ queryKey: ["stats"], queryFn: fetchStats });
  return (
    <div>
      <p>Updated: {new Date(state$.dataUpdatedAt.get()).toLocaleTimeString()}</p>
      <button onClick={() => state$.refetch.get()()}>Refresh</button>
    </div>
  );
}

Type

export type { CreateQueryOptions, QueryState } from "./core";
export { createQuery } from "./core";
/**
 * UseQueryOptions is an alias for CreateQueryOptions for backward compatibility.
 */
export type UseQueryOptions<TData = unknown> = CreateQueryOptions<TData>;
/**
 * Custom hook that bridges TanStack Query with Legend-State.
 * Manages query state as an observable using QueryObserver.
 *
 * Accepts `DeepMaybeObservable<CreateQueryOptions>`, supporting an Observable
 * for the entire options object or for individual fields. Elements inside
 * the queryKey array can also be Observables and will react to changes automatically.
 *
 * @example
 * ```tsx
 * const products$ = useQuery({
 *   queryKey: ['products'],
 *   queryFn: () => fetch('/api/products').then(r => r.json())
 * })
 * ```
 */
export type UseQuery = typeof createQuery;
export declare const useQuery: UseQuery;

Source

View on GitHub