How do you create paginated pages in Gatsby? You might have many blog posts and want to show 10 per page. Do you need a Gatsby pagination plugin?
\n\n\ntl;dr - Don't use a plugin (yet). Call
\ncreatePage()and pass limit and skip in context. Use lodash_.times()and some custom logic.
You have 107 blog posts. You want to show 10 posts per page. That makes 11 pages. The pages should be /blog, then /blog/2, /blog/3, etc. Each page should have a link to to the next and previous pages (where appropriate).
For example:
\n/blog links to /blog/2/ as the next page/blog/2/ links to /blog as the previous page and /blog/3 as the next pageThe first page has no previous link. The last page has no next link.
\nPagination is not part of Gatsby. It doesn't need to be. You create pages just as normal via createPage(). Paginated pages do not need any special treatment.
The terms are confusing. Page 1 and a Gatsby Page. We'll call Gatsby pages a \"page\". We'll call page 1, page 2, etc \"paginated pages\". A paginated page is also a page!
\nIn this article we'll talk about blog posts. The same logic applies to any other type of page. We'll show some examples later of applying the same to category or tag pages.
\ngatsby-node.jsIn summary.
\nCreate each page
\nIf you have 107 blog posts and 10 per page, you need 11 paginated pages. With 107 blog posts and 15 per page, 8 paginated pages.
\nIn javascript, that is:
\nconst paginatedPagesCount = Math.ceil(blogPostsCount / blogPostsPerPaginatedPage);Creating the paths like /blog and /blog/2 requires a little logic. We can put all of this into a helper function. You can define it at the top scope in gatsby-node.js.
const paginationPath = (path, page, totalPages) => {\n if (page === 0) {\n return path\n } else if (page < 0 || page >= totalPages) {\n return ''\n } else {\n return `${path}/${page + 1}`\n }\n}We need to know the total number of pages in order to know which is the last page. If we have 11 pages the link for page 12 is an empty string. There is no page 12!
\nWe'll assume you've already fetched your blog posts as normal inside gatsby-node.js. The blog posts are in an array blogPosts.
Then you can create pages like this.
\n// How many posts do we have?\nconst blogPostsCount = blogPosts.length;\n// How many posts per paginated page?\nconst blogPostsPerPaginatedPage = 10;\n// How many paginated pages do we need?\nconst const paginatedPagesCount = Math.ceil(blogPostsCount / blogPostsPerPaginatedPage);\n\n// Create each paginated page\n_.times(paginatedPagesCount, (index) => {\n createPage({\n // Calculate the path for this page like `/blog`, `/blog/2`\n path: paginationPath('/blog', index, paginatedPagesCount),\n // Set the component as normal\n component: componentPath,\n // Pass the following context to the component\n context: {\n // Skip this number of posts from the beginning\n skip: index * blogPostsPerPaginatedPage,\n // How many posts to show on this paginated page\n limit: blogPostsPerPaginatedPage,\n // How many paginated pages there are in total\n paginatedPagesCount,\n // The path to the previous paginated page (or an empty string)\n prevPath: paginationPath('/blog', index - 1, paginatedPagesCount),\n // The path to the next paginated page (or an empty string)\n nextPath: paginationPath('/blog', index + 1, paginatedPagesCount),\n }\n })\n});This code simply calls createPage() once for each paginated page. The context contains all the information required for that paginated page.
In the component, you use skip and limit directly inside your query. Gatsby's all* queries support these variables directly.
For example:
\nquery BlogQuery($skip: Int!, $limit: Int!) {\n allMarkdownRemark(\n sort: { fields: [frontmatter___date], order: DESC }\n skip: $skip\n limit: $limit\n ) {\n ...\n }\n}UPDATE: We have launched our very own pagination plugin, humbly called gatsby-awesome-pagination.
\nThere are two pagination plugins right now. They have very similar names! gatsby-paginate and gatsby-pagination. They both use a similar approach. You get all the data you want in gatsby-node.js. Then you pass that data to the component.
Now your query lives in gatsby-node.js but your data is used in the component. Part of the magic of GraphQL is putting your queries next to your components.
The packages pass data via context. In the blog post example, the 10 posts per page are passed via context. This is not a great idea. The idea behind context is to pass just that, context. Not the actual data for the page. This approach somewhat abuses context.
Perhaps you want to show links like 1 2 3. You need to create these links with custom logic. Neither pagination package provides helpers.
\nThe code to generate the links is beyond the scope of this article. In general, we recommend the following:
\ngatsby-node.jscontextThis keeps the separation of concerns. All pagination logic is in gatsby-node.js. The component fetches all the data it requires. The component renders the previous / next / numbered links passed from context.