Gatsby + Cockpit Layout Field

An Introduction on how to use Cockpit Layout Field in your Gatsby Project

If you ever worked with Cockpit Headless CMS you surely have met the layout field. It enables us to visually arrange components. It is even possible to define custom components corresponding to React Components we will us in Gatsby.

So let’s have a look on how to use the Layout field with custom components in your next Gatsby Project.

This article extends the “Getting Started with Gatsby and Cockpit” guide. So I will assume that you already have a working Gatsby project running with a pages collection. If this is not the case you can either download the files from the getting started guide (part 2) or use this project’s files from the project repository. The cockpit installation is living in the cockpit folder. You may have to generate a new API key.

Update Cockpit Collection

The first step is to update our Cockpit pages collection.

If you started with the getting started guide, edit the content field and set its type from Wyswyg to Layout. Otherwise make sure you have some Layout field in you collection. In our example this field is named content.

Update GraphQL Queries

We changed the collection so we will have different data in the GraphQL query. As the Layout field is really flexible we want the data as an object. The gatsby-plugin-cockpit plugin parses Layout fields and gives us all the layout components as an object. You can fetch this with <field name>_parsed. The new home query looks now like:

page(slug: { eq: "home" }) {

Create React Components

We want every block inside of the Cockpit Layout field and the field itsem to be reflected as a React Component in our Gatsby project. So we will have to create a single component for every single block.

Let’s start with the main CockpitLayout Component. This one maps the blocks with the React components. First it defines the available components and it renders the components with the related tag.

The available components are defined through an object mapping the Cockpit block names as keys with the React components as values. In our case we will have something like this:

// CockpitLayout Components
import CockpitGrid from '../CockpitGrid';
import CockpitSection from '../CockpitSection';
// Components
import Heading from '../Heading';
import ProjectGrid from '../ProjectGrid';
const components = {
Grid: CockpitGrid,
Section: CockpitSection,
Heading: Heading,
ProjectGrid: ProjectGrid,

I sugest you to just copy the CockpitLayout, CockpitGrid, CockpitSection, Heading and ProjectGrid components from the repository. The CockpitGrid and CockpitSection components are generic structural components mapping the Grid and Section blocks from the Layout field.

Those components require some packages. So run npm install — save lodash.upperfirst is-empty classnames in your terminal.

Now that we have our components we can update the page pages/index.js file. We will just replace the page content with the CockpitLayout component so we get the following code:

New pages/index.js File Using the CockpitLayout Component

Add Custom Components to Cockpit

We defined a ProjectGrid component which does no exist in Cockpit yet.

  1. Download the LayoutComponent Cockpit addon
  2. Rename the downloaded folder to LayoutComponents
  3. Put the folder into the Cockpit addons folder
  4. Log in into Cockpit, go to “Settings” > “Layout Components”
  5. Create a new ProjectGrid component which will then be available in the Layout field.
  6. Add the ProjectGrid component to the home page.

Run npm run develop and look at localhost:8000.

This a really small introduction on how to use the Cockpit Layout field in you Gatsby project. I hope it helps!