├── .babelrc
├── .flowconfig
├── .github
├── ISSUE_TEMPLATE
│ ├── bug_report.md
│ ├── config.yml
│ └── feature_request.md
└── dependabot.yml
├── .gitignore
├── CHANGELOG.md
├── LICENSE
├── README.md
├── __tests__
├── __snapshots__
│ └── index.js.snap
├── index.js
└── utils.js
├── dependabot.yml
├── docs
└── examples.md
├── package.json
├── src
├── components.js
├── index.js
└── utils.js
└── yarn.lock
/.babelrc:
--------------------------------------------------------------------------------
1 | {
2 | "presets": ["env"],
3 | "plugins": [
4 | "babel-plugin-transform-react-jsx",
5 | "transform-flow-strip-types",
6 | "add-module-exports"
7 | ]
8 | }
9 |
--------------------------------------------------------------------------------
/.flowconfig:
--------------------------------------------------------------------------------
1 | [ignore]
2 |
3 | [include]
4 |
5 | [libs]
6 |
7 | [lints]
8 |
9 | [options]
10 | suppress_comment=\\(.\\|\n\\)*\\$FlowExpectError
11 |
12 | [strict]
13 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/bug_report.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Bug report
3 | about: Create a report to help us improve
4 | title: ''
5 | labels: bug
6 | assignees: ''
7 |
8 | ---
9 |
10 | **Describe the bug**
11 | A clear and concise description of what the bug is.
12 |
13 | **To Reproduce**
14 | Steps to reproduce the behavior:
15 | 1. Go to '...'
16 | 2. Click on '....'
17 | 3. Scroll down to '....'
18 | 4. See error
19 |
20 | **Expected behavior**
21 | A clear and concise description of what you expected to happen.
22 |
23 | **Screenshots**
24 | If applicable, add screenshots to help explain your problem.
25 |
26 | **Additional context**
27 | Add any other context about the problem here.
28 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/config.yml:
--------------------------------------------------------------------------------
1 | blank_issues_enabled: false
2 | contact_links:
3 | - name: Support request
4 | url: https://stackoverflow.com/questions/tagged/gatsby
5 | about: Please ask and answer support requests on stack overflow
6 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/feature_request.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Feature request
3 | about: Suggest an idea for this project
4 | title: ''
5 | labels: enhancement
6 | assignees: ''
7 |
8 | ---
9 |
10 | **Is your feature request related to a problem? Please describe.**
11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
12 |
13 | **Describe the solution you'd like**
14 | A clear and concise description of what you want to happen.
15 |
16 | **Describe alternatives you've considered**
17 | A clear and concise description of any alternative solutions or features you've considered.
18 |
19 | **Additional context**
20 | Add any other context or screenshots about the feature request here.
21 |
--------------------------------------------------------------------------------
/.github/dependabot.yml:
--------------------------------------------------------------------------------
1 | vrsion: 2
2 | allow:
3 | - package-ecosystem: "npm"
4 | directory: "/"
5 | allow:
6 | - dependency-type: "production"
7 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules/
2 | lib/
3 |
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 |
3 | All notable changes to this project will be documented in this file.
4 |
5 | The format is based on [Keep a Changelog][keep a changelog] and this project adheres to [Semantic Versioning][semantic versioning].
6 |
7 | ## [Unreleased]
8 |
9 | ---
10 |
11 | ## [0.3.8] - 2021-04-01
12 |
13 | - Bump lodash to 4.17.21 for security fixes
14 |
15 | ## [0.3.7] - 2021-04-01
16 |
17 | ### Fixed
18 |
19 | - Change `peerDependencies` to `>=` for Gatsby 3 support
20 |
21 | ---
22 |
23 |
24 |
25 | [keep a changelog]: https://keepachangelog.com/
26 | [semantic versioning]: https://semver.org/
27 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2018 Gatsby Central
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | Awesome Pagination for Gatsby
2 | ---
3 |
4 | A sensible approach to pagination for Gatsby sites.
5 |
6 | Please post questions on StackOverflow, only bug reports are accepted via GitHub.
7 |
8 | ## Contents
9 |
10 | * [QuickStart](#quick-start)
11 | * [Introduction](#introduction)
12 | * [Philosophy](#philosophy)
13 | * [Notes](#notes)
14 |
15 | ## Quick start
16 |
17 | ```
18 | yarn add gatsby-awesome-pagination
19 | ```
20 |
21 | Open `gatsby-node.js` and import:
22 |
23 | ```javascript
24 | import { paginate } from 'gatsby-awesome-pagination';
25 | ```
26 |
27 | Then, use `paginate()` like so:
28 |
29 | ```javascript
30 | exports.createPages = ({ actions, graphql }) => {
31 | const { createPage } = actions;
32 |
33 | // Fetch your items (blog posts, categories, etc).
34 | const blogPosts = doSomeMagic();
35 |
36 | // Create your paginated pages
37 | paginate({
38 | createPage, // The Gatsby `createPage` function
39 | items: blogPosts, // An array of objects
40 | itemsPerPage: 10, // How many items you want per page
41 | pathPrefix: '/blog', // Creates pages like `/blog`, `/blog/2`, etc
42 | component: path.resolve('...'), // Just like `createPage()`
43 | })
44 | }
45 | ```
46 |
47 | Now in your page query you can use the pagination context like so:
48 |
49 | ```javascript
50 | export const pageQuery = graphql`
51 | query ($skip: Int!, $limit: Int!) {
52 | allMarkdownRemark(
53 | sort: { fields: [frontmatter___date], order: DESC }
54 | skip: $skip // This was added by the plugin
55 | limit: $limit // This was added by the plugin
56 | ) {
57 | ...
58 | }
59 | }
60 | `
61 | ```
62 |
63 | Then inside your component, you can link to next / previous pages, and so on:
64 |
65 | ```javascript
66 | const BlogIndex = (props) => {
67 | return (
68 |
69 | {data.allMarkdownRemark.edges.map(edge =>
)}
70 |
71 | {/* previousPageLink and nextPageLink were added by the plugin */ }
72 |
75 |
110 | {props.data.posts.edges.map(edge =>
)}
111 |
112 | {previousPagePath ?
115 |
147 |
{post.frontmatter.title}
148 |
149 |
150 | {previousPagePath ? (
151 |
161 |
{label}
16 | );
17 |
18 | type PaginationLinksProps = {
19 | previousLabel?: string,
20 | nextLabel?: string,
21 | pageLabel?: string,
22 | separator?: string,
23 | pageContext: {
24 | pageNumber: number,
25 | humanPageNumber: number,
26 | skip: number,
27 | limit: number,
28 | numberOfPages: number,
29 | previousPagePath?: string,
30 | nextPagePath?: string
31 | }
32 | };
33 |
34 | export const PaginationLinks = ({
35 | previousLabel = "← previous",
36 | nextLabel = "next →",
37 | pageLabel = "Page: %d",
38 | separator = " - ",
39 | activeStyle = {},
40 | inactiveStyle = { textDecorationLine: "line-through", color: "grey" },
41 | pageContext: {
42 | pageNumber,
43 | humanPageNumber,
44 | skip,
45 | limit,
46 | numberOfPages,
47 | previousPagePath,
48 | nextPagePath
49 | }
50 | }: PaginationLinksProps): React.Node => {
51 | return (
52 |
53 | {linkOrText(previousLabel, previousPagePath, activeStyle, inactiveStyle)}
54 | {separator}
55 | {pageLabel.replace("%d", humanPageNumber)}
56 | {separator}
57 | {linkOrText(nextLabel, nextPagePath)}
58 |
59 | );
60 | };
61 |
--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
1 | // @flow
2 |
3 | import isString from "lodash/fp/isString";
4 | import get from "lodash/fp/get";
5 | import times from "lodash/fp/times";
6 | import cloneDeep from "lodash/fp/cloneDeep";
7 | import isInteger from "lodash/fp/isInteger";
8 |
9 | import {
10 | paginatedPath,
11 | getPreviousItem,
12 | getNextItem,
13 | calculateSkip
14 | } from "./utils";
15 |
16 | import type { PathPrefix } from "./utils";
17 |
18 | type CreatePage = ({}) => void;
19 |
20 | type PaginateOpts = {
21 | createPage: CreatePage,
22 | items: {}[],
23 | itemsPerPage: number,
24 | itemsPerFirstPage?: number,
25 | pathPrefix: PathPrefix,
26 | component: string,
27 | context?: {}
28 | };
29 | export const paginate = (opts: PaginateOpts): void => {
30 | const {
31 | createPage,
32 | items,
33 | itemsPerPage,
34 | itemsPerFirstPage,
35 | pathPrefix,
36 | component,
37 | context
38 | } = opts;
39 |
40 | // How many items do we have in total? We use `items.length` here. In fact, we
41 | // could just accept an integer in the API as the actual contents of `items`
42 | // is never used.
43 | const totalItems = items.length;
44 | // If `itemsPerFirstPage` is specified, use that value for the first page,
45 | // otherwise use `itemsPerPage`.
46 | // $FlowExpectError
47 | const firstPageCount: number = isInteger(itemsPerFirstPage)
48 | ? itemsPerFirstPage
49 | : itemsPerPage;
50 |
51 | // How many page should we have?
52 | const numberOfPages =
53 | // If there are less than `firstPageCount` items, we'll only have 1 page
54 | totalItems <= firstPageCount
55 | ? 1
56 | : Math.ceil((totalItems - firstPageCount) / itemsPerPage) + 1;
57 |
58 | // Iterate as many times as we need pages
59 | times((pageNumber: number) => {
60 | // Create the path for this page
61 | const path = paginatedPath(pathPrefix, pageNumber, numberOfPages);
62 |
63 | // Calculate the path for the previous and next pages
64 | const previousPagePath = paginatedPath(
65 | pathPrefix,
66 | pageNumber - 1,
67 | numberOfPages
68 | );
69 | const nextPagePath = paginatedPath(
70 | pathPrefix,
71 | pageNumber + 1,
72 | numberOfPages
73 | );
74 |
75 | // Call `createPage()` for this paginated page
76 | createPage({
77 | path,
78 | component,
79 | // Clone the passed `context` and extend our new pagination context values
80 | // on top of it.
81 | context: Object.assign({}, cloneDeep(context), {
82 | pageNumber,
83 | humanPageNumber: pageNumber + 1,
84 | skip: calculateSkip(pageNumber, firstPageCount, itemsPerPage),
85 | limit: pageNumber === 0 ? firstPageCount : itemsPerPage,
86 | numberOfPages,
87 | previousPagePath,
88 | nextPagePath
89 | })
90 | });
91 | })(numberOfPages);
92 | };
93 |
94 | type CreatePagePerItemOpts = {
95 | createPage: CreatePage,
96 | items: {}[],
97 | itemToPath: string | (({}) => string),
98 | itemToId: string | (({}) => string),
99 | component: string
100 | };
101 | export const createPagePerItem = (opts: CreatePagePerItemOpts): void => {
102 | const { createPage, items, itemToPath, itemToId, component } = opts;
103 |
104 | // $FlowExpectError
105 | const getPath: ({}) => string = isString(itemToPath)
106 | ? get(itemToPath)
107 | : itemToPath;
108 | // $FlowExpectError
109 | const getId: ({}) => string = isString(itemToId) ? get(itemToId) : itemToId;
110 |
111 | // We cannot use `forEach()` here because in the FP version of lodash, the
112 | // iteratee is capped to a single argument, the item itself. We cannot get the
113 | // item's index in the array. So instead we use `times()` and provide the
114 | // length of the array.
115 | times((index: number) => {
116 | const item = items[index];
117 | const path = getPath(item);
118 | const id = getId(item);
119 |
120 | // NOTE: If there is no previous / next item, we set an empty string as the
121 | // value for the next and previous path and ID. Gatsby ignores context
122 | // values which are undefined, so we need these to exist.
123 | const previousItem = getPreviousItem(items, index);
124 | const previousPath = getPath(previousItem) || "";
125 | const nextItem = getNextItem(items, index);
126 | const nextPath = getPath(nextItem) || "";
127 |
128 | // Does the item have a `context` field?
129 | const itemContext = get("context")(item) || {};
130 | const context = Object.assign({}, itemContext, {
131 | pageId: id,
132 | previousPagePath: previousPath,
133 | previousItem: previousItem,
134 | previousPageId: getId(previousItem) || "",
135 | nextPagePath: nextPath,
136 | nextItem: nextItem,
137 | nextPageId: getId(nextItem) || ""
138 | });
139 |
140 | // Call `createPage()` for this item
141 | createPage({
142 | path,
143 | component,
144 | context
145 | });
146 | })(items.length);
147 | };
148 |
--------------------------------------------------------------------------------
/src/utils.js:
--------------------------------------------------------------------------------
1 | // @flow
2 | import get from "lodash/fp/get";
3 |
4 | type ReturnedItem = {} | void;
5 |
6 | export const getPreviousItem = (items: {}[], index: number): ReturnedItem => {
7 | // If this is the first (or -1) element, there is no previous, so return
8 | // undefined
9 | if (index <= 0) {
10 | return;
11 | }
12 |
13 | // Get the previous element
14 | return get(`[${index - 1}]`, items);
15 | };
16 |
17 | export const getNextItem = (items: {}[], index: number): ReturnedItem => {
18 | // If this is the last element (or later), there is no previous, so return
19 | // undefined
20 | if (index >= items.length - 1) {
21 | return;
22 | }
23 |
24 | // Get the previous element
25 | return get(`[${index + 1}]`, items);
26 | };
27 |
28 | type PathPrefixFunction = ({
29 | pageNumber: number,
30 | numberOfPages: number
31 | }) => string;
32 |
33 | export type PathPrefix = string | PathPrefixFunction;
34 |
35 | export const paginatedPath = (
36 | pathPrefix: PathPrefix,
37 | pageNumber: number,
38 | numberOfPages: number
39 | ): string => {
40 | // If this page is less than zero (-1 for example), then it it does not
41 | // exist, return an empty string.
42 | if (pageNumber < 0) {
43 | return "";
44 | }
45 |
46 | // If this page number (which is zero indexed) plus one is more than the total
47 | // number of pages, then this page does not exist, so return an empty string.
48 | if (pageNumber + 1 > numberOfPages) {
49 | return "";
50 | }
51 |
52 | // Calculate a path prefix either by calling `pathPrefix()` if it's a function
53 | // or simply using `pathPrefix` if it is a string.
54 | const prefix =
55 | typeof pathPrefix === "function"
56 | ? pathPrefix({ pageNumber, numberOfPages })
57 | : pathPrefix;
58 |
59 | // If this is page 0, return only the pathPrefix
60 | if (pageNumber === 0) {
61 | return prefix;
62 | }
63 |
64 | // Otherwise, add a slash and the number + 1. We add 1 because `pageNumber` is
65 | // zero indexed, but for human consuption, we want 1 indexed numbers.
66 | return `${prefix !== "/" ? prefix : ""}/${pageNumber + 1}`;
67 | // NOTE: If `pathPrefix` is a single slash (the index page) then we do not
68 | // want to output two slashes, so we omit it.
69 | };
70 |
71 | export const calculateSkip = (
72 | pageNumber: number,
73 | firstPageCount: number,
74 | itemsPerPage: number
75 | ): number => {
76 | if (pageNumber === 0) {
77 | return 0;
78 | } else if (pageNumber === 1) {
79 | return firstPageCount;
80 | } else {
81 | return firstPageCount + itemsPerPage * (pageNumber - 1);
82 | }
83 | };
84 |
--------------------------------------------------------------------------------