--- id: useQuery title: useQuery redirect_from: - framework/solid/reference/useQuery --- ## Overview ```ts function useQuery(options: DefinedInitialDataOptions, queryClient?: () => QueryClient): DefinedUseQueryResult; function useQuery(options: UndefinedInitialDataOptions, queryClient?: () => QueryClient): UseQueryResult; ``` - [`DefinedInitialDataOptions` → `DefinedUseQueryResult`](#call-signature-1): 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. - [`UndefinedInitialDataOptions` → `UseQueryResult`](#call-signature-2): 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](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts function useQuery(options: DefinedInitialDataOptions, queryClient?: () => QueryClient): DefinedUseQueryResult; ``` Defined in: [packages/solid-query/src/useQuery.ts:57](https://github.com/TanStack/query/blob/main/packages/solid-query/src/useQuery.ts#L57) 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 known to be defined, 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`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> An accessor returning the [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`, with `initialData` known to be defined. #### queryClient? () => [`QueryClient`](../classes/QueryClient.md) An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context will be used. ### Returns [`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`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](queryOptions.md) to share these options between `useQuery` and imperative APIs like `queryClient.query`. ### Example ```tsx 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 (
{postsQuery.isError ? Error: {postsQuery.error.message} : null}
    {(post) =>
  • {post.title}
  • }
) } ``` ## Call Signature ```ts function useQuery(options: UndefinedInitialDataOptions, queryClient?: () => QueryClient): UseQueryResult; ``` Defined in: [packages/solid-query/src/useQuery.ts:228](https://github.com/TanStack/query/blob/main/packages/solid-query/src/useQuery.ts#L228) 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`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> An accessor returning the [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. #### queryClient? () => [`QueryClient`](../classes/QueryClient.md) An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context will be used. ### Returns [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`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](queryOptions.md) to share these options between `useQuery` and imperative APIs like `queryClient.query`. ### Examples ```tsx import { For, Match, Switch } from 'solid-js' import { useQuery } from '@tanstack/solid-query' function Posts() { const postsQuery = useQuery(() => ({ queryKey: ['posts'], queryFn: fetchPosts, })) return ( Loading... Error: {postsQuery.error.message}
    {(post) =>
  • {post.title}
  • }
{postsQuery.isFetching ? 'Background Updating...' : ' '}
) } ``` `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`: ```tsx 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 ( Loading... Error: {postsQuery.error.message} {postsQuery.data} posts ) } ``` A dependent query, only enabled once `postId` is set: ```tsx 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 ( {postQuery.data?.title}}> Select a post Loading... Error: {postQuery.error.message} ) } ``` 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: ```tsx 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 ( {postQuery.data?.title}}> Select a post Loading... Error: {postQuery.error.message} ) } ``` 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: ```tsx 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>(['posts']) ?.find((post) => post.id === props.postId), initialDataUpdatedAt: () => queryClient.getQueryState(['posts'])?.dataUpdatedAt, })) return postQuery.isError ? Error: {postQuery.error.message} :

{postQuery.data?.title}

} ``` Paginated data, keeping the previous page's data visible while the next page loads: ```tsx 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 (
    {(post) =>
  • {post.title}
  • }
) } ``` ## Parameters ### options [`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> An accessor returning the [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. #### `options` properties Built from [`QueryOptions`](../interfaces/QueryOptions.md#properties). See the type above for what it changes. ### queryClient? () => [`QueryClient`](../classes/QueryClient.md) An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context will be used. ## Returns [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`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. ### 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](https://tanstack.com/query/latest/docs/framework/react/guides/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`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`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. |