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

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)

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

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

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:

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

How layouts worked in version 1

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

<Root>
  <Layout>
    {/* layout is not affected when the page template changes */}
    <PageElement>{/* page content here */}</PageElement>
  </Layout>
</Root>

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

How layouts work in version 2

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:

<Root>
  <PageElement>
    {/* layout will rerender each time the page template changes */}
    <Layout>{/* page content here */}</Layout>
  </PageElement>
</Root>

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

Passing data from Layout to Page / from Page to Layout

Use React Context to pass data both ways.

For example you can use this boilerplate:

// 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 <Provider value={this.state}>{this.props.children}</Provider>
  }
}

export { Consumer as default, ContextProviderComponent }

Use Provider in Layout Component:

import { ContextProviderComponent } from "./Context"

export default ({ children }) => (
  <ContextProviderComponent>
    <Header />
    {children}
    <Footer />
  </ContextProviderComponent>
)

And then you can use it anywhere:

To read state:

import ContextConsumer from "./Context"

const ComponentThatReadState = () => (
  <ContextConsumer>
    {({ data }) => {
      data.menuOpen ? <Menu /> : null
    }}
  </ContextConsumer>
)

To read and set state:

import ContextConsumer from "./Context"

const ComponentThatChangeState = () => (
  <ContextConsumer>
    {({ data, set }) => (
      <div onClick={() => set({ menuOpen: !data.menuOpen })}>
        {data.menuOpen ? `Opened Menu` : `Closed Menu`}
      </div>
    )}
  </ContextConsumer>
)

Handling multiple layouts

If you want to use different layouts for different pages, you can pass this information in the context of the pages you create, and then conditionally render in your layout file.

In gatsby-node.js:

exports.onCreatePage = ({ page, actions }) => {
  const { createPage } = actions

  if (page.path.match(/special-page/)) {
    page.context.layout = "special"
    createPage(page)
  }
}

And then in src/layouts/index.js:

export default ({ children, pageContext }) => {
  if (pageContext.layout === "special") {
    return <AlternativeLayout>{children}</AlternativeLayout>
  }
  return <RegularLayout>{children}</RegularLayout>
}

Current Tags

3.23.0-alpha-9689ff.25 ... alpha-9689ff (2 years ago)
3.23.0-alpha-a5-peer.70 ... alpha-a5-peer (2 years ago)
2.14.0-alpha-qe-sm.46 ... alpha-qe-sm (3 years ago)
3.14.0-alpha-transformer-json.26 ... alpha-transformer-json (2 years ago)
3.6.0-alpha-ts-jit.60 ... alpha-ts-jit (3 years ago)
4.0.0-alpha-v5.d20221012t101120.57 ... alpha-v5 (2 years ago)
4.0.0-alpha-drupal-proxyurl.14 ... drupal-proxyurl (2 years ago)
3.18.0-alpha-drupal-self-reference.18 ... drupal-self-reference (2 years ago)
1.5.0-image-helpers.58 ... image-helpers (4 years ago)
3.8.0-alpha-image-service.24 ... image-service (3 years ago)
4.13.1 ... latest (a year ago)
2.15.0 ... latest-v3 (2 years ago)
3.25.0 ... latest-v4 (2 years ago)
4.14.0-next.2 ... next (a year ago)
1.1.6-otp-test.69 ... otp-test (5 years ago)
3.23.0-alpha-preview-gh-api.26 ... preview-gh-api (2 years ago)
2.0.0-reach-router.186 ... reach-router (4 years ago)
1.2.3-unifiedroutes.76 ... unifiedroutes (4 years ago)
2.0.0-v3rc.0 ... v3rc (4 years ago)
3.15.0-alpha-wp-image-cdn-auth.48 ... wp-image-cdn-auth (3 years ago)

260 Versions

