Gatsby Starter Infinite Scroll is a developer-focused Gatsby starter that adds infinite scroll to any Gatsby project, with an automatic fallback to pagination when JavaScript is unavailable or fails.
Gatsby Starter Infinite Scroll is an open-source starter created by baobabKoodaa and published on GitHub. It takes a Gatsby project as its input and produces a paginated page template that can display large collections of items (such as photos or blog posts) using either infinite scroll or numbered pagination. The repository includes a live demo showing 10,000 photos at https://gatsby-starter-infinite-scroll.baobab.fi, and the code is structured in five key files: gatsby-node.js, gatsby-browser.js, templates/paginatedPageTemplate.js, components/view.js, and components/globalState.js. Prerequisites are Node v16 and gatsby-cli v4 installed globally.
Key Features
- Automatic pagination fallback — Infinite scroll is the default, but the template automatically switches to pagination when JavaScript is disabled or an error occurs; the demo also includes a toggle to test both modes.
- Lazy metadata fetching — Only metadata for the currently visible items is loaded on initial page load; additional metadata is fetched on demand as the user scrolls, avoiding the cost of loading metadata for all items up front (a problem when base64 image placeholders are included).
- Initial items bundled with the page — The first set of items is shipped in the initial HTML response instead of being fetched separately, reducing round trips.
- Scroll position restoration — Items are kept in a global state, so a user who navigates to another internal page and returns to the front page finds their previous scroll position preserved.
- Edge-case handling — If initial items fit on screen without enabling scrolling, more items are fetched automatically; slow connections are handled by consistent initial page content, and multiple metadata pages can be fetched concurrently to support fast scrolling.
- Unsplash fetch script — A script is included that can pull large sets of random images from Unsplash for testing the starter.
- Tech stack — Built with Gatsby and React, uses CSS Grid for the image layout (adapted from work by LekoArts), borrows infinite-scroll logic from react-simple-infinite-scroll, and uses a FontAwesome loading spinner.
Who is it for?
- Gatsby developers who want to add infinite scroll or pagination to a content-heavy site without implementing the logic from scratch.
- Blog authors looking to present long lists of posts with a smooth scrolling experience, as demonstrated by the author's own blog.
- Photographers and visual portfolios needing a performant photo grid that loads images lazily; the starter's photo-book example and 10k-photo demo target this use case directly.
- Performance-conscious developers who need to avoid loading unnecessary metadata at initial page load, especially when dealing with large collections and placeholder images.
What can you do with it?
- Build a photo gallery: Use the included photo-book example to create a grid of images with infinite scroll, lazy loading, and scroll-position memory.
- Add infinite scroll to a blog: Apply the paginated template to blog post lists, as done in the author's personal blog linked from the repository.
- Learn the implementation: Read the code in the recommended order (gatsby-node.js → gatsby-browser.js → paginatedPageTemplate.js → view.js → globalState.js) to understand how the starter works and adapt it to custom use cases.
How does it work?
The starter generates pages via gatsby-node.js, then uses gatsby-browser.js to hook into client-side navigation. The paginated page template renders items stored in a global state, and a view component triggers fetching of additional metadata as the user approaches the bottom of the page. The global state keeps items across navigations, which enables scroll restoration and avoids refetching.
FAQ
Yes, it is a public open-source starter hosted on GitHub. No license or pricing information is stated in the repository.
Yes, the default behavior is infinite scroll, but the template automatically falls back to pagination if JavaScript is disabled or an error occurs. The demo even provides a toggle so you can test both modes without disabling JS.
What versions of Node and Gatsby does it require?
It requires Node v16 and gatsby-cli v4. You can use a tool like nvm to switch Node versions, and install the CLI globally with npm install -g gatsby-cli@latest-v4.
How are images loaded in the demo?
The demo includes a script that fetches random images from Unsplash. The starter fetches only the metadata it needs for visible items, so images are loaded as placeholders and then replaced as you scroll.
