gatsby-plugin-page-progress
Version:
Progress indicator for the top of pages as user scrolls
194 lines (133 loc) • 4.92 kB
Markdown
# gatsby-plugin-page-progress
Add a page progress indicator to your Gatsby project 😎
The progress bar moves as you scroll down the page.
> Useful for blog sites and other reading material so users know how far they've read into an article or page.
## [Install](#install)
`npm i gatsby-plugin-page-progress`
## [Options Example](#options-example)
Inside `gatsby-config.js`
```js
plugins: [
{
resolve: "gatsby-plugin-page-progress",
options: {
includePaths: ["/", { regex: "^/blog" }],
excludePaths: ["/blog/beep-beep-lettuce"],
height: 3,
prependToBody: false,
color: `#663399`,
footerHeight: 500,
headerHeight: 0,
},
},
];
```
If you'd like the progression bar to appear on all pages of your project,
you can simply add the name of the plugin to your plugins array in `gatsby-config.js`
```js
plugins: ["gatsby-plugin-page-progress"];
```
## [Options](#options)
#### `includePaths`
Required: ❌
Accepts: `[string | object]`
Default: `[]`
> Supports multiple paths. This option enables the plugin to include an array of paths. You can use regex to define multiple path inclusions. **See examples below**
#### `excludePaths`
Required: ❌
Accepts: `[string | object]`
Default: `[]`
> Supports multiple paths. This option enables the plugin to exclude an array of paths. You can use regex to multiple path exclusions. Defining paths to exclude will take precedence over `includePath` definitions. **See examples below**
#### `prependToBody`
Required: ❌
Accepts: `boolean`
Default: `false`
> If `false`, the bar is appended to the `<body>`. If `true`, the bar is prepended to the `<body>`.
#### `height`
Required: ❌
Accepts: `number`
Default: `3`
> Sets the `height` of the progress bar.
#### `color`
Required: ❌
Accepts: `string`
Default: `#663399`
> Sets the `color` of the progress bar.
#### `footerHeight`
Required: ❌
Accepts: `number`
Default: `0`
> Sets the height of the footer. The width of the progress bar will be scaled appropriately to reach 100% before reaching the page footer.
#### `headerHeight`
Required: ❌
Accepts: `number`
Default: `0`
> Sets the height of the header. The width of the progress bar will be scaled appropriately to reach 100% while offsetting the height of a fixed header and moves the progress bar below the header.
## [Examples](#examples)
#### Only include the root path:
```js
plugins: [
{
resolve: "gatsby-plugin-page-progress",
options: {
includePaths: ["/"],
excludePaths: [],
},
},
];
```
#### Include the root path, plus all paths under the `/blog` route:
```js
plugins: [
{
resolve: "gatsby-plugin-page-progress",
options: {
includePaths: ["/", { regex: "^/blog" }],
excludePaths: [],
},
},
];
```
> This plugin calls the constructor function for [RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#Creating_a_regular_expression). That's why we define any regex that we want to use inside an object. For more information on how to write regular expressions using the RegExp constructor use [MDN for reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Description).
#### Exclude only the root path:
```js
plugins: [
{
resolve: "gatsby-plugin-page-progress",
options: {
includePaths: [],
excludePaths: ["/"],
},
},
];
```
#### Include the root path, plus every path under the `/blog` route, but exclude a specific path under `/blog`:
```js
plugins: [
{
resolve: "gatsby-plugin-page-progress",
options: {
includePaths: ["/", { regex: "^/blog" }],
excludePaths: ["/blog/awesome/article"],
},
},
];
```
#### Include the root path, plus all paths under the `/blog` route, but exclude all paths under `/blog` that end with `'react'`':
```js
plugins: [
{
resolve: "gatsby-plugin-page-progress",
options: {
includePaths: ["/", { regex: "^/blog" }],
excludePaths: [{ regex: "^/blog.+react$" }],
},
},
];
```
> Remember that exclusions always take precedence over inclusions. In the case above - If the plugin finds any path that begins with `/blog` and ends with `react` it will not apply the progress indicator because it already knows to exclude that route 😁 Inversely, if we were on a route under `/blog` that didn't end with `react`, it would apply the progress indicator because the exclusion rule wouldn't apply to that route.