0
Fork 0
mirror of https://github.com/TanStack/query.git synced 2026-11-18 19:33:22 +00:00
query/docs/framework/solid/reference/functions/useQuery.md
Wonsuk Choi f38e6271b4
chore(*): update '@tanstack/typedoc-config' to v0.3.5 (#12035)
* chore(scripts/generate-docs): read type alias bodies whose type parameters have defaults

* chore(*): update '@tanstack/typedoc-config' to v0.3.5
2026-10-17 11:14:03 +09:00

16 KiB

id title redirect_from
useQuery useQuery
framework/solid/reference/useQuery

Overview

function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): UseQueryResult<TData, TError>;
function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): DefinedUseQueryResult<TData, TError>;
  • UndefinedInitialDataOptions → UseQueryResult: Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — enabled: false skips the initial fetch.
  • DefinedInitialDataOptions → DefinedUseQueryResult: Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — enabled: false skips the initial fetch.

See also: Parameters · Returns

Call Signature

function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): UseQueryResult<TData, TError>;

Defined in: packages/solid-query/src/useQuery.ts:178

Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — enabled: false skips the initial fetch.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>

An accessor returning the UndefinedInitialDataOptions to use — everything you can pass to useQuery.

queryClient?

() => QueryClient

An accessor for a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns

UseQueryResult<TData, TError>

The current query result, as a Solid store. status is pending if there is no cached data to display, error if the last fetch attempt failed, or success if the query has data to display. isPending/isSuccess/isError are derived booleans for convenience.

See

queryOptions to share these options between useQuery and imperative APIs like queryClient.query.

Examples

import { For, Match, Switch } from 'solid-js'
import { useQuery } from '@tanstack/solid-query'

function Posts() {
  const postsQuery = useQuery(() => ({
    queryKey: ['posts'],
    queryFn: fetchPosts,
  }))

  return (
    <Switch>
      <Match when={postsQuery.isPending}>Loading...</Match>
      <Match when={postsQuery.isError}>Error: {postsQuery.error.message}</Match>
      <Match when={postsQuery.isSuccess}>
        <ul>
          <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
        </ul>
        <div>{postsQuery.isFetching ? 'Background Updating...' : ' '}</div>
      </Match>
    </Switch>
  )
}

select derives whatever data a component needs from the cached value, without changing what's actually stored in the cache — the cache still holds the full Post[], but data here is a number:

import { Match, Switch } from 'solid-js'
import { useQuery } from '@tanstack/solid-query'

function PostCount() {
  const postsQuery = useQuery(() => ({
    queryKey: ['posts'],
    queryFn: fetchPosts,
    select: (posts) => posts.length,
  }))

  return (
    <Switch>
      <Match when={postsQuery.isPending}>Loading...</Match>
      <Match when={postsQuery.isError}>Error: {postsQuery.error.message}</Match>
      <Match when={postsQuery.isSuccess}>{postsQuery.data} posts</Match>
    </Switch>
  )
}

A dependent query, only enabled once postId is set:

import { Match, Switch } from 'solid-js'
import { useQuery } from '@tanstack/solid-query'

function Post(props: { postId: number | undefined }) {
  const postQuery = useQuery(() => ({
    queryKey: ['post', props.postId],
    queryFn: () => fetchPost(props.postId!),
    enabled: props.postId != null,
  }))

  return (
    <Switch fallback={<h1>{postQuery.data?.title}</h1>}>
      <Match when={props.postId == null}>Select a post</Match>
      <Match when={postQuery.isLoading}>Loading...</Match>
      <Match when={postQuery.isError}>Error: {postQuery.error.message}</Match>
    </Switch>
  )
}

The same dependent query, using skipToken to disable it in a type-safe way instead of relying on enabled. The non-null assertion is still needed — Solid's props narrowing doesn't survive into the queryFn closure the way a local const would — but skipToken keeps queryFn's return type accurate without it. refetch doesn't work while queryFn is skipToken — use enabled: false instead if you need to trigger the query manually:

import { Match, Switch } from 'solid-js'
import { skipToken, useQuery } from '@tanstack/solid-query'

function Post(props: { postId: number | undefined }) {
  const postQuery = useQuery(() => ({
    queryKey: ['post', props.postId],
    queryFn: props.postId != null ? () => fetchPost(props.postId!) : skipToken,
  }))

  return (
    <Switch fallback={<h1>{postQuery.data?.title}</h1>}>
      <Match when={props.postId == null}>Select a post</Match>
      <Match when={postQuery.isLoading}>Loading...</Match>
      <Match when={postQuery.isError}>Error: {postQuery.error.message}</Match>
    </Switch>
  )
}

Seeding a detail query from an already-cached list, to skip the loading state. initialDataUpdatedAt carries over the list's own fetch time, so that if you set a staleTime, it's measured from when the list was fetched rather than from now:

import { useQuery, useQueryClient } from '@tanstack/solid-query'

function Post(props: { postId: number }) {
  const queryClient = useQueryClient()

  const postQuery = useQuery(() => ({
    queryKey: ['post', props.postId],
    queryFn: () => fetchPost(props.postId),
    initialData: () =>
      queryClient
        .getQueryData<Array<Post>>(['posts'])
        ?.find((post) => post.id === props.postId),
    initialDataUpdatedAt: () =>
      queryClient.getQueryState(['posts'])?.dataUpdatedAt,
  }))

  return postQuery.isError ? <span>Error: {postQuery.error.message}</span> : <h1>{postQuery.data?.title}</h1>
}

