How Page Modules Work in Gatsby


Page Modules in Agility CMS are the functional components that make up a page. Editors use these to compose what type of content is on each page and in what order they appear.

Developers define what page modules are available in the CMS and what fields they have. Each module defined in Agility CMS should correspond to a React Component in your Gatsby site.

Generally speaking, if you don't have any modules defined or editors don't add modules to pages, then there won't be anything to output for your pages.

Pages, Page Templates, Content Zones & Modules

Learn how pages are generated and rendered

What is in a Page Module?

A Page Module in Agility CMS has a name and fields.

The name is a friendly representation of the module's intended functionality such as Posts Listing or Rich Text Area. This way, editors can easily identify them and add them to pages appropriately. 

Fields represent content that can be managed by editors. These fields are then used in code (passed as props) to display the content the editor intended.

An Example

In the agility-gatsby-starter site, the name of the page module 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 module has a reference name of RichTextArea in the CMS, then while the page is being rendered by the gatsby-source-agilitycms plugin, it will look for ./src/modules/RichTextArea.js in the ./src/modules directory.


Internally, the <ContentZone /> component will dynamically import the module and pass all the field values for that module as item in the props.

import React from 'react';
import { renderHTML } from '../agility/utils'

const RichTextArea = ({ item }) => {

    return (
        <section className="container">
            <div dangerouslySetInnerHTML={renderHTML(item.customFields.textblob)}></div>

export default RichTextArea;

Did you notice that we haven't used any GraphQL to get our data? That's because the data is already retrieved in the initial GraphQL page query and it simply passed as props to our UI.

How to Query GraphQL in a Page Module

While it's convenient that the fields on your modules are automatically passed to your React components, there will be cases where you'll need to access content that is not associated with your modules, such as content stored in Shared Content in the CMS.

For these cases, you'll need to formulate a Static GraphQL query. At the time of writing, you are limited to using a Static Query although, with the upcoming addition of React Suspense, it is expected this limitation will be addressed soon.

An example Static Query used in a PostListing module that lists blog posts:

export default (props) => (
        query PostListingModuleQuery {
              filter: {
                properties: { referenceName: { eq: "posts"}}
              limit: 10
            ) {
                nodes {
                    customFields {
                        imageLocalImg {
                            childImageSharp {
                                fluid(quality: 90, maxWidth: 480, maxHeight: 350) {
                    sitemapNode {
                    properties {
		render={queryData => {
			return (
				<PostsListing posts={queryData.allAgilityPost.nodes} {...props} />

How to Add a new Page Module

If you create a new page module in Agility CMS, then you'll need to create the corresponding React component for it within the ./src/modules directory.

If you don't have React component for your page module, then nothing can be rendered for it on your Gatsby site.

How to Change the Fields

You can alter your fields at any time and they fields values passed to your component will update automatically the next time you run another build.

2 out of 2 found this helpful



Please sign in to leave a comment.