4.13.1 ... a year ago
4.14.0-next.2 ... a year ago
4.14.0-next.1 ... a year ago
4.13.0 ... a year ago
4.14.0-next.0 ... a year ago
4.12.0 ... a year ago
4.13.0-next.0 ... a year ago
4.11.0 ... 2 years ago
4.12.0-next.0 ... 2 years ago
4.11.0-next.1 ... 2 years ago
4.10.0 ... 2 years ago
4.11.0-next.0 ... 2 years ago
4.10.0-next.2 ... 2 years ago
4.10.0-next.1 ... 2 years ago
4.9.0 ... 2 years ago
4.10.0-next.0 ... 2 years ago
4.8.0 ... 2 years ago
4.9.0-next.0 ... 2 years ago
4.7.0 ... 2 years ago
4.8.0-next.0 ... 2 years ago
4.6.0 ... 2 years ago
4.7.0-next.0 ... 2 years ago
4.5.0 ... 2 years ago
4.6.0-next.0 ... 2 years ago
4.4.0 ... 2 years ago
4.5.0-next.0 ... 2 years ago
4.4.0-next.1 ... 2 years ago
4.3.0 ... 2 years ago
4.4.0-next.0 ... 2 years ago
2.15.0 ... 2 years ago
3.25.0 ... 2 years ago
4.2.0 ... 2 years ago
4.3.0-next.0 ... 2 years ago
4.0.0-alpha-drupal-proxyurl.14 ... 2 years ago
4.1.0 ... 2 years ago
4.2.0-next.0 ... 2 years ago
4.0.0 ... 2 years ago
4.1.0-next.0 ... 2 years ago
4.0.0-next.2 ... 2 years ago
4.0.0-next.1 ... 2 years ago
3.14.0-alpha-transformer-json.26 ... 2 years ago
4.0.0-next.0 ... 2 years ago
4.0.0-alpha-v5.d20221012t101120.57 ... 2 years ago
4.0.0-alpha-v5.d20221010t183635.51 ... 2 years ago
4.0.0-alpha-v5.d20221007t081809.41 ... 2 years ago
4.0.0-alpha-v5.d20221005t111511.35 ... 2 years ago
4.0.0-alpha-v5.16 ... 2 years ago
3.24.0 ... 2 years ago
3.25.0-next.0 ... 2 years ago
3.23.0-alpha-a5-peer.70 ... 2 years ago
4.0.0-alpha-v5.26 ... 2 years ago
3.23.0 ... 2 years ago
3.23.0-alpha-preview-gh-api.26 ... 2 years ago
3.24.0-next.0 ... 2 years ago
3.23.0-alpha-v5.26 ... 2 years ago
3.23.0-alpha-9689ff.25 ... 2 years ago
4.0.0-alpha-v5.25 ... 2 years ago
4.0.0-alpha-v5.24 ... 2 years ago
3.22.0 ... 2 years ago
3.23.0-next.0 ... 2 years ago
3.21.0 ... 2 years ago
3.22.0-next.0 ... 2 years ago
3.20.0 ... 2 years ago
3.21.0-next.0 ... 2 years ago
3.18.0-alpha-drupal-self-reference.18 ... 2 years ago
3.19.0 ... 2 years ago
3.20.0-next.0 ... 2 years ago
3.18.0 ... 2 years ago
3.19.0-next.1 ... 2 years ago
3.19.0-next.0 ... 2 years ago
3.18.0-next.1 ... 3 years ago
3.17.0 ... 3 years ago
3.18.0-next.0 ... 3 years ago
3.16.0 ... 3 years ago
3.17.0-next.0 ... 3 years ago
3.15.0 ... 3 years ago
3.15.0-alpha-wp-image-cdn-auth.48 ... 3 years ago
3.16.0-next.0 ... 3 years ago
3.14.0 ... 3 years ago
3.15.0-next.0 ... 3 years ago
3.14.0-next.2 ... 3 years ago
3.13.0 ... 3 years ago
3.14.0-next.1 ... 3 years ago
3.14.0-next.0 ... 3 years ago
3.12.1 ... 3 years ago
3.12.0 ... 3 years ago
3.13.0-next.0 ... 3 years ago
3.11.0 ... 3 years ago
3.12.0-next.0 ... 3 years ago
3.11.0-next.1 ... 3 years ago
3.10.0 ... 3 years ago
3.11.0-next.0 ... 3 years ago
3.10.0-next.1 ... 3 years ago
3.9.0 ... 3 years ago
3.10.0-next.0 ... 3 years ago
3.8.0 ... 3 years ago
3.9.0-next.0 ... 3 years ago
3.8.0-alpha-image-service.24 ... 3 years ago
3.8.0-alpha-image-service.25 ... 3 years ago
3.7.0 ... 3 years ago
3.7.0-alpha-image-service.75 ... 3 years ago
3.8.0-next.0 ... 3 years ago
3.6.0 ... 3 years ago
3.6.0-alpha-ts-jit.60 ... 3 years ago
3.7.0-next.0 ... 3 years ago
3.5.0 ... 3 years ago
3.6.0-next.0 ... 3 years ago
3.4.0 ... 3 years ago
3.5.0-next.0 ... 3 years ago
3.3.0 ... 3 years ago
3.4.0-next.0 ... 3 years ago
3.2.0 ... 3 years ago
3.3.0-next.0 ... 3 years ago
3.1.0 ... 3 years ago
3.2.0-next.0 ... 3 years ago
3.0.0 ... 3 years ago
3.1.0-next.0 ... 3 years ago
3.0.0-zz-next.2 ... 3 years ago
2.14.0 ... 3 years ago
3.0.0-zz-next.1 ... 3 years ago
3.0.0-zz-next.8 ... 3 years ago
3.0.0-next.1 ... 3 years ago
3.0.0-next.0 ... 3 years ago
3.0.0-alpha-9689ff.13 ... 3 years ago
2.14.0-alpha-qe-sm.46 ... 3 years ago
3.0.0-alpha-9689ff.36 ... 3 years ago
3.0.0-alpha-9689ff.34 ... 3 years ago
3.0.0-alpha-9689ff.24 ... 3 years ago
3.0.0-alpha-9689ff.22 ... 3 years ago
3.0.0-alpha-9689ff.17 ... 3 years ago
3.0.0-alpha-9689ff.8 ... 3 years ago
2.14.0-next.2 ... 3 years ago
2.14.0-next.1 ... 3 years ago
2.13.0 ... 3 years ago
3.0.0-alpha-9689ff.5 ... 3 years ago
2.14.0-next.0 ... 3 years ago
3.0.0-alpha-9689ff.27 ... 3 years ago
2.12.0 ... 3 years ago
2.13.0-next.0 ... 3 years ago
2.12.0-next.3 ... 3 years ago
2.12.0-next.2 ... 3 years ago
2.12.0-next.1 ... 3 years ago
2.11.0 ... 3 years ago
2.12.0-next.0 ... 3 years ago
2.10.0 ... 3 years ago
2.11.0-next.0 ... 3 years ago
2.10.0-next.1 ... 3 years ago
2.9.0 ... 3 years ago
2.10.0-next.0 ... 3 years ago
2.8.0 ... 4 years ago
2.9.0-next.0 ... 4 years ago
2.7.1 ... 4 years ago
2.8.0-next.1 ... 4 years ago
2.7.0 ... 4 years ago
2.8.0-next.0 ... 4 years ago
2.7.0-next.2 ... 4 years ago
2.7.0-next.1 ... 4 years ago
2.6.0 ... 4 years ago
2.7.0-next.0 ... 4 years ago
2.5.0 ... 4 years ago
2.6.0-next.0 ... 4 years ago
2.4.0 ... 4 years ago
2.5.0-next.0 ... 4 years ago
2.3.0 ... 4 years ago
2.4.0-next.0 ... 4 years ago
2.3.0-next.1 ... 4 years ago
2.2.0 ... 4 years ago
2.3.0-next.0 ... 4 years ago
2.1.0 ... 4 years ago
2.2.0-next.0 ... 4 years ago
2.0.0 ... 4 years ago
2.0.0-v3rc.0 ... 4 years ago
2.1.0-next.1 ... 4 years ago
2.0.0-reach-router.186 [deprecated] ... 4 years ago
2.1.0-next.0 ... 4 years ago
2.0.0-next.0 ... 4 years ago
1.10.0 ... 4 years ago
1.11.0-next.0 ... 4 years ago
1.9.0 ... 4 years ago
1.10.0-next.0 ... 4 years ago
1.8.0 ... 4 years ago
1.9.0-next.0 ... 4 years ago
1.7.0 ... 4 years ago
1.8.0-next.0 ... 4 years ago
1.6.0 ... 4 years ago
1.7.0-next.0 ... 4 years ago
1.5.0-image-helpers.58 ... 4 years ago
1.5.0 ... 4 years ago
1.6.0-next.0 ... 4 years ago
1.4.0 ... 4 years ago
1.5.0-next.0 ... 4 years ago
1.4.0-next.1 ... 4 years ago
1.4.0-next.0 ... 4 years ago
1.3.13 ... 4 years ago
1.3.12 ... 4 years ago
1.3.11 ... 4 years ago
1.3.10 ... 4 years ago
1.3.9 ... 4 years ago
1.3.8 ... 4 years ago
1.2.3-unifiedroutes.76 ... 4 years ago
1.3.6 ... 5 years ago
1.3.5 ... 5 years ago
1.3.4 ... 5 years ago
1.3.3 ... 5 years ago
1.3.2 ... 5 years ago
1.3.1 ... 5 years ago
1.3.0 ... 5 years ago
1.2.4 ... 5 years ago
1.2.3 ... 5 years ago
1.2.2 ... 5 years ago
1.2.1 ... 5 years ago
1.2.0 ... 5 years ago
1.1.24 ... 5 years ago
1.1.23 ... 5 years ago
1.1.22 ... 5 years ago
1.1.21 ... 5 years ago
1.1.20 ... 5 years ago
1.1.18 ... 5 years ago
1.1.16 ... 5 years ago
1.1.15 ... 5 years ago
1.1.14 ... 5 years ago
1.1.13 ... 5 years ago
1.1.12 ... 5 years ago
1.1.11 ... 5 years ago
1.1.10 ... 5 years ago
1.1.8 ... 5 years ago
1.1.7 ... 5 years ago
1.1.6 ... 5 years ago
1.1.6-otp-test.69 ... 5 years ago
1.1.6-otp-test.68 ... 5 years ago
1.1.5 ... 5 years ago
1.1.4 ... 5 years ago
1.1.3 ... 5 years ago
1.1.2 ... 5 years ago
1.1.1 ... 5 years ago
1.1.0 ... 6 years ago
1.0.15 ... 6 years ago
1.0.14 ... 6 years ago
1.0.13 ... 6 years ago
1.0.12 ... 6 years ago
1.0.11 ... 6 years ago
1.0.10 ... 6 years ago
1.0.9 ... 6 years ago
1.0.8 ... 6 years ago
1.0.7 ... 6 years ago
1.0.6 ... 6 years ago
1.0.5 ... 6 years ago
1.0.4 ... 6 years ago
1.0.3 ... 6 years ago
1.0.2 ... 6 years ago
1.0.1 ... 6 years ago
1.0.0 ... 6 years ago
1.0.0-rc.4 ... 6 years ago
1.0.0-rc.3 ... 6 years ago
1.0.0-rc.2 ... 6 years ago
1.0.0-rc.1 ... 6 years ago
1.0.0-rc.0 ... 6 years ago
1.0.0-beta.3 ... 6 years ago
1.0.0-beta.2 ... 6 years ago
1.0.0-beta.1 ... 6 years ago