Global Configs

Globals are in many ways similar to Collections, except that 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:

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  globals: [
    // highlight-line
    // Your Globals go here
  ],
})

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:

import type { GlobalConfig } from 'payload'

export const Nav: GlobalConfig = {
  slug: 'nav',
  fields: [
    {
      name: 'items',
      type: 'array',
      required: true,
      maxRows: 8,
      fields: [
        {
          name: 'page',
          type: 'relationship',
          relationTo: 'pages', // "pages" is the slug of an existing collection
          required: true,
        },
      ],
    },
  ],
}

The following options are available:

* 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

The behavior of Globals within the Admin Panel can be fully customized to fit the needs of your application. This includes grouping or hiding their navigation links, adding Custom Components, setting page metadata, and more.

To configure Admin Options for Globals, use the admin property in your Global Config:

import type { GlobalConfig } from 'payload'

export const MyGlobal: GlobalConfig = {
  // ...
  admin: {
    // highlight-line
    // ...
  },
}

The following options are available:

Custom Components

Globals can set their own Custom Components which only apply to Global-specific UI within the Admin Panel. This includes elements such as the Save Button, or entire layouts such as the Edit View.

To override Global Components, use the admin.components property in your Global Config:

import type { SanitizedGlobalConfig } from 'payload'

export const MyGlobal: SanitizedGlobalConfig = {
  // ...
  admin: {
    components: {
      // highlight-line
      // ...
    },
  },
}

The following options are available:

General

Edit View Options

Custom components within the Edit View are configured under admin.components.elements:

import type { GlobalConfig } from 'payload'

export const MyGlobal: GlobalConfig = {
  // ...
  admin: {
    components: {
      elements: {
        // highlight-start
        Status: '/path/to/CustomStatus',
        SaveButton: '/path/to/CustomSaveButton',
        PublishButton: '/path/to/CustomPublishButton',
        // highlight-end
      },
    },
  },
}

The following elements can be customized within admin.components.elements:

GraphQL

You can completely disable GraphQL for this global by passing graphQL: false to your global config. This will completely disable all queries, mutations, and types from appearing in your GraphQL schema.

You can also pass an object to the global's graphQL property, which allows you to define the following properties:

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 SanitizedGlobalConfig.

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.

import type { GlobalConfig, SanitizedGlobalConfig } from 'payload'