PayloadCMS Globals Explained: Everything You Need to Know

In this guide, we’re going to go over how to use globals in Payload CMS. Let’s dive in.

Globals are very similar to collections. The primary difference is that collections allow you to create many of the same type of document multiple times. A global, however, corresponds to a single document. Just like collections, you’re able to create as many globals as you need, but none of them will create more than one document.

Globals are stored in your database and have the same fields available to it as collections do. Similarly to collections, globals also automatically generate Local API, REST API, and GraphQL API to query your documents on the frontend.

You’ll use globals for things like header and footer navigation or site-wide banners (like a sticky banner). So let’s create a header navigation as an example.

To get started, you’ll want to create a new directory called “globals.” In it, you’ll create another new directory called Header with a TypeScript file called “config.ts.” Next, import {GlobalConfig} from ‘payload’ at the top of the file, and export a constant called Header and assign the GlobalConfig type to it. You’ll set it equal to an object with the slug and fields options, use “header” for the slug and an empty array for your fields.

From there, you can import this header global into your payload config file by adding it to your globals array.

If you’d like to call the global something else, you can use the label option to change how it’s displayed in the admin dashboard navigation. You’ll still query the global by its slug on the frontend, but you can change the name just like you can for a collection.

Slug and fields are both required in order to initialize a global, but once you have those set, that’s all you really need.

So, we’ll create an array of links for our Header. We can create a new field with type of array and name: headerLinks. In this array, we’ll include an array of fields with a name, destination (which will be a relationship field), and a newTab checkbox. We’ll set the array to have a minRow of 1 and a maxRow of 5, just so our Header nav doesn’t get out of hand.

Now we can use each array item to define our navigation menu.

Just like our collections, you have access to the access, admin, and description options, but you cannot set a global to be your upload collection. You also can’t use it for authentication.

Access

I won’t spend too much time here because access in Globals is exactly the same as it is in collections. You can set read, create, update, and delete options using a boolean or function that takes user as an argument in order to fine-tune access control to your admin dashboard. I’ll cover this in more detail soon.

Admin

While many of the admin options are similar between collections and globals, there are a few key differences. You can still use group to group your global in the admin UI, so for example, we can set group to “navigation” to this global to get it into its own group, where we might put our footer navigation as well.

You can also set hidden to true or a function that takes user as an argument to either hide the global from navigation or from specific users.

Description

Just like collections, you can set this as a text or React component to provide more information to editors about what this global does. For this, we can just include the description option and say something like “This is our navigation menu to be used in the header.” Which will then show up for us in the global view.

Final Thoughts

Globals are by their nature less complicated than collections. Since they use many of the same options as collections but without the added complexity of multiple documents, it’s much easier to manage and add to globals than it would be for collections. However, globals add a layer of powerful flexibility that allows you to set up things like header and footer navigation and site-wide notifications.