Paginated data, keeping the previous page's data visible while the next page loads:

import { For, createSignal } from 'solid-js'
import { keepPreviousData, useQuery } from '@tanstack/solid-query'

function Posts() {
  const [page, setPage] = createSignal(0)

  const postsQuery = useQuery(() => ({
    queryKey: ['posts', page()],
    queryFn: () => fetchPosts(page()),
    placeholderData: keepPreviousData,
  }))

  return (
    <div>
      <ul>
        <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
      </ul>
      <button
        disabled={postsQuery.isPlaceholderData}
        onClick={() => setPage((old) => old + 1)}
      >
        Next Page
      </button>
    </div>
  )
}

Call Signature

function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): DefinedUseQueryResult<TData, TError>;

Defined in: packages/solid-query/src/useQuery.ts:228

Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — enabled: false skips the initial fetch.

This overload is selected when initialData is set, so the resulting data is never undefined (unless a select changes TData to include undefined).

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>

An accessor returning the DefinedInitialDataOptions to use — everything you can pass to useQuery, with initialData set.

queryClient?

() => QueryClient

An accessor for a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns

DefinedUseQueryResult<TData, TError>

The current query result, as a Solid store, typed so that status is success — or error if a fetch attempt fails while keeping the existing data (status never resolves to pending in this overload's type, since initialData guarantees data upfront). isSuccess/isError are derived booleans for convenience.

See

queryOptions to share these options between useQuery and imperative APIs like queryClient.query.

Example

import { For } from 'solid-js'
import { useQuery } from '@tanstack/solid-query'

function Posts() {
  // `postsQuery.data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
  // list stays visible alongside the error.
  const postsQuery = useQuery(() => ({
    queryKey: ['posts'],
    queryFn: fetchPosts,
    initialData: [],
  }))

  return (
    <div>
      {postsQuery.isError ? <span>Error: {postsQuery.error.message}</span> : null}
      <ul>
        <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
      </ul>
    </div>
  )
}

Parameters

options

DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>

An accessor returning the DefinedInitialDataOptions to use — everything you can pass to useQuery, with initialData set.

options properties

Built from QueryOptions. See the type above for what it changes.

queryClient?

() => QueryClient

An accessor for a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns

DefinedUseQueryResult<TData, TError>

The current query result, as a Solid store, typed so that status is success — or error if a fetch attempt fails while keeping the existing data (status never resolves to pending in this overload's type, since initialData guarantees data upfront). isSuccess/isError are derived booleans for convenience.

Result properties

Property Type Description
data TData | undefined The last successfully resolved data for the query.
dataUpdatedAt number The timestamp for when the query most recently returned the status as "success".
error TError | null The error object for the query, if an error was thrown. - Defaults to null.
errorUpdateCount number The sum of all errors.
errorUpdatedAt number The timestamp for when the query most recently returned the status as "error".
failureCount number The failure count for the query. - Incremented every time the query fails. - Reset to 0 when the query succeeds.
failureReason TError | null The failure reason for the query retry. - Reset to null when the query succeeds.
fetchStatus "fetching" | "paused" | "idle" The fetch status of the query. - fetching: Is true whenever the queryFn is executing, which includes initial pending as well as background refetch. - paused: The query wanted to fetch, but has been paused. - idle: The query is not fetching. - See Network Mode for more information.
isEnabled boolean true if this observer is enabled, false otherwise.
isError boolean A derived boolean from the status variable, provided for convenience. - true if the query attempt resulted in an error.
isFetched boolean Will be true if the query has been fetched.
isFetchedAfterMount boolean Will be true if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data.
isFetching boolean A derived boolean from the fetchStatus variable, provided for convenience. - true whenever the queryFn is executing, which includes initial pending as well as background refetch.
isInitialLoading boolean Deprecated isInitialLoading is being deprecated in favor of isLoading and will be removed in the next major version.
isLoading boolean Is true whenever the first fetch for a query is in-flight. - Is the same as isFetching && isPending.
isLoadingError boolean Will be true if the query failed while fetching for the first time.
isPaused boolean A derived boolean from the fetchStatus variable, provided for convenience. - The query wanted to fetch, but has been paused.
isPending boolean Will be pending if there's no cached data and no query attempt was finished yet.
isPlaceholderData boolean Will be true if the data shown is the placeholder data.
isRefetchError boolean Will be true if the query failed while refetching.
isRefetching boolean Is true whenever a background refetch is in-flight, which does not include initial pending. - Is the same as isFetching && !isPending.
isStale boolean Will be true if the data in the cache is invalidated or if the data is older than the given staleTime.
isSuccess boolean A derived boolean from the status variable, provided for convenience. - true if the query has received a response with no errors and is ready to display its data.
refetch (options?: RefetchOptions) => Promise<QueryObserverResult<TData, TError>> A function to manually refetch the query.
status "error" | "pending" | "success" The status of the query. - Will be: - pending if there's no cached data and no query attempt was finished yet. - error if the query attempt resulted in an error. - success if the query has received a response with no errors and is ready to display its data.