Awesome Pagination for Gatsby
A sensible approach to pagination for Gatsby sites.
Please post questions on StackOverflow, only bug reports are accepted via GitHub.
Contents
Quick start
Open gatsby-node.js
and import:
import { paginate } from 'gatsby-awesome-pagination';
Then, use paginate()
like so:
exports.createPages = ({ actions, graphql }) => {
const { createPage } = actions;
// Fetch your items (blog posts, categories, etc).
const blogPosts = doSomeMagic();
// Create your paginated pages
paginate({
createPage, // The Gatsby `createPage` function
items: blogPosts, // An array of objects
itemsPerPage: 10, // How many items you want per page
pathPrefix: '/blog', // Creates pages like `/blog`, `/blog/2`, etc
component: path.resolve('...'), // Just like `createPage()`
})
}
Now in your page query you can use the pagination context like so:
export const pageQuery = graphql`
query ($skip: Int!, $limit: Int!) {
allMarkdownRemark(
sort: { fields: [frontmatter___date], order: DESC }
skip: $skip // This was added by the plugin
limit: $limit // This was added by the plugin
) {
...
}
}
`
Then inside your component, you can link to next / previous pages, and so on:
const BlogIndex = (props) => {
return (
<div>
{data.allMarkdownRemark.edges.map(edge => <PostItem item={edge.node}/>)}
<div>
{/* previousPageLink and nextPageLink were added by the plugin */ }
<Link to={props.pageContext.previousPagePath}>Previous</Link>
<Link to={props.pageContext.nextPagePath}>Next</Link>
</div>
</div>
)
}
For a more detailed example, see docs/examples.md
Introduction
Love Gatsby, wanna paginate. Sweet, that’s exactly what this package is for.
We differ from other pagination options as follows:
- Don’t abuse
context
to pass data into components - Pass only pagination context via
context
- Provide helpers for next / previous links
There are 2 types of pagination. You have 80 blog posts and you want to show
them 15 at a time on pages like /blog
, /blog/2
, /blog/3
, etc. You do this
with paginate()
. Then on each blog post, you want to link to the previous and
next blog posts. You do this with createPagePerItem()
.
Philosophy
Why did we create this plugin? We felt that the other Gatsby pagination plugins were using an approach that goes against the principles of GraphQL. One of the advantages of GraphQL is to be able to decide what data you need right where you use that data. That’s how Gatsby works with page queries.
By putting all the data into context
, the other pagination plugins break this.
Now you need to decide what data you require for each page inside
gatsby-node.js
and not inside your page query.
We also felt that there were some helpers missing. Generating links to the next and previous pages.
This plugin aims to make it easy to paginate in Gatsby properly. No compromises.
API
Both paginate()
and createPagePerItem()
take a single argument, an object.
They share the following keys (* = required):
createPage
* - ThecreatePage
function fromexports.createPages
component
* - The value you would pass tocreatePage()
ascomponent
Gatsby docs hereitems
* - An array of objects, the items you want to paginate over
paginate()
In addition to the arguments above, paginate()
also supports:
itemsPerPage
* - An integer, how many items should be displayed on each pageitemsPerFirstPage
- An integer, how many items should be displayed on the first pagepathPrefix
* - A (nonempty) string or string returning function, the path (eg/blog
) to which/2
,/3
, etc will be addedcontext
- A base context object which is extended with the pagination context values
Example:
paginate({
createPage: boundActionCreators.createPage,
component: path.resolve('./src/templates/blog-index.js'),
items: blogPosts,
itemsPerPage: 15,
itemsPerFirstPage: 3,
pathPrefix: '/blog'
})
Each page’s context
automatically receives the following values:
pageNumber
- The page number (starting from 0)humanPageNumber
- The page number (starting from 1) for human consumptionskip
- The $skip you can use in a GraphQL querylimit
- The $limit you can use in a GraphQL querynumberOfPages
- The total number of pagespreviousPagePath
- The path to the previous page orundefined
nextPagePath
- The path to the next page orundefined
pathPrefix()
For more advanced use cases, you can supply a function to pathPrefix
. This
function will receive a single object as its only argument, that object will
contain pageNumber
and numberOfPages
, both integers.
A simple example implementation could be:
const pathPrefix = ({ pageNumber, numberOfPages }) =>
pageNumber === 0 ? '/blog' : '/blog/page'
This example produces pages like /blog
, /blog/page/2
, /blog/page/3
, etc.
createPagePerItem()
WARNING: This API is under active development and will probably change. USE WITH CAUTION.
In addition to the arguments above, createPagePerItem()
also accepts:
itemToPath
* - A function that takes one object fromitems
and returns thepath
for thisitem
itemToId
* - A function that takes one object fromitems
and returns the item’s ID
NOTE: Both itemToPath
and itemToId
also accept a string with the path to
the value, for example node.frontmatter.permalink
or node.id
.
NOTE: If an individual item
has a property called context
, and that
property is an object, then it’s own properties will be added to the page’s
context
for that item.
Example:
createPagePerItem({
createPage: boundActionCreators.createPage,
component: path.resolve('./src/templates/blog-post.js'),
items: blogPosts,
itemToPath: 'node.frontmatter.permalink',
itemToId: 'node.id'
})
Each page’s context
automatically receives the following values:
previousPagePath
- The path to the previous page orundefined
previousItem
- A copy of the previous element fromitems
previousPageId
- The ID of the previous pagenextPagePath
- The path to the next page orundefined
nextItem
- A copy of the next element fromitems
nextPageId
- The ID of the next page
Notes
Flow
This plugin is written using flow. There are some
limitations when using flow and lodash. Specifically
this issue. In many cases we use
$FlowExpectError
and explicitly define the type of something to workaround. A
more elegant solution does not currently seem to exist. Any input on improving
the typing is greatly appreciated in the plugin’s issues.
Contributors
Thanks to the following for their contributions: