TanStack
API Reference

useInfiniteQuery

Overview

ts
function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): DefinedUseInfiniteQueryResult<TData, TError>;
function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): UseInfiniteQueryResult<TData, TError>;

See also: Parameters · Returns

Call Signature

ts
function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(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 set.

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 set.

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

tsx
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

ts
function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(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:

tsx
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:

tsx
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

PropertyTypeDescription
dataTData | undefinedThe last successfully resolved data for the query.
dataUpdatedAtnumberThe timestamp for when the query most recently returned the status as "success".
errorTError | nullThe error object for the query, if an error was thrown. - Defaults to null.
errorUpdateCountnumberThe sum of all errors.
errorUpdatedAtnumberThe timestamp for when the query most recently returned the status as "error".
failureCountnumberThe failure count for the query. - Incremented every time the query fails. - Reset to 0 when the query succeeds.
failureReasonTError | nullThe 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.
hasNextPagebooleanWill be true if there is a next page to be fetched (known via the getNextPageParam option).
hasPreviousPagebooleanWill be true if there is a previous page to be fetched (known via the getPreviousPageParam option).
isEnabledbooleantrue if this observer is enabled, false otherwise.
isErrorbooleanA derived boolean from the status variable, provided for convenience. - true if the query attempt resulted in an error.
isFetchedbooleanWill be true if the query has been fetched.
isFetchedAfterMountbooleanWill be true if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data.
isFetchingbooleanA derived boolean from the fetchStatus variable, provided for convenience. - true whenever the queryFn is executing, which includes initial pending as well as background refetch.
isFetchingNextPagebooleanWill be true while fetching the next page with fetchNextPage.
isFetchingPreviousPagebooleanWill be true while fetching the previous page with fetchPreviousPage.
isFetchNextPageErrorbooleanWill be true if the query failed while fetching the next page.
isFetchPreviousPageErrorbooleanWill be true if the query failed while fetching the previous page.
isInitialLoadingbooleanDeprecated isInitialLoading is being deprecated in favor of isLoading and will be removed in the next major version.
isLoadingbooleanIs true whenever the first fetch for a query is in-flight. - Is the same as isFetching && isPending.
isLoadingErrorbooleanWill be true if the query failed while fetching for the first time.
isPausedbooleanA derived boolean from the fetchStatus variable, provided for convenience. - The query wanted to fetch, but has been paused.
isPendingbooleanWill be pending if there's no cached data and no query attempt was finished yet.
isPlaceholderDatabooleanWill be true if the data shown is the placeholder data.
isRefetchErrorbooleanWill be true if the query failed while refetching.
isRefetchingbooleanIs true whenever a background refetch is in-flight, which does not include initial pending. - Is the same as isFetching && !isPending.
isStalebooleanWill be true if the data in the cache is invalidated or if the data is older than the given staleTime.
isSuccessbooleanA 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.