# Global Configs

Source: https://payloadcms.com/docs/beta/configuration/globals

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

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

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

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

> **Tip:** If you have more than one Global that share the same structure,
> consider using a [Collection](/docs/v4/configuration/collections.md) instead.

## Config Options

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

Here is what a simple Global Config might look like:

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

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

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](/docs/v4/access-control/globals.md).                                                                                                                                                 |
| `admin`         | The configuration options for the Admin Panel. [More details](#admin-options).                                                                                                                                                                                                                |
| `authorship`    | Automatically track the user that created and last updated this Global via polymorphic `createdBy` / `updatedBy` fields. Enabled by default. Set to `false` to disable, or to `{ createdBy: false }` / `{ updatedBy: false }` to toggle each field. [More details](/docs/v4/configuration/collections.md#authorship). |
| `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](/docs/v4/rest-api/overview.md#custom-endpoints).                                                                                                                                                                                                     |
| `fields` \*     | Array of field types that will determine the structure and functionality of the data stored within this Global. [More details](/docs/v4/fields/overview.md).                                                                                                                                           |
| `graphQL`       | Manage GraphQL-related properties related to this global. [More details](#graphql)                                                                                                                                                                                                            |
| `hooks`         | Entry point for Hooks. [More details](/docs/v4/hooks/overview.md#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](/docs/v4/admin/locked-documents.md).                                                                                                |
| `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](/docs/v4/versions/overview.md#global-config).                                                                                                                                                               |
| `select`        | Function that receives the current `operation`, `req`, and caller's `select`, and returns the final `select` to apply. Useful for forcing fields to be populated for hooks / access control. [More details](/docs/v4/queries/select.md#entity-level-select-config).                                    |

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

### Fields

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

### Access Control

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

### Hooks

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

## Admin Options

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

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

```ts
import type { 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](/docs/v4/admin/preview.md).                                                 |
| `livePreview` | Enable real-time editing for instant visual feedback of your front-end application. [More details](/docs/v4/live-preview/overview.md).                                                           |
| `meta`        | Page metadata overrides to apply to this Global within the Admin Panel. [More details](/docs/v4/admin/metadata.md).                                                                              |

### Custom Components

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

#### General

| Option        | Description                                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Description` | A component to render below the Global label in the Edit View. [More details](/docs/v4/custom-components/edit-view.md#description). |
| `edit`        | Override or create new components within the Edit View. [More details](#edit-view-options).                                |
| `views`       | Override or create new views within the Admin Panel. [More details](/docs/v4/custom-components/custom-views.md).                    |

#### Edit View Options

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

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

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

The following components can be customized within `admin.components.edit`:

| Option                   | Description                                                                                                                                                                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `beforeDocumentControls` | Inject custom components before the Save button. [More details](/docs/v4/custom-components/edit-view.md#beforedocumentcontrols).                                                                                    |
| `editMenuItems`          | Inject custom components within the 3-dot menu dropdown. [More details](/docs/v4/custom-components/edit-view.md#editmenuitems).                                                                                     |
| `SaveButton`             | Replace the default Save Button with a Custom Component. [Drafts](/docs/v4/versions/drafts.md) must be disabled. [More details](/docs/v4/custom-components/edit-view.md#savebutton).                                         |
| `SaveDraftButton`        | Replace the default Save Draft Button with a Custom Component. [Drafts](/docs/v4/versions/drafts.md) must be enabled and autosave must be disabled. [More details](/docs/v4/custom-components/edit-view.md#savedraftbutton). |
| `PublishButton`          | Replace the default Publish Button with a Custom Component. [Drafts](/docs/v4/versions/drafts.md) must be enabled. [More details](/docs/v4/custom-components/edit-view.md#publishbutton).                                    |
| `UnpublishButton`        | Replace the default Unpublish Button with a Custom Component. [Drafts](/docs/v4/versions/drafts.md) must be enabled. [More details](/docs/v4/custom-components/edit-view.md#unpublishbutton).                                |
| `PreviewButton`          | Replace the default Preview Button with a Custom Component. [Preview](/docs/v4/admin/preview.md) must be enabled. [More details](/docs/v4/custom-components/edit-view.md#previewbutton).                                     |
| `Status`                 | Replace the default Status component with a Custom Component. [Drafts](/docs/v4/versions/drafts.md) must be enabled. [More details](/docs/v4/custom-components/edit-view.md#status).                                         |

> **Note:** For details on how to build Custom Components, see [Building Custom
> Components](/docs/v4/custom-components/overview.md#building-custom-components).

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

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