* docs(query-core/types): describe 'status', 'isPending', 'isSuccess' and 'isError' of the query result by its current data and error
* docs(query-core/types): describe 'isLoadingError', 'isRefetchError' and the error result types by the current data and error, including 'select' failures
* docs(query-core/types): note that 'isRefetchError' is 'false' after a failed page fetch in infinite queries
* docs({query-core,react,preact,vue,solid,svelte,angular}-query): describe 'success' and 'pending' by cached data and 'placeholderData' since 'select' can return 'undefined'
* docs({query-core,react,preact,vue,solid,svelte,angular}-query): describe 'success' by cached data or data from 'placeholderData', and limit the 'select' returning 'undefined' case to cached data
* docs(docs/framework): revert generated reference pages to leave them to the post-merge workflow
* docs(docs/framework): regenerate reference pages with 'generate-docs'
18 KiB
| id | title | redirect_from | |
|---|---|---|---|
| useInfiniteQuery | useInfiniteQuery |
|
Overview
function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): DefinedUseInfiniteQueryResult<TData, TError>;
function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): UseInfiniteQueryResult<TData, TError>;
DefinedInitialDataInfiniteOptions→DefinedUseInfiniteQueryResult: The options foruseInfiniteQueryare identical touseQuery, with the addition ofinitialPageParam,getNextPageParam,getPreviousPageParam, andmaxPages.UndefinedInitialDataInfiniteOptions→UseInfiniteQueryResult: The options foruseInfiniteQueryare identical touseQuery, with the addition ofinitialPageParam,getNextPageParam,getPreviousPageParam, andmaxPages.
See also: Parameters · Returns
Call Signature
function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): DefinedUseInfiniteQueryResult<TData, TError>;
Defined in: packages/solid-query/src/useInfiniteQuery.ts:68
The options for useInfiniteQuery are identical to useQuery, with the addition of
initialPageParam, getNextPageParam, getPreviousPageParam, and maxPages.
This overload is selected when initialData is known to be defined.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = InfiniteData<TQueryFnData, unknown>
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
Parameters
options
DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
An accessor returning the DefinedInitialDataInfiniteOptions to use — everything
you can pass to useInfiniteQuery, with initialData known to be defined.
queryClient?
Accessor<QueryClient>
An accessor for a custom QueryClient. Otherwise, the one from the nearest context
will be used.
Returns
DefinedUseInfiniteQueryResult<TData, TError>
The same properties as useQuery, with the addition of fetchNextPage, fetchPreviousPage,
hasNextPage, hasPreviousPage, isFetchingNextPage, and isFetchingPreviousPage. data.pages and
data.pageParams are also added, as long as a select doesn't change TData away from its default
InfiniteData<TQueryFnData> shape.
Remarks
Keep in mind that imperative fetch calls, such as fetchNextPage, may interfere with the default
refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
actions, or add conditions like hasNextPage && !isFetching.
See
infiniteQueryOptions to share these options between useInfiniteQuery and imperative APIs like queryClient.infiniteQuery.
Example
import { For } from 'solid-js'
import { useInfiniteQuery } from '@tanstack/solid-query'
function Projects() {
// `projectsQuery.data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
// list stays visible alongside the error.
const projectsQuery = useInfiniteQuery(() => ({
queryKey: ['projects'],
queryFn: ({ pageParam }) => fetchProjects(pageParam),
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.nextId,
initialData: { pages: [], pageParams: [] },
}))
return (
<div>
{projectsQuery.isError ? <span>Error: {projectsQuery.error.message}</span> : null}
<ul>
<For each={projectsQuery.data.pages}>
{(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
</For>
</ul>
</div>
)
}
Call Signature
function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): UseInfiniteQueryResult<TData, TError>;
Defined in: packages/solid-query/src/useInfiniteQuery.ts:184
The options for useInfiniteQuery are identical to useQuery, with the addition of
initialPageParam, getNextPageParam, getPreviousPageParam, and maxPages.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = InfiniteData<TQueryFnData, unknown>
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
Parameters
options
UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
An accessor returning the UndefinedInitialDataInfiniteOptions to use — everything
you can pass to useInfiniteQuery.
queryClient?
Accessor<QueryClient>
An accessor for a custom QueryClient. Otherwise, the one from the nearest context
will be used.
Returns
UseInfiniteQueryResult<TData, TError>
The same properties as useQuery, with the addition of fetchNextPage, fetchPreviousPage,
hasNextPage, hasPreviousPage, isFetchingNextPage, and isFetchingPreviousPage. data.pages and
data.pageParams are also added, as long as a select doesn't change TData away from its default
InfiniteData<TQueryFnData> shape.
Remarks
Keep in mind that imperative fetch calls, such as fetchNextPage, may interfere with the default
refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
actions, or add conditions like hasNextPage && !isFetching.
See
infiniteQueryOptions to share these options between useInfiniteQuery and imperative APIs like queryClient.infiniteQuery.
Examples
Fetching the next page from a "Load More" button click:
import { For, Match, Switch } from 'solid-js'
import { useInfiniteQuery } from '@tanstack/solid-query'
function Projects() {
const projectsQuery = useInfiniteQuery(() => ({
queryKey: ['projects'],
queryFn: ({ pageParam }) => fetchProjects(pageParam),
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.nextId,
}))
return (
<Switch>
<Match when={projectsQuery.isPending}>Loading...</Match>
<Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
<Match when={projectsQuery.isSuccess}>
<ul>
<For each={projectsQuery.data.pages}>
{(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
</For>
</ul>
<button
onClick={() => projectsQuery.fetchNextPage()}
disabled={!projectsQuery.hasNextPage || projectsQuery.isFetching}
>
{projectsQuery.isFetchingNextPage
? 'Loading more...'
: projectsQuery.hasNextPage
? 'Load More'
: 'Nothing more to load'}
</button>
</Match>
</Switch>
)
}
Fetching the next page automatically as the user scrolls, using an IntersectionObserver on a
sentinel element after the list:
import { For, Match, Switch, createEffect, onCleanup } from 'solid-js'
import { useInfiniteQuery } from '@tanstack/solid-query'
function Projects() {
const projectsQuery = useInfiniteQuery(() => ({
queryKey: ['projects'],
queryFn: ({ pageParam }) => fetchProjects(pageParam),
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.nextId,
}))
let sentinelRef: HTMLDivElement | undefined
createEffect(() => {
if (sentinelRef == null || !projectsQuery.hasNextPage || projectsQuery.isFetching) return
const observer = new IntersectionObserver(([entry]) => {
if (entry?.isIntersecting) projectsQuery.fetchNextPage()
})
observer.observe(sentinelRef)
onCleanup(() => observer.disconnect())
})
return (
<Switch>
<Match when={projectsQuery.isPending}>Loading...</Match>
<Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
<Match when={projectsQuery.isSuccess}>
<ul>
<For each={projectsQuery.data.pages}>
{(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
</For>
</ul>
<div ref={sentinelRef}>{projectsQuery.isFetchingNextPage ? 'Loading more...' : null}</div>
</Match>
</Switch>
)
}
Parameters
options
UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
An accessor returning the UndefinedInitialDataInfiniteOptions to use — everything
you can pass to useInfiniteQuery.
options properties
Built from InfiniteQueryOptions. See the type above for what it changes.
queryClient?
Accessor<QueryClient>
An accessor for a custom QueryClient. Otherwise, the one from the nearest context
will be used.
Returns
UseInfiniteQueryResult<TData, TError>
The same properties as useQuery, with the addition of fetchNextPage, fetchPreviousPage,
hasNextPage, hasPreviousPage, isFetchingNextPage, and isFetchingPreviousPage. data.pages and
data.pageParams are also added, as long as a select doesn't change TData away from its default
InfiniteData<TQueryFnData> shape.
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. |
fetchNextPage |
(options?: FetchNextPageOptions) => Promise<InfiniteQueryObserverResult<TData, TError>> |
This function allows you to fetch the next "page" of results. |
fetchPreviousPage |
(options?: FetchPreviousPageOptions) => Promise<InfiniteQueryObserverResult<TData, TError>> |
This function allows you to fetch the previous "page" of results. |
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. |
hasNextPage |
boolean |
Will be true if there is a next page to be fetched (known via the getNextPageParam option). |
hasPreviousPage |
boolean |
Will be true if there is a previous page to be fetched (known via the getPreviousPageParam option). |
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 has an error from a fetch that failed after its retries, or if select threw. |
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. |
isFetchingNextPage |
boolean |
Will be true while fetching the next page with fetchNextPage. |
isFetchingPreviousPage |
boolean |
Will be true while fetching the previous page with fetchPreviousPage. |
isFetchNextPageError |
boolean |
Will be true if the query failed while fetching the next page. |
isFetchPreviousPageError |
boolean |
Will be true if the query failed while fetching the previous page. |
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 has an error and no data to display. |
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 true if the query has no cached data, no data from placeholderData and no error. |
isPlaceholderData |
boolean |
Will be true if the data shown is the placeholder data. |
isRefetchError |
boolean |
Will be true if the query has an error and still has data to display (for infinite queries, not after a failed page fetch). |
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 cached data or data from placeholderData, and no error. |
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: - error if the query has an error from a fetch that failed after its retries, or if select threw. - success if the query has cached data (even if select returns undefined) or data from placeholderData, and no error. - pending otherwise, since the query has no cached data, no data from placeholderData and no error. |