v2.6.0

[markerikson]

This feature release adds infinite query support to RTK Query.

Changelog

RTK Query Infinite Query support

Since we first released RTK Query in 2021, we've had users asking us to add support for "infinite queries" - the ability to keep fetching additional pages of data for a given endpoint. It's been by far our most requested feature. Until recently, our answer was that we felt there were too many use cases to support with a single API design approach.

Last year, we revisited this concept and concluded that the best approach was to mimic the flexible infinite query API design from React Query. We had additional discussions with @TkDodo , who described the rationale and implementation approach and encouraged us to use their API design, and @riqts provided an initial implementation on top of RTKQ's existing internals.

We're excited to announce that this release officially adds full infinite query endpoint support to RTK Query!

Using Infinite Queries

As with React Query, the API design is based around "page param" values that act as the query arguments for fetching a specific page for the given cache entry.

Infinite queries are defined with a new build.infiniteQuery() endpoint type. It accepts all of the same options as normal query endpoints, but also needs an additional infiniteQueryOptions field that specifies the infinite query behaviors. With TypeScript, you must supply 3 generic arguments: build.infiniteQuery<ResultType, QueryArg, PageParam>, where ResultType is the contents of a single page, QueryArg is the type passed in as the cache key, and PageParam is the value used to request a specific page.

The endpoint must define an initialPageParam value that will be used as the default (and can be overridden if desired). It also needs a getNextPageParam callback that will calculate the params for each page based on the existing values, and optionally a getPreviousPageParam callback if reverse fetching is needed. Finally, a maxPages option can be provided to limit the entry cache size.

The query and queryFn methods now receive a {queryArg, pageParam} object, instead of just the queryArg.

For the cache entries and hooks, the data field is now an object like {pages: ResultType[], pageParams: PageParam[]>. This gives you flexibility in how you use the data for rendering.

const pokemonApi = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: 'https://example.com/pokemon' }),
  endpoints: (build) => ({
    // 3 TS generics: page contents, query arg, page param
    getInfinitePokemonWithMax: build.infiniteQuery<Pokemon[], string, number>({
      infiniteQueryOptions: {
        // Must provide a default initial page param value
        initialPageParam: 1,
        // Optionally limit the number of cached pages
        maxPages: 3,
        // Must provide a `getNextPageParam` function
        getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) =>
          lastPageParam + 1,
        // Optionally provide a `getPreviousPageParam` function
        getPreviousPageParam: (
          firstPage,
          allPages,
          firstPageParam,
          allPageParams,
        ) => {
          return firstPageParam > 0 ? firstPageParam - 1 : undefined
        },
      },
      // The `query` function receives `{queryArg, pageParam}` as its argument
      query({ queryArg, pageParam }) {
        return `/type/${queryArg}?page=${pageParam}`
      },
    }),
  }),
})

As with all RTKQ functionality, the core logic is UI-agnostic and does not require React. However, using the RTKQ React entry point will also auto-generate useInfiniteQuery hooks for these endpoints. Infinite query hooks fetch the initial page, then provide fetchNext/PreviousPage functions to let you trigger requests for more pages.

