Global Configs

Global configs are in many ways similar to Collections. The big difference is that Collections will potentially contain many documents, while a Global is a "one-off". Globals are perfect for things like header nav, site-wide banner alerts, app-wide localized strings, and other "global" data that your site or app might rely on.

As with Collection configs, it's often best practice to write your Globals in separate files and then import them into the main Payload config.

Options

Option	Description
`slug` \*	Unique, URL-friendly string that will act as an identifier for this Global.
`fields` \*	Array of field types that will determine the structure and functionality of the data stored within this Global. Click here for a full list of field types as well as how to configure them.
`label`	Text for the name in the Admin panel or an object with keys for each language. Auto-generated from slug if not defined.
`description`	Text or React component to display below the Global header to give editors more information.
`admin`	Admin-specific configuration. See below for more detail.
`hooks`	Entry points to "tie in" to collection actions at specific points. More
`access`	Provide access control functions to define exactly who should be able to do what with this Global. More
`versions`	Set to true to enable default options, or configure with object properties. More
`endpoints`	Add custom routes to the REST API. More
`graphQL.name`	Text used in schema generation. Auto-generated from slug if not defined.
`typescript`	An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined.
`custom`	Extension point for adding custom data (e.g. for plugins)
`dbName`	Custom table or collection name for this global depending on the database adapter. Auto-generated from slug if not defined.

\* An asterisk denotes that a property is required.

Simple Global example

1import { GlobalConfig } from 'payload/types'
2
3const 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,
      },
    ],
  },
],
21}
22
23export default Nav

Global config example

You can find a few example Global configs in the Public Demo source code on GitHub.

Admin options

You can customize the way that the Admin panel behaves on a Global-by-Global basis by defining the admin property on a Global's config.

Option	Description
`group`	Text used as a label for grouping collection and global links together in the navigation.
`hidden`	Set to true or a function, called with the current user, returning true to exclude this global from navigation and admin routing.
`components`	Swap in your own React components to be used within this Global. More
`preview`	Function to generate a preview URL within the Admin panel for this global that can point to your app. More.
`livePreview`	Enable real-time editing for instant visual feedback of your front-end application. More.
`hideAPIURL`	Hides the "API URL" meta field while editing documents within this collection.
`forceRenderAllFields `	Forces all fields in the Edit view to render immediately, regardless of scroll position. By default, this is set to `false` to improve performance, as fields are progressively rendered to balance load times. Enabling this option can make it easier to locate fields using browser search (e.g., `CMD+F`).

Preview

Global admin options can accept a preview function that will be used to generate a link pointing to the frontend of your app to preview data.

If the function is specified, a Preview button will automatically appear in the corresponding global's Edit view. Clicking the Preview button will link to the URL that is generated by the function.

The preview function accepts two arguments:

The document being edited
An options object, containing locale and token properties. The token is the currently logged-in user's JWT.

Example global with preview function:

1import { GlobalConfig } from 'payload/types'
2
3export const MyGlobal: GlobalConfig = {
slug: 'my-global',
fields: [
  {
    name: 'slug',
    type: 'text',
    required: true,
  },
],
admin: {
  preview: (doc, { locale }) => {
    if (doc?.slug) {
      return `https://bigbird.com/preview/${doc.slug}?locale=${locale}`
    }
17
    return null
  },
},
21}

Access control

As with Collections, you can specify extremely granular access control (what users can do with this Global) on a Global-by-Global basis. However, Globals only have update and read access control due to their nature of only having one document. To learn more, go to the Access Control docs.

1import { GlobalConfig } from 'payload/types'
2
3// This is the type used for incoming global configs.
4// Only the bare minimum properties are marked as required.

1import { SanitizedGlobalConfig } from 'payload/types'
2
3// This is the type used after an incoming global config is fully sanitized.
4// Generally, this is only used internally by Payload.

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

Global Configs

Options

Simple Global example

Global config example

Admin options

Preview

Access control

Hooks

Field types

TypeScript

I18n