Gatsby plugin to add breadcrumbs to your site
npm install gatsby-plugin-breadcrumb







- Installation
- Usage
- Gotchas
- Give these a quick read to see common issues you might face while using this
plugin!
This plugin should work fine on Gatsby v2, v3, and v4.
``bash`
yarn add gatsby-plugin-breadcrumb
or
`bash`
npm install gatsby-plugin-breadcrumb
There are two ways to use gatsby-plugin-breadcrumb to add breadcrumbs to your
Gatsby site: Click Tracking and AutoGen.
Click tracking creates a breadcrumb of out of the path taken (clicked) by the
user. The two ways to use click tracking are:
- Using the component:
- Add the plugin gatsby-plugin-breadcrumb to your gatsby-config.js
- Import and use the component, passing the required props,
on pages you wish to see the breadcrumb.
- Click Tracking example
- Breadcrumb props
- Breadcrumb with Layout component
- Breadcrumb with default crumb
- Styling the Breadcrumb
- Using the useBreadcrumb hook: The useBreadcrumb hook enables you touseBreadcrumb
control your own breadcrumbs, by calling and passing thegatsby-plugin-breadcrumbs
required object properties. Using the hook enables you to pass the breadcrumbs
to your own custom Breadcrumb component, but still take advantage of
click tracking logic.
- Add the plugin gatsby-plugin-breadcrumb to your gatsby-config.jsuseBreadcrumb
- Import and use the hook, passing the required object
properties.
- useBreadcrumb example
- useBreadcrumb props/returns
AutoGen (Auto Generated) will generate breadcrumbs for each page and inject them
into Gatsby page pageContext prop under the breadcrumb property.
- Add the plugin gatsby-plugin-breadcrumb to your gatsby-config.js anduseAutoGen
define the plugin option to truecrumbs
- Get array from breadcrumb object in pageContext
- Import and use the component, passing the required props on
pages you wish to see the breadcrumb
- AutoGen example
- Breadcrumb props
- Styling the Breadcrumb
> Use of the component is not a requirement. If you want topageContext
> create your own breadcrumb component, and pass it the breadcrumb data from
> , this is always an option.
CodeSandbox.io Demo
gatsby-config.js
`javascriptgatsby-plugin-breadcrumb
{
// optional: if you are using path prefix, see plugin option below
pathPrefix: '/blog',
plugins: [
{
resolve: ,`
options: {
// defaultCrumb: optional To create a default crumb
// see Click Tracking default crumb example below
defaultCrumb: {
location: {
pathname: "/",
},
crumbLabel: "HomeCustom",
crumbSeparator: " / ",
},
// usePathPrefix: optional, if you are using pathPrefix above
usePathPrefix: '/blog',
}
}
],
}
/pages/aboutus.js
`jsx
import React from 'react'
import { Breadcrumb } from 'gatsby-plugin-breadcrumb'
export const AboutUs = ({ location }) => {
...
return(
$3
The
component provides default breadcrumbs, while also allowing
you to customize those breadcrumbs if you wish.$3
| prop | type | description | examples | required |
| -------------- | ------ | --------------------------------- | --------------------------------------------------------------- | -------- |
| location | object | Reach Router location prop | See Reach Router location prop, passed by Gatsby to every page. | required |
| crumbLabel | string | Name for the breadcrumb |
"About Us" | required |
| title | string | Title preceding the breadcrumbs | "Breadcrumbs: ", ">>>" | optional |
| crumbSeparator | string | Separator between each breadcrumb | " / " | optional |$3
Instead of adding the
component to every page, another option
would be to add it to a layout component.$3
CodeSandbox.io Demo
/pages/aboutus.js
`jsx
import React from 'react'
import Layout from './layout'
...export const AboutUs = ({ location }) => {
return (
...
}
}
`/pages/contact.js
`jsx
import React from 'react'
import Layout from './layout'export const Contact = ({location}) => {
return (
...
}
}
`/components/layout.js
`jsx
import React from 'react'
import { Breadcrumb } from 'gatsby-plugin-breadcrumb'export const Layout = ({location, crumbLabel}) => {
return (
...
}
}
`$3
While using the Click Tracking option with the
component, if a
user goes directly to a page, your breadcrumb will start with that page. You may
want to always provide a default or "Home" breadcrumb. You can do this by adding
a defaultCrumb plugin option. We must structure the defaultCrumb breadcrumb
we provide in a way our context is expecting, see below for an example using all
available options.`javascript
{
resolve: gatsby-plugin-breadcrumb,
options: {
defaultCrumb: {
// location: required and must include the pathname property
location: {
pathname: "/",
},
// crumbLabel: required label for the default crumb
crumbLabel: "Home",
// all other properties optional
crumbSeparator: " / ",
},
},
},
`$3
To use the default styles please import the
gatsby-plugin-breadcrumb.css file
into your gatsby-browser.js file.gatsby-browser.js
`javascript
import 'gatsby-plugin-breadcrumb/gatsby-plugin-breadcrumb.css'
`If you would rather style your own breadcrumb, here is a list of the classes
used with the
component:| class | description |
| -------------------------- | ----------------------------------------------- |
|
breadcrumb__title | Applied to the breadcrumb title () |
| breadcrumb | Applied to the breadcrumb container (