gatsby-plugin-breadcrumb

$3

- Installation
- Usage
- Gotchas
- Give these a quick read to see common issues you might face while using this
plugin!

Gatsby Versions

This plugin should work fine on Gatsby v2, v3, and v4.

Installation

``bash
yarn add gatsby-plugin-breadcrumb
`

or

`bash
npm install gatsby-plugin-breadcrumb
`

Usage

There are two ways to use gatsby-plugin-breadcrumb to add breadcrumbs to your
Gatsby site: Click Tracking and AutoGen.

$3

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 to
control your own breadcrumbs, by calling useBreadcrumb and passing the
required object properties. Using the hook enables you to pass the breadcrumbs
to your own custom Breadcrumb component, but still take advantage of
gatsby-plugin-breadcrumbs click tracking logic.

- Add the plugin gatsby-plugin-breadcrumb to your gatsby-config.js
- Import and use the useBreadcrumb hook, passing the required object
properties.

- useBreadcrumb example
- useBreadcrumb props/returns

$3

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 and
define the useAutoGen plugin option to true
- Get crumbs 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 to
> create your own breadcrumb component, and pass it the breadcrumb data from
> pageContext, this is always an option.

Click Tracking example:

CodeSandbox.io Demo

gatsby-config.js

`javascript
{
// optional: if you are using path prefix, see plugin option below
pathPrefix: '/blog',
plugins: [
{
resolve: gatsby-plugin-breadcrumb,
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 (