Pagination in Gatsby Using gatsby-awesome-pagination

Published on January 14, 2020
Default avatar

By Joshua Hall

Pagination in Gatsby Using gatsby-awesome-pagination

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

Despite Gatsby’s amazing performance, it would be best not to force the user to load every single post onto the same page. Instead, we’ll explore the gatsby-awesome-pagination plugin to segment our post archive into more manageable sections.


We’ll start with the gatsby-starter-blog starter since it comes with markdown support.

$ gatsby new pagination-example https://github.com/gatsbyjs/gatsby-starter-blog
$ yarn add gatsby-awesome-pagination


In our gatsby-node.js file, Let’s import the paginate method and pass it an object below the query for our posts. It only needs a few things, namely the createPage action, an array of our posts, the item limit per page, the slug for our new archive page, and its template. Now when we make this query we’ll get get a bunch of extra stuff in the pageContext prop we’ll use to manage which page is rendered.

const { paginate } = require('gatsby-awesome-pagination');

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions

  const blogPost = path.resolve(`./src/templates/blog-post.js`)
  const result = await graphql(` ... `)

    items: result.data.allMarkdownRemark.edges,
    itemsPerPage: 3,
    pathPrefix: '/posts',
    component: path.resolve('src/templates/blog-archive.js')


The gatsby-awesome-pagination plugin is, as far as I know, just for paginating separate ‘archive’ pages. So instead of adding pagination to the starter’s home page we’ll link to a separate posts page with everything. Groups of posts on normal pages would probably be best with just a static query and something like a carousel to manage what’s shown.

import React from "react";
import { Link, graphql } from "gatsby";
import Bio from "../components/bio";
import Layout from "../components/layout";

class BlogIndex extends React.Component {
  render() {
    const { data } = this.props;

    return (
      <Layout location={this.props.location}>
        <Bio />
        <Link to='/posts'><button>See All Posts</button></Link>

export default BlogIndex;

Our archive template already has access to our query’s pageContext in its props, which we’ll pass to a separate Pager component. Note that we need to use a normal query instead of a static query since our pageContext will be passing values into the skip and limit arguments, which we’ll also need to set.

import Pager from '../components/pager';

export const pageQuery = graphql`
  query($skip: Int!, $limit: Int!) {
    site { ... }
        sort: { fields: [frontmatter___date], order: DESC},
        skip: $skip,
        limit: $limit
        ) {
      edges { ... }

const BlogArchive = ({ data, pageContext, location }) => {
    const posts = data.allMarkdownRemark.edges;

    return (
      <Layout location={location}>
        {posts.map(({ node }) => {
            const title = node.frontmatter.title || node.fields.slug
            return (
              <article key={node.fields.slug}>
                    <Link to={node.fields.slug}> {title} </Link>
                  <p dangerouslySetInnerHTML={{ __html: node.frontmatter.description || node.excerpt }} />

        <Pager pageContext={pageContext} />

export default BlogArchive;


The final step is really as simple as getting the page paths from the pageContext. If you log the pageContext you can see the skip and limit properties that are being passed to the query, along with pageNumber and numberOfPages which you could use to generate a number and link for each page.

import React from 'react';
import { Link } from 'gatsby';

const Pager = ({ pageContext }) => {
  const { previousPagePath, nextPagePath } = pageContext;
  return (
    <nav style={{ display: 'flex', justifyContent: 'space-between' }}>
        {previousPagePath && (
          <Link to={previousPagePath}>
            <button>← Newer Posts</button>

      <div style={{ justifySelf: 'flex-end' }}>
        {nextPagePath && (
          <Link to={nextPagePath}>
            <button>Older Posts →</button>

export default Pager;


Adding navigation between each post is just as simple and doesn’t even need a plugin. This particular starter actually already supports this, but let’s pretend it doesn’t for now.

Where we create our pages from our query, we just need to add two fields that will then have access to in the pageContext. If it’s the first post then prev shouldn’t exist, else we’ll return the last post. Same with next, only return the next post if one exists.

posts.forEach((post, index) => {
    path: post.node.fields.slug,
    component: blogPost,
    context: {
      slug: post.node.fields.slug,
      prev: index === 0 ? null : posts[index - 1].node,
      next: index === (posts.length - 1) ? null : posts[index + 1].node

It’s the same execution as with our Pager, check if prev/next exist, throw them in a Link, and you’re done.

const BlogPostTemplate = ({ data, pageContext, location }) => {
  const post = data.markdownRemark;
  const { prev, next } = pageContext;

  return (
    <Layout location={location}>
      <Link to='/posts'>Archive</Link>
          <h1> {post.frontmatter.title} </h1>
          <p> {post.frontmatter.date} </p>
        <section dangerouslySetInnerHTML={{ __html: post.html }} />
        <hr />

      <nav style={{ display: 'flex', justifyContent: 'space-between' }}>
          {prev && <Link to={prev.fields.slug} rel="prev"> ← Last Post </Link>}

        <div style={{ justifySelf: 'flex-end' }}>
          {next && <Link to={next.fields.slug} rel="next"> Next Post → </Link>}

export default BlogPostTemplate;

Closing Thoughts

This plugin is still being ironed out, but I’m excited to see how they’ll improve this already incredibly simple design.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us

About the authors
Default avatar
Joshua Hall


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

I am getting a “TypeError: data is undefined” from the blog-archive.js file:

const posts = data.allMarkdownRemark.edges;

Any idea what might be causing this?

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel