---
title: "Globals Config"
aliases: [payload-globals, global-config, singleton-config]
tags: [payloadcms, globals, config, singleton, admin]
sources: [raw/configuration__globals.md]
created: 2026-05-15
updated: 2026-05-15
---

## Overview

Globals are singleton Documents — one document per Global. Use them for site-wide singletons: header nav, footer, banner alerts, app-wide localized strings.

- Each Global auto-generates [[wiki/payloadcms/local-api|Local API]], [[wiki/payloadcms/rest-api|REST API]], and GraphQL API
- If 2+ Globals share the same structure → use a [[wiki/payloadcms/collection-config|Collection]] instead

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

export default buildConfig({
  globals: [NavGlobal, FooterGlobal],
})
```

## Config Options

| Option | Required | Description |
|--------|----------|-------------|
| `slug` | ✓ | Unique URL-friendly identifier |
| `fields` | ✓ | Field schema — same as Collections |
| `access` | | Per-operation access control functions |
| `admin` | | Admin Panel behavior (group, hidden, components) |
| `hooks` | | Lifecycle hooks (beforeRead, afterChange, etc.) |
| `versions` | | Enable drafts/versioning (`true` or config object) |
| `label` | | Display name (auto-generated from slug if omitted) |
| `dbName` | | Override DB table/collection name |
| `description` | | Help text shown in Admin Panel header |
| `endpoints` | | Add custom REST routes |
| `graphQL` | | GraphQL overrides or `false` to disable entirely |
| `lockDocuments` | | Document locking config (`false` to disable) |
| `typescript` | | Override TypeScript interface name |
| `select` | | Function to force-populate fields for hooks/access control |

### Minimal Example

```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',
          required: true,
        },
      ],
    },
  ],
}
```

## Admin Options

Configure via `admin` property in Global Config:

| Option | Description |
|--------|-------------|
| `group` | Nav group label (`false` = hide from nav but keep routes) |
| `hidden` | `true` or function `(user) => boolean` to hide from admin routing |
| `components` | Custom React components (see below) |
| `preview` | Function returning preview URL |
| `livePreview` | Enable real-time live preview |
| `meta` | Page metadata overrides |

### Custom Components

Override via `admin.components`:

```ts
admin: {
  components: {
    Description: '/path/to/CustomDescription',
    edit: {
      SaveButton: '/path/to/CustomSaveButton',
      PublishButton: '/path/to/CustomPublishButton',
      SaveDraftButton: '/path/to/CustomSaveDraftButton',
      UnpublishButton: '/path/to/CustomUnpublishButton',
      PreviewButton: '/path/to/CustomPreviewButton',
      Status: '/path/to/CustomStatus',
      beforeDocumentControls: '/path/to/BeforeControls',
      editMenuItems: '/path/to/MenuItem',
    },
    views: {},
  },
}
```

Draft-gated buttons: `SaveDraftButton`, `PublishButton`, `UnpublishButton`, `Status` — require `versions` with drafts enabled. `SaveButton` — requires drafts **disabled**. `PreviewButton` — requires `admin.preview` configured.

## GraphQL

```ts
// Fully disable
graphQL: false

// Or fine-grained
graphQL: {
  name: 'SiteNav',           // override schema name
  disableQueries: true,      // no queries
  disableMutations: true,    // no mutations
}
```

## TypeScript

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

- `GlobalConfig` — raw config, minimal required fields
- `SanitizedGlobalConfig` — post-sanitization, used internally

## Key Takeaways

- **Globals = singletons**; one document per slug stored in DB
- If structure repeats across multiple Globals → promote to a Collection
- `slug` is the only required property besides `fields`
- Access control, hooks, versions, and admin components work identically to Collections
- GraphQL can be disabled per-Global with `graphQL: false`
- Draft buttons in admin components have hard prerequisites (drafts enabled/disabled)
- `select` option lets you force-populate fields for hooks/access control without leaking data to clients

## Related

- [[wiki/payloadcms/collection-config|Collection Config]] — same shape, multi-document
- [[wiki/payloadcms/local-api|Local API]] — `payload.findGlobal()`, `payload.updateGlobal()`
- [[wiki/payloadcms/rest-api|REST API]] — `GET /api/globals/{slug}`, `POST /api/globals/{slug}`
- [[wiki/payloadcms/authentication-overview|Authentication Overview]] — access control basis
- [[wiki/payloadcms/custom-components|Custom Components]] — building custom admin UI

---

*Source: raw/configuration__globals.md — https://payloadcms.com/docs/configuration/globals*
