A simple hook to create infinite scroll list components

Overview

react-infinite-scroll-hook

Build status License Version

All Contributors

This is a hook to create infinite scroll components!
Live demo is here.

Basically, we need to set a sentry component to trigger infinite loading. When sentry becomes visible on the screen or it comes near to be visible (based on our config of course), it triggers infinite loading (by calling onLoadMore callback) all with the help of IntersectionObserver.

sentry should be some component which will not be unmounted as long as we want to keep the infinite scrolling observer active. For example, we can use a "loading" indicator as our sentry. The trick is, because that we want to keep the infinite scrolling observer active as long as there is a next page, we need to keep this "loading" component mounted even if we don't have a loading flag as true. This will also keep our layout more consistent and prevent flickering etc.

We don't need to use a "loading" component as the sentry and we can keep them separate too. It can be anything like some empty div or last item of your list etc. We just need to place it based on our scrolling direction. To bottom if we want to trigger loading when we scroll to bottom, to top if we want to trigger it when we scroll to top like a chat message box etc. Same approach can be used with horizontal scrolling too.

Please check below to find examples with different layouts and libraries.

Note: This package uses IntersectionObserver under the hood. You might want to check the browser compatibility from here and if you want to support older browsers, you might need to use a polyfill.

Before v4, useInfiniteScroll hook would basically check the DOM with an interval and look at the distance between the bottom of your "infinite" component and the bottom of the window. This was a simple solution. But it had its difficulties. It was not so easy to change the layout of your "infinite" component (like creating a chat message box with inverted scrolling etc). It was a requirement to modify the package based on each different use case.

And also, checking the DOM with an interval by using setInterval wasn't a sophisticated solution. It was enough, but it had it's limits. With v4, we migrated to use IntersectionObserver and created a much more flexible API to support different design. Basically, now we have a little bit more inversion of control.

If you want to use the older version which is using setInterval, you can find it here.

Installation

npm install react-infinite-scroll-hook

Simple Example

import useInfiniteScroll from 'react-infinite-scroll-hook';

function SimpleInfiniteList() {
  const { loading, items, hasNextPage, error, loadMore } = useLoadItems();

  const [sentryRef] = useInfiniteScroll({
    loading,
    hasNextPage,
    onLoadMore: loadMore,
    // When there is an error, we stop infinite loading.
    // It can be reactivated by setting "error" state as undefined.
    disabled: !!error,
    // `rootMargin` is passed to `IntersectionObserver`.
    // We can use it to trigger 'onLoadMore' when the sentry comes near to become
    // visible, instead of becoming fully visible on the screen.
    rootMargin: '0px 0px 400px 0px',
  });

  return (
    <List>
      {items.map((item) => (
        <ListItem key={item.key}>{item.value}</ListItem>
      ))}
      {/* 
          As long as we have a "next page", we show "Loading" right under the list.
          When it becomes visible on the screen, or it comes near, it triggers 'onLoadMore'.
          This is our "sentry".
          We can also use another "sentry" which is separated from the "Loading" component like:
            <div ref={sentryRef} />
            {loading && <ListItem>Loading...</ListItem>}
          and leave "Loading" without this ref.
      */}
      {(loading || hasNextPage) && (
        <ListItem ref={sentryRef}>
          <Loading />
        </ListItem>
      )}
    </List>
  );
}

Or if we have a scrollable container and we want to use it as our "list container" instead of document, we just need to use rootRef like:

function InfiniteListWithVerticalScroll() {
  const { loading, items, hasNextPage, error, loadMore } = useLoadItems();

  const [sentryRef, { rootRef }] = useInfiniteScroll({
    loading,
    hasNextPage,
    onLoadMore: loadMore,
    disabled: !!error,
    rootMargin: '0px 0px 400px 0px',
  });

  return (
    <ListContainer
      // This where we set our scrollable root component.
      ref={rootRef}
    >
      <List>
        {items.map((item) => (
          <ListItem key={item.key}>{item.value}</ListItem>
        ))}
        {(loading || hasNextPage) && (
          <ListItem ref={sentryRef}>
            <Loading />
          </ListItem>
        )}
      </List>
    </ListContainer>
  );
}

Other Examples

You can find different layout examples here. Live demo contains all of these cases.

Also, we have more realistinc examples with swr and Apollo GraphQL too.

Arguments

