Global Configs

Globals are in many ways similar to Collections, except they correspond to only a single Document. You can define as many Globals as your application needs. Each Global Document is stored in the Database based on the Fields that you define, and automatically generates a Local API, REST API, and GraphQL API used to manage your Documents.

Globals are the primary way to structure singletons in Payload, such as a header navigation, site-wide banner alerts, or app-wide localized strings. Each Global can have its own unique Access Control, Hooks, Admin Options, and more.

To define a Global Config, use the globals property in your Payload Config:

1
import { buildConfig } from 'payload'
2
3
export default buildConfig({
4
// ...
5
globals: [
6
// Your Globals go here
7
],
8
})

Config Options

It's often best practice to write your Globals in separate files and then import them into the main Payload Config.

Here is what a simple Global Config might look like:

1
import { GlobalConfig } from 'payload'
2
3
export const Nav: GlobalConfig = {
4
slug: 'nav',
5
fields: [
6
{
7
name: 'items',
8
type: 'array',
9
required: true,
10
maxRows: 8,
11
fields: [
12
{
13
name: 'page',
14
type: 'relationship',
15
relationTo: 'pages', // "pages" is the slug of an existing collection
16
required: true,
17
},
18
],
19
},
20
],
21
}

The following options are available:

OptionDescription
accessProvide Access Control functions to define exactly who should be able to do what with this Global. More details.
adminThe configuration options for the Admin Panel. More details.
customExtension point for adding custom data (e.g. for plugins)
dbNameCustom table or collection name for this Global depending on the Database Adapter. Auto-generated from slug if not defined.
descriptionText or React component to display below the Global header to give editors more information.
endpointsAdd custom routes to the REST API. More details.
fields *Array of field types that will determine the structure and functionality of the data stored within this Global. More details.
graphQL.nameText used in schema generation. Auto-generated from slug if not defined.
hooksEntry point for Hooks. More details.
labelText for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined.
slug *Unique, URL-friendly string that will act as an identifier for this Global.
typescriptAn object with property interface as the text used in schema generation. Auto-generated from slug if not defined.
versionsSet to true to enable default options, or configure with object properties. More details.

* An asterisk denotes that a property is required.

Fields

Fields define the schema of the Global. To learn more, go to the Fields documentation.

Access Control

Global Access Control determines what a user can and cannot do with any given Global Document. To learn more, go to the Access Control documentation.

Hooks

Global Hooks allow you to tie into the lifecycle of your Documents so you can execute your own logic during specific events. To learn more, go to the Hooks documentation.

Admin Options

You can customize the way that the Admin Panel behaves on a Global-by-Global basis. To learn more, go to the Global Admin Options documentation.

TypeScript

You can import types from Payload to help make writing your Global configs easier and type-safe. There are two main types that represent the Global Config, GlobalConfig and SanitizeGlobalConfig.

The GlobalConfig type represents a raw Global Config in its full form, where only the bare minimum properties are marked as required. The SanitizedGlobalConfig type represents a Global Config after it has been fully sanitized. Generally, this is only used internally by Payload.

1
import { GlobalConfig, SanitizedGlobalConfig } from 'payload'
Next

I18n