---
title: Global Configs
label: Globals
order: 30
desc: Set up your Global config for your needs by defining fields, adding slugs and labels, establishing access control, tying in hooks and more.
keywords: globals, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
---

Globals are in many ways similar to [Collections](./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](../database/overview) based on the [Fields](../fields/overview) that you define, and automatically generates a [Local API](../local-api/overview), [REST API](../rest-api/overview), and [GraphQL API](../graphql/overview) 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](../access-control/overview), [Hooks](../hooks/overview), [Admin Options](#admin-options), and more.

To define a Global Config, use the `globals` property in your [Payload Config](./overview):

```ts
import { buildConfig } from 'payload'

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

<Banner type="success">
  **Tip:**
  If you have more than one Global that share the same structure, consider using a [Collection](./collections) instead.
</Banner>

## Config Options

It's often best practice to write your Globals in separate files and then import them into the main [Payload Config](./overview).

Here is what a simple Global Config might look like:

```ts
import { 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,
        },
      ],
    },
  ],
}
```

<Banner type="success">
  **Reminder:**
  For more complex examples, see the [Templates](https://github.com/payloadcms/payload/tree/main/templates) and [Examples](https://github.com/payloadcms/payload/tree/main/examples) directories in the Payload repository.
</Banner>

The following options are available:

| Option              | Description                                                                                                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`access`**        | Provide Access Control functions to define exactly who should be able to do what with this Global. [More details](../access-control/globals).                                                  |
| **`admin`**         | The configuration options for the Admin Panel. [More details](#admin-options).                                                                                                               |
| **`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.                                                                    |
| **`description`**   | Text or React component to display below the Global header to give editors more information.                                                                                                   |
| **`endpoints`**     | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints).                                                                                                      |
| **`fields`** *     | Array of field types that will determine the structure and functionality of the data stored within this Global. [More details](../fields/overview).                                            |
| **`graphQL`**       | Manage GraphQL-related properties related to this global. [More details](#graphql)                                                                                                             |
| **`hooks`**         | Entry point for Hooks. [More details](../hooks/overview#global-hooks).                                                                                                                         |
| **`label`**         | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined.                                                                        |
| **`lockDocuments`** | Enables or disables document locking. By default, document locking is enabled. Set to an object to configure, or set to `false` to disable locking. [More details](../admin/locked-documents). |
| **`slug`** *       | Unique, URL-friendly string that will act as an identifier for this Global.                                                                                                                    |
| **`typescript`**    | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined.                                                                            |
| **`versions`**      | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#global-config).                                                               |

_* An asterisk denotes that a property is required._

### Fields

Fields define the schema of the Global. To learn more, go to the [Fields](../fields/overview) documentation.

### Access Control

[Global Access Control](../access-control/globals) determines what a user can and cannot do with any given Global Document. To learn more, go to the [Access Control](../access-control/overview) documentation.

### Hooks

[Global Hooks](../hooks/globals) 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](../hooks/overview) documentation.

## Admin Options

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

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

```ts
import { GlobalConfig } from 'payload'

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

The following options are available:

| Option            | Description                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **`group`**       | Text or localization object used to group Collection and Global links in the admin navigation. Set to `false` to hide the link from the navigation while keeping its routes accessible. |
| **`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 details](#custom-components).                           |
| **`preview`**     | Function to generate a preview URL within the Admin Panel for this Global that can point to your app. [More details](../admin/preview).           |
| **`livePreview`** | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview).          |
| **`hideAPIURL`**  | Hides the "API URL" meta field while editing documents within this collection.                                                    |
| **`meta`**        | Page metadata overrides to apply to this Global within the Admin Panel. [More details](../admin/metadata).                                                                           |

### Custom Components

Globals can set their own [Custom Components](../admin/components) which only apply to Global-specific UI within the [Admin Panel](../admin/overview). 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:

```ts
import type { SanitizedGlobalConfig } from 'payload'

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

The following options are available:

| Path                           | Description                                                                                                            |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **`elements.SaveButton`**      | Replace the default Save Button with a Custom Component. [Drafts](../versions/drafts) must be disabled.                                    |
| **`elements.SaveDraftButton`** | Replace the default Save Draft Button with a Custom Component. [Drafts](../versions/drafts) must be enabled and autosave must be disabled. |
| **`elements.PublishButton`**   | Replace the default Publish Button with a Custom Component. [Drafts](../versions/drafts) must be enabled.                                  |
| **`elements.PreviewButton`**   | Replace the default Preview Button with a Custom Component. [Preview](../admin/preview) must be enabled.                                         |
| **`views`**                    | Override or create new views within the Admin Panel. [More details](../admin/views).                                     |

<Banner type="success">
  **Note:**
  For details on how to build Custom Components, see [Building Custom Components](../admin/components#building-custom-components).
</Banner>

## 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:

| Option                 | Description                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------- |
| **`name`**             | Override the name that will be used in GraphQL schema generation.                   |
| **`disableQueries`**   | Disable all GraphQL queries that correspond to this global by passing `true`.       |
| **`disableMutations`** | Disable all GraphQL mutations that correspond to this global by passing `true`.     |

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

```ts
import type { GlobalConfig, SanitizedGlobalConfig } from 'payload'
```