function PokemonList({
    pokemonType = 'fire',
  }: {
    pokemonType?: string
   ) {
  const {
    data,
    isFetching,
    isSuccess,
    fetchNextPage,
    fetchPreviousPage,
    refetch,
  } = api.useGetInfinitePokemonInfiniteQuery(pokemonType)

  const handlePreviousPage = async () => {
    const res = await fetchPreviousPage()
  }

  const handleNextPage = async () => {
    const res = await fetchNextPage()
  }
  
  // `data` is a `{pages, pageParams}` object.
  // You can use those to render whatever UI you need.
  // In this case, flatten per-page arrays of results for this endpoint
  // into a single array to render a list.
  const allPokemon = data?.pages.flat() ?? [];

  // render UI with pages, show loading state, fetch as needed
}

Docs and Examples

The RTK Query docs have been updated with new content and explanations for infinite queries:

• Usage Guides: Infinite Queries covers the new concepts, explains how to define infinite query endpoints and use the hooks, documents fetching behaviors, and describes common API interaction patterns
• API Reference: createApi documents the new infinite query endpoint options
• Generated API Slices: React Hooks has been updated to better organize the hook descriptions, and covers the infinite query hook arguments and behaviors

We've also added a new infinite query example app in the repo that shows several usage patterns like pagination, cursors, infinite scrolling, and limit+offset queries.

Notes

As with all new features and functionality, more code does mean an increase in bundle size.

We did extensive work to byte-shave and optimize the final bundle size for this feature. Final estimates indicate that this adds about 4.2Kmin to production bundles. That's comparable to React Query's infinite query support size.

However, given RTKQ's current architecture, that bundle size increase is included even if you aren't using any infinite query endpoints in your application. Given the significant additional functionality, that seems like an acceptable tradeoff. (And as always, having this kind of functionality built into RTKQ means that your app benefits when it uses this feature without having to add a lot of additional code to your own app, which would likely be much larger.)

Longer-term, we hope to investigate reworking some of RTKQ's internal architecture to potentially make some of the features opt-in for better bundle size optimizations, but don't have a timeline for that work.

Thanks

This new feature wouldn't have been possible without huge amounts of assistance from several people. We'd like to thank:

• @TkDodo of TanStack Query, for happily letting us reuse the API design and implementation approach that they worked hard to figure out, and offering us his advice and knowledge on why they made specific design choices
• @riqts , for building the first initial POC draft PR long before we were even ready to begin thinking about this ourselves
• @remus-selea and @agusterodin , for trying out various stages of the draft PRs and offering significant detailed feedback and bug reports as I iterated on the implementation

What's Changed

• [API Concept] - Infinite Query API by @riqts in [API Concept] - Infinite Query API #4393
• RTKQ Infinite Query integration by @markerikson in RTKQ Infinite Query integration #4738

and numerous specific sub-PRs that went into that integration PR as I worked through the implementation over the last few months.

Full Changelog: v2.5.1...v2.6.0

---

This discussion was created from the release v2.6.0.

[raryanpur]

Congrats redux-toolkit team! This is a great addition to the project, very appreciative of all of the hard work that went into making this happen.

[User6531]

Huge thanks! I really appreciate all the work you've put into making this. The infinite query feature is fantastic — it's made things so much easier to work with. Thanks again for your time and effort!
That said, while using the maxPages feature with infinite scroll, I ran into an issue that I’d love to get your thoughts on.

• When fetching the next page of data, the oldest page is removed (as expected).
• Since the scroll position stays the same (near the bottom), it immediately triggers another fetch, causing an unintended rapid loop of data fetching.
• Ideally, I want to preserve the user's relative scroll position (i.e., keep the view near the last seen items when fetching new pages).

Current Behavior

1. User scrolls to the bottom.
2. New data is fetched (maxPages removes the first page and appends a new one).
3. Since the scroll remains near the bottom, another fetch is triggered.
4. This cycle continues, leading to excessive fetch requests.

Would love to hear if there’s an existing solution or if this could be considered as an enhancement. Thanks!

[User6531]

@markerikson do u have any thoughts on that?

I understand that it is not an issue with RTK Query. I just want to ask whether you have faced this issue and possibly have a solution for it.

[markerikson]

I've honestly never written an infinite-scroll UI before, so I have no suggestions here.

[riqts]

@User6531 You likely want to use something like a "window" library (e..g https://github.com/bvaughn/react-window) or an intersection observer here to solve this issue. Another way to think about this issue you are having with infinite scroll, is to either:

1. Have the new items be appended to the page, moving the scroll.
2. Trigger the fetch based on them being NEAR the final amount of data rather than being at the end i.e. rendering an extra page/row and when they get to that page/row prefetch the next :)

Apologies if I am misunderstanding your exact trouble with it though, I can try find some examples of infinite scroll from the discussions thread that existed prior to RTKQ having a native solution as well though, that may have some suggestions. #1163

[User6531]

Pessimistic Updates with infiniteQuery Not Working (selectCachedArgsForQuery Issue)

Description

I'm trying to use selectCachedArgsForQuery with an infiniteQuery in RTK Query, but I get a TypeScript error:

Argument of type '"getApplications"' is not assignable to parameter of type 'QueryKeys<{ getApplications: InfiniteQueryDefinition<...>; ... }>'.ts(2345)

I suspect that selectCachedArgsForQuery does not support infiniteQuery, and there is no equivalent function like selectCachedArgsForInfiniteQuery.

Code Example

async onQueryStarted(productId, _api) {
  const { dispatch, queryFulfilled } = _api;
  const state = _api.getState();

  try {
    await queryFulfilled;

    const args = applicationApi.util.selectCachedArgsForQuery(
      state,
      "getApplications", // Infinite query
    );

    args.forEach((arg) => {
      dispatch(
        applicationApi.util.updateQueryData(
          "getApplications",
          arg,
          (prevData) => prevData, // No modification, just checking structure
        ),
      );
    });
  } catch (error) {
    console.error(error);
  }
}

Expected Behavior

• selectCachedArgsForQuery should return the correct cached arguments for an infiniteQuery.
• If selectCachedArgsForQuery does not support infiniteQuery, an alternative method (e.g., selectCachedArgsForInfiniteQuery) should be provided.

Observed Behavior

• TypeScript throws an error that "getApplications" is not assignable to the expected type.
• There is no documented way to get cached arguments for infiniteQuery.

Possible Fixes

• Add support for selecting cached arguments from infiniteQuery.
• Provide a utility function like selectCachedArgsForInfiniteQuery.
• Improve documentation to clarify how to manually retrieve cached arguments for infiniteQuery.

[markerikson]

Yeah, there's been several places where I missed adding handling for infinite queries in 2.6.0. Already fixed a couple, added this as #4875 .