Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Gatsby Starter Infinite Scroll

This is a Gatsby starter intended for developers who need infinite scroll or pagination in their Gatsby project.

Try out this live demo with 10k photos »»»

Get started

Fork and npm install. Run in dev mode with gatsby develop.

If you are wondering how to apply this to your specific use case, here are some examples: blog posts, photos.

If you want to understand how this works, I recommend reading the code in the following order:

» gatsby-node.js
» gatsby-browser.js
» templates/paginatedPageTemplate.js
» components/view.js
» components/globalState.js

If you run into any difficulty, I will be happy to help.

🚀 To infinity and beyond!

  • The default behavior is to use infinite scroll, but fallback to pagination if JS is disabled or an error occurs. Additionally, the demo has a toggle so you can test both modes without disabling JS in your browser.
  • This implementation does not fetch unnecessary metadata at initial pageload. Instead, we only fetch the metadata that we actually need. For example, if we're showing you 120 items right now, then we only need metadata for 120 items. We can ask for more metadata as you scroll for more items. This was somewhat awkward to implement in Gatsby, which is why previously published implementations load metadata for all items during initial page load, and then use client side JS to filter to the desired items. The performance hit for doing that isn't too bad for small collections of items, but it becomes unbearable for large collections, especially if the metadata contains base64 versions of images as placeholders. This performance optimization was my main motivation for creating this starter.
  • Additionally, a minor performance improvement: initial items shipped along with the initial page instead of separately fetched.
  • When the user navigates to another internal page and later returns to front page, scroll position is not forgotten (because we keep items in global state).
  • Many edge cases are considered
    • Large screens / small pages: If initial items fit to screen before scrolling is possible, we fetch more items (this is often overlooked in infinite scroll implementations, e.g. LinkedIn and react-simple-infinite-scroll have this bug.)
    • Slow connections: the initial pageload is consistent even before the React component mounts.
    • Metadata fetching: allow fetching multiple pages of metadata concurrently (as opposed to consecutively, which slows the maximum scroll speed. This can be relevant for example when images are cached locally and metadata pages are not, or if the user wants to scroll fast to a specific location before images can load).
  • Includes a script that can fetch large amounts of random images from Unsplash.

🎓 Attribution

  • Photos are from Unsplash. Unfortunately I couldn't get photographer attribution, because their main API is rate limited, and the non limited API ( only gave me photos. If you can help me get photographer attribution, that would be awesome!
  • Infinite scroll uses some code from Jared Palmer's react-simple-infinite-scroll.
  • Image layout CSS Grid is modified from work by LekoArts.
  • Traffic lights CSS graphics are modified from work by Azik Samarkandiy.
  • Loading spinner uses icon from FontAwesome.

I would love to see what you build with this. You can drop me a message or star this repo.


A Gatsby starter with infinite scroll and pagination.







No releases published


No packages published