Custom Globals in Payload CMS
Suppose you need to store site settings — logo, contacts, social media. Collections are not suitable: it's not a list but a single record. In Payload CMS, Globals are the solution — a single editable object with its own field schema. Misusing collections for global data leads to duplicate records and complicates administration. Globals solve this: a single entry point for all settings, versioning, and flexible access control. We help design and implement custom Globals for your project: from basic settings to nested navigation with hooks and access control.
"Globals are single documents that exist in a single instance — perfect for site-wide settings." — Payload CMS Documentation
Why Globals instead of collections?
Average API response time for Globals is ~50 ms, while for collections it's ~150 ms due to pagination and filtering. This yields up to 200% performance gain per page render. Additionally, administration is simplified: the content manager sees one form, not a list of records where mistakes are easy. On one project, after switching from collections to Globals, updating site settings dropped from 2 hours to 5 minutes — a 90% time savings.
How to add a custom Global
// globals/Settings.ts import { GlobalConfig } from 'payload/types' const Settings: GlobalConfig = { slug: 'settings', label: 'Site Settings', access: { read: () => true, update: ({ req: { user } }) => user?.role === 'admin', }, fields: [ { name: 'siteName', type: 'text', required: true, label: 'Site Name', }, { name: 'logo', type: 'upload', relationTo: 'media', }, { name: 'contactEmail', type: 'email', }, { name: 'socialLinks', type: 'array', fields: [ { name: 'platform', type: 'select', options: ['telegram', 'vk', 'youtube', 'instagram'], }, { name: 'url', type: 'text' }, ], }, { name: 'defaultSeo', type: 'group', label: 'Default SEO', fields: [ { name: 'title', type: 'text' }, { name: 'description', type: 'textarea' }, { name: 'ogImage', type: 'upload', relationTo: 'media' }, ], }, ], } export default Settings Why access control matters?
Without access control, any authenticated user can edit global settings. In the example above, we allow read to everyone and update only to admins. This reduces the risk of accidental data corruption. For finer control, use beforeChange and afterChange hooks to check roles or additional conditions. A common mistake is opening update to all editors, leading to conflicts. We recommend assigning a responsible person for configuration.
Navigation Global with nested links
// globals/Navigation.ts const Navigation: GlobalConfig = { slug: 'navigation', fields: [ { name: 'items', type: 'array', fields: [ { name: 'label', type: 'text', required: true }, { name: 'link', type: 'group', fields: [ { name: 'type', type: 'radio', options: ['internal', 'external'], defaultValue: 'internal', }, { name: 'page', type: 'relationship', relationTo: 'pages', admin: { condition: (_, { type }) => type === 'internal' }, }, { name: 'url', type: 'text', admin: { condition: (_, { type }) => type === 'external' }, }, ], }, { name: 'children', type: 'array', fields: [ { name: 'label', type: 'text' }, { name: 'page', type: 'relationship', relationTo: 'pages' }, ], }, ], }, ], } Integrating Globals with Next.js
Server-side rendering is optimal. Use getPayload to fetch Globals at the layout level. This makes settings available on all pages without extra requests.
// app/(frontend)/layout.tsx import { getPayload } from 'payload' import config from '@payload-config' export default async function RootLayout({ children }) { const payload = await getPayload({ config }) const settings = await payload.findGlobal({ slug: 'settings' }) const navigation = await payload.findGlobal({ slug: 'navigation' }) return ( <html> <body> <Header nav={navigation} logo={settings.logo} /> <main>{children}</main> <Footer settings={settings} /> </body> </html> ) } For client-side access, use REST API: GET /api/globals/settings. Configure ISR to update data without full rebuild.
Example of complex navigation structure with submenus
Nesting can be unlimited — use recursive schemas via arrays. For frontend rendering, you'll need a NavItem component that renders itself for children.Hooks for complex logic
beforeChange and afterChange hooks allow side effects. For example, when the URL changes in settings, automatically regenerate the sitemap.
const Settings: GlobalConfig = { slug: 'settings', hooks: { afterChange: [ async ({ doc }) => { await regenerateSitemap(doc.siteUrl) }, ], }, fields: [/*...*/], } Globals vs Collections comparison
| Criterion | Globals | Collections |
|---|---|---|
| Number of documents | One | Many |
| Use case | Settings, configuration | Content, blog, products |
| API endpoint | /api/globals/{slug} | /api/{slug} |
| Admin panel | Single form | List with form |
| Versioning | Supported | Supported |
| Hooks | Full hooks | Full hooks |
| Average API response time | 50 ms | 150 ms |
| Admin simplicity | High | Medium |
| Risk of duplication | None | High |
Globals are 3x faster. Order a consultation to optimize your project — we'll help implement Globals and reduce server load.
Work process
- Analysis: define necessary Globals and their fields, considering access and versioning requirements.
- Design: develop schema, configure relationships and hooks, plan frontend integration.
- Implementation: write Globals code in TypeScript, integrate with Next.js or other frameworks.
- Testing: verify roles, versioning, caching, load testing.
- Deployment: set up CI/CD, backups, document API.
Timeline
Setting up 2 to 4 basic Globals (settings, navigation, footer, SEO) takes from 1 to 3 business days, including frontend integration. Complex hooks or custom fields may extend to 5 days. Get a free preliminary estimate.
What's included
- Globals source code with comments and TypeScript types.
- Documentation for fields, API, and admin panel.
- Frontend integration (Next.js, Nuxt, React).
- Consultation on access and security setup.
- Post-deployment support for 2 weeks.
We have experience with Payload CMS in commercial projects (5+ implementations). Contact us for a detailed discussion of your project. Order a consultation on Payload setup — we'll propose a turnkey solution.