gatsby-plugin-layout

This plugin enables adding components which live above the page components and persist across page changes.

This can be helpful for:

- Persisting layout between page changes for e.g. animating navigation
- Storing state when navigating pages
- Custom error handling using componentDidCatch
- Inject additional data into pages using React Context.

This plugin reimplements the behavior of layout components in gatsby@1, which was removed in version 2.

Install

``shell
npm install gatsby-plugin-layout
`

How to use

Add the plugin to your gatsby-config.js:

By default plugin will try to use Layout component located in src/layouts/index.js (same as Gatsby v1)

`js
module.exports = {
plugins: [gatsby-plugin-layout],
}
`

If you prefer to keep layout in different place, you can use component option:

`js
module.exports = {
plugins: [
{
resolve: gatsby-plugin-layout,
options: {
component: require.resolve(./relative/path/to/layout/component),
},
},
],
}
`

Once the plugin is added, you don't need to manually wrap your pages with the Layout component. The plugin does this automatically.

Why would you want to reimplement the V1 layout behavior?

There are a few scenarios where it makes sense to reimplement the V1 layout handling:

1. You have a large or complex V1 site and refactoring to the new layout component is not feasible
2. Your site uses page transitions or other transitions that break if the layout component is unmounted and remounted when routes change
3. Your site attaches global state in the layout that doesn't persist if the component is unmounted and remounted

$3

In the original implementation, the layout component was wrapped around the outside of the page component, which, in pseudo-code, looked something like this:

`jsx


{/ layout is not affected when the page template changes /}
{/ page content here /}


`

This meant that the layout component could manage things like transitions and persistent state without any special workarounds, because it never rerendered.

$3

In version 2, the layout component is no longer special, and it's included in every page that wants to display it. This means that it _does_ rerender on every route change:

`jsx


{/ layout will rerender each time the page template changes /}
{/ page content here /}


`

This can make it complicated to support transitions or state without using the wrapPageElement browser API (and the SSR equivalent). This plugin implements those APIs for you, which reimplements the behavior of Gatsby V1.

Troubleshooting

$3

Use React Context to pass data both ways.

For example you can use this boilerplate:

`js
// Context.js
import React from "react"

const defaultContextValue = {
data: {
// set your initial data shape here
menuOpen: false,
},
set: () => {},
}

const { Provider, Consumer } = React.createContext(defaultContextValue)

class ContextProviderComponent extends React.Component {
constructor() {
super()

this.setData = this.setData.bind(this)
this.state = {
...defaultContextValue,
set: this.setData,
}
}

setData(newData) {
this.setState(state => ({
data: {
...state.data,
...newData,
},
}))
}

render() {
return {this.props.children}
}
}

export { Consumer as default, ContextProviderComponent }
`

Use Provider in Layout Component:

`js
import { ContextProviderComponent } from "./Context"

export default ({ children }) => (