How Page Templates work in Gatsby

Page Templates in Agility CMS are how developers can differentiate the styles of certain types of pages, and define where on the page that editors can add Modules (functional components of the page that editors control).

Some sites may only have a single page template and this is re-used across the site, others may have other templates to allow for more flexible layouts.

Pages, Page Templates, Content Zones & Modules

Learn how pages are generated and rendered

What is in a Page Template?

When editors create pages in Agility CMS, they must select which template they'd like to use.

A Page Template consists of a Name and Content Zones.

The Name should represent what the editor can expect from using the Page Template. For example, a site may have templates named One Column Template, Two Column Template, or Blog Template.

A Content Zone is an area defined in the Page Template where an editor can add, edit, or remove modules. A Page Template can have one or many Content Zones.

Learn how to Create Page Templates

An Example

In the agilitycms-gatsby-starter site, the Name of the Page Template is used to find a corresponding react component that matches the same name. If a match is found, that component is dynamically imported and rendered.

For example, if a Page Template has a reference name of OneColumnTemplate in the CMS, then while the page is being rendered by the gatsby-source-agilitycms plugin, it will look for ./src/components/agility-pageTemplates/OneColumnTemplate.jsx in the ./src/components/agility-pageTemplates directory.

Reviewing the example AgilityPage.jsx from our agilitycms-gatsby-starter site, the <AgilityPageTemplate/> component will automatically take care of resolving and rendering the appropriate page template.


From AgilityPage.jsx:

const AgilityPageTemplate = getPageTemplate(\s/g, "")

From MainTemplate.jsx:

import React from "react"
import ContentZone from "../../agility/components/ContentZone"
import { getModule } from "../../components/agility-pageModules"

const OneColumnTemplate = props => {
  return (
    <div id="main-template">
      <ContentZone name="MainContentZone" {...props} getModule={getModule} />
export default OneColumnTemplate

How to Add a New Page Template

When you create a new Page Template within Agility CMS, you'll want to create the corresponding React component for it within the .src/components/agility-pageTemplates directory.

All of the Page Templates that are being used within the site need to be imported into the index file within the .src/components/agility-pageTemplates directory and added allTemplates array:

import MainTemplate from "./MainTemplate";

// All of the Agility Page Template Components that are in use in this site need to be imported into this index file.
// Place Page Templates in allTemplates array below, passing in a name and the component.

const allTemplates = [
{ name: "MainTemplate", template: MainTemplate }
]; export const getPageTemplate = (templateName) => { if (!templateName) return null; const obj = allTemplates.find( (m) => === templateName.toLowerCase() ); if (!obj) return null; return obj?.template; };

If there is no corresponding React component for your Page Template, then nothing can be rendered for it on your Gatsby site.

How to Add a Content Zone

You can alter your content zones at any time, you'll simply have to utilize the <ContentZone /> component within your page template React component. This tells the gatsby build where to render the modules for this content zone in your code.

For example, this means that all modules in MainContentZone for a page are to be rendered here:

<ContentZone name="MainContentZone" {...props} getModule={getModule} />
2 out of 2 found this helpful



Please sign in to leave a comment.