obsidian/wiki/payloadcms/fields-group.md

title	aliases	tags	sources	created	updated
Group Field	payload-group-field group-field	payloadcms fields group nested admin-ui	raw/fields__group.md	2026-05-15	2026-05-15

The Group field nests multiple fields under a shared property name in the database and groups them visually in the Admin Panel.

Basic Config

import type { Field } from 'payload'

export const MyGroupField: Field = {
  name: 'pageMeta',       // → nested object key in DB
  type: 'group',
  fields: [               // required — fields nested inside
    { name: 'title', type: 'text' },
    { name: 'description', type: 'textarea' },
  ],
}

Config Options

Option	Required	Description
name	—	Property name in DB (omit for presentational-only)
fields	✅	Array of fields nested inside this group
label		Heading in Admin Panel; defaults to field name
interfaceName		Creates reusable TS interface + GraphQL type
localized		One flag localizes all nested fields at once
defaultValue		Object with defaults for all nested fields
saveToJWT		Include group data in JWT (top-level groups only)
hidden		Hidden from API + Admin UI, still stored in DB
virtual		Not stored in DB at all
validate		Custom validation function
hooks		Field lifecycle hooks
access		Field-level access control
typescriptSchema		Override generated TS type with JSON schema
custom		Plugin extension point

Named vs Presentational Groups

Named group — creates nested object in data

{
  name: 'pageMeta',    // → { pageMeta: { title, description } }
  label: 'Page Meta',
  type: 'group',
  fields: [ ... ],
}

Presentational group — no nesting, visual grouping only

Omit name, keep label:

{
  label: 'Page Meta',  // visual section heading only
  type: 'group',       // no name → no nested object
  fields: [ ... ],
}

Fields appear at the parent document level, not nested.

Admin Options

admin: {
  hideGutter: true,  // hides the vertical gutter line (useful inside Array/Block)
}

Inherits all base wiki/payloadcms/fields-basic.

Localization

Setting localized: true on the group localizes all nested fields without marking each individually — one flag covers everything inside.

Requires wiki/payloadcms/localization in the base config.

interfaceName — Reusable TypeScript Interface

{
  name: 'pageMeta',
  type: 'group',
  interfaceName: 'Meta',   // generates: interface Meta { title: string; description: string }
  fields: [ ... ],
}

See wiki/payloadcms/typescript for generate:types CLI.

Key Takeaways

• Named group → nested object in DB ({ pageMeta: { title, description } })
• Presentational group (no name) → fields remain flat in DB, grouped visually only
• localized: true on group = all nested fields localized at once
• interfaceName creates a reusable TS interface + GraphQL type for the group shape
• hideGutter: true cleans up nested group appearance inside Array/Block fields
• Group fields can contain any field type including other groups

Sources

• Payload CMS Docs — Group Field
• Raw: raw/fields__group.md