Name Description Type Optional Default Value
loading Some sort of "is fetching" info of the request. boolean
hasNextPage If the list has more items to load. boolean
onLoadMore The callback function to execute when the 'onLoadMore' is triggered. VoidFunction
rootMargin We pass this to 'IntersectionObserver'. We can use it to configure when to trigger 'onLoadMore'. string
disabled Flag to stop infinite scrolling. Can be used in case of an error etc too. boolean
delayInMs How long it should wait before triggering 'onLoadMore' (in milliseconds). number 100

Contributors

Thanks goes to these wonderful people (emoji key):


Eugene Fidelin

💻

Evan Cater

📖

This project follows the all-contributors specification. Contributions of any kind welcome!

Issues
  • feat: add `mode` options to provide scroll event

    feat: add `mode` options to provide scroll event

    Hello, I use scrollEvent mode detect loadmore callback in my project, and it works well in IOS and Android. And how do you think about that ? 😄 We can provide the options depends on user 's need!

    By the way, I am sorry for my my fault about my useless PR because I has not seen the v3.0 yet when I commit pulling request.

    opened by ron0115 4
  • Error when importing

    Error when importing

    Hello, could you help me out why i cant use this library ? i just import it to my file but it seems doesn't work well. The error says : Line 16:5: 'hasNextPage' is not defined no-undef Line 17:17: 'loadMore' is not defined no-undef Line 18:17: 'error' is not defined no-undef Line 67:32: 'hasNextPage' is not defined no-undef

    Thank you.

    question 
    opened by awingmawe 3
  • Can IntersectionObserver be used instead of intervals?

    Can IntersectionObserver be used instead of intervals?

    Love this great library.

    I was thinking timers weren't the most performant way of checking the boundaries. Should we instead rely on the IntersectionObserver API?

    opened by mordechaim 3
  • Fix `onLoadMore` is triggered even when list is not visible

    Fix `onLoadMore` is triggered even when list is not visible

    Problem.

    When list is not visible on the page the onLoadMore is constantly triggered. Bug exists for lists with window as parent

    ezgif com-video-to-gif (3)

    Steps to reproduce.

    Comment out the following lines

    if (!isListInView()) {
       return;
    }
    

    Run the demo from this PR, reduce browser window, so only yellow footer is visible. You will se in console that onLoadMore is being triggered for ever

    Fix.

    Trigger onLoadMore only if list is in the view.

    ezgif com-video-to-gif (4)

    opened by eugef 3
  • Demo works only for html list tags

    Demo works only for html list tags

    The repo's demo works only if the container is a List ul or ol. It should be specified in the README

    opened by gabrielmoncea 3
  • Should we map the threshold to a ratio instead of a px?

    Should we map the threshold to a ratio instead of a px?

    Hello everyone, could not find a template for this one.

    I was wondering if the threshold could be a ratio of the container instead of a pixel distance, this representation is common in other infinite-list components and what not and seems to me that relates better with the mindset of "when should we load more" since we live on the world of responsiveness.

    I know this might be a breaking change, so we there's should be some caution. Either way, here's an example of what I mean?

    
     const infiniteRef = useInfiniteScroll<HTMLDivElement>({
       ...
        threshold:  0.5 // trigger loadMore in the middle of the scroll parent
      })
    
    

    Cheers for the awesomew hook, hope I can help with this one!

    enhancement 
    opened by rodrigo-picanco 3
  • Couldnt use it with standard div

    Couldnt use it with standard div

    Here's my code below. It doesnt trigger "nextPage" function, while I scroll down (at the bottom of page).

    whats wrong?

    
      const [infiniteRef] = useInfiniteScroll({
        loading,
        hasNextPage,
        onLoadMore: nextPage,
        disabled: !!error,
        rootMargin: '0px 0px 400px 0px',
      })
    
    
            <div className="my-content" ref={infiniteRef}>
              <div className="row" >
                <div className="col-sm-12">
                  <div className="row">
                    {product_list.data.map((item, i) => (
                      <div className="col-md-3 col-sm-6 col-6">
                        <ProductCard {...item} />
                      </div>
                    ))}
                  </div>
                </div>
            </div>
    
    opened by tcagkansokmen 2
  • Can't get it to work with horizontal scrolling

    Can't get it to work with horizontal scrolling

    Any tips would be greatly appreciated.

    opened by 10000multiplier 2
  • Content not loaded when moved to absolute bottom

    Content not loaded when moved to absolute bottom

    When I move to the bottom of the page in your demo then if the list items are not loaded, I have to move back to where the text "footer" is written and then it loads more item

    opened by natashajaved 2
Releases(v4.0.1)
  • v4.0.1(Apr 11, 2021)

    Updated README.md with some more explanation about how to use the hook with more control and mentioned examples which are using swr and Apollo GraphQL.
    Published this version to keep README.md updated on npm too.

    Source code(tar.gz)
    Source code(zip)
  • v4.0.0(Apr 4, 2021)

    With this verion, we completely migrate to using IntersectionObserver instead of checking the DOM by using setInterval.

    So, we have a much more flexible API and it's much easier to create lists with different layouts.

    You can check README.md to a little bit more detailed explanation, different examples and demo.

    But simply, we can show the difference like this:

    Before v4

    import useInfiniteScroll from 'react-infinite-scroll-hook';
    
    function InfiniteList({}) {
      const { loading, items, hasNextPage, error, loadMore } = useLoadItems();
    
      const infiniteRef = useInfiniteScroll({
        loading,
        hasNextPage,
        onLoadMore: handleLoadMore,
        scrollContainer,
      });
    
      // ...
    
      return (
        <List ref={infiniteRef}>
          {items.map((item) => (
            <ListItem key={item.key}>{item.value}</ListItem>
          ))}
          {loading && <ListItem>Loading...</ListItem>}
        </List>
      );
    }
    

    After v4

    import useInfiniteScroll from 'react-infinite-scroll-hook';
    
    function SimpleInfiniteList() {
      const { loading, items, hasNextPage, error, loadMore } = useLoadItems();
    
      const [infiniteRef] = useInfiniteScroll({
        loading,
        hasNextPage,
        onLoadMore: loadMore,
        // When there is an error, we stop infinite loading.
        // It can be reactivated by setting "error" state as undefined.
        disabled: !!error,
        // `rootMargin` is passed to `IntersectionObserver`.
        // We can use it to trigger 'onLoadMore' when the sentry comes near to become
        // visible, instead of becoming fully visible on the screen.
        rootMargin: '0px 0px 400px 0px',
      });
    
      return (
        <List>
          {items.map((item) => (
            <ListItem key={item.key}>{item.value}</ListItem>
          ))}
          {/* 
              As long as we have a "next page", we show "Loading" right under the list.
              When it becomes visible on the screen, or it comes near, it triggers 'onLoadMore'.
              This is our "sentry".
              We can also use another "sentry" which is separated from the "Loading" component like:
                <div ref={infiniteRef} />
                {loading && <ListItem>Loading...</ListItem>}
              and leave "Loading" without this ref.
          */}
          {hasNextPage && (
            <ListItem ref={infiniteRef}>
              <Loading />
            </ListItem>
          )}
        </List>
      );
    }
    
    Source code(tar.gz)
    Source code(zip)
  • 3.0.0(Aug 3, 2020)

    Migrated to TSDX

    • Change named export to default export
    // Before
    import { useInfiniteScroll } from "react-infinite-scroll-hook";
    // After
    import useInfiniteScroll from "react-infinite-scroll-hook";
    
    Source code(tar.gz)
    Source code(zip)
  • 2.0.2(Jul 29, 2020)

  • 2.0.0(Jun 17, 2019)

    • Changed loadMore prop as onLoadMore to provide some naming standardization. Due to this will break the apps those are currently using this package, this is a major version update.
    Source code(tar.gz)
    Source code(zip)
  • 1.0.2(Jun 6, 2019)

Owner
Onur Önder
Frontend Developer @Getir · Ege University Computer Engineering · Ege University Civil Engineering
Onur Önder
React container that will auto scroll to bottom

react-scroll-to-bottom React container that will auto scroll to bottom or top if new content is added and viewport is at the bottom, similar to tail -

William Wong 99 Sep 17, 2021
:scroll: A versatile infinite scroll React component.

ReactList A versatile infinite scroll React component. Install bower install react-list # or npm install react-list ReactList depends on React. Exam

Casey Foster 1.9k Oct 14, 2021
React components for efficiently rendering large lists and tabular data

React components for efficiently rendering large lists and tabular data. Check out the demo for some examples. Sponsors The following wonderful compan

Brian Vaughn 22.6k Oct 14, 2021
Lazy load your component, image or anything matters the performance.

Note This project is now currently maintained by @ameerthehacker, please reach out to him on any issues or help. react-lazyload Lazyload your Componen

twobin 5.4k Oct 14, 2021
Simulate normal scrolling by using only fixed number of DOM elements for large lists of items with React Hooks

React Recycled Scrolling Simulate normal scrolling by using only fixed number of DOM elements for large lists of items with React Hooks Install npm in

sarons 24 Sep 2, 2021