114 lines
3.3 KiB
Markdown
114 lines
3.3 KiB
Markdown
---
|
|
title: "Group Field"
|
|
aliases: [payload-group-field, group-field]
|
|
tags: [payloadcms, fields, group, nested, admin-ui]
|
|
sources: [raw/fields__group.md]
|
|
created: 2026-05-15
|
|
updated: 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
|
|
|
|
```ts
|
|
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
|
|
|
|
```ts
|
|
{
|
|
name: 'pageMeta', // → { pageMeta: { title, description } }
|
|
label: 'Page Meta',
|
|
type: 'group',
|
|
fields: [ ... ],
|
|
}
|
|
```
|
|
|
|
### Presentational group — no nesting, visual grouping only
|
|
|
|
Omit `name`, keep `label`:
|
|
|
|
```ts
|
|
{
|
|
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
|
|
|
|
```ts
|
|
admin: {
|
|
hideGutter: true, // hides the vertical gutter line (useful inside Array/Block)
|
|
}
|
|
```
|
|
|
|
Inherits all base [[wiki/payloadcms/fields-basic|Field Admin options]].
|
|
|
|
## Localization
|
|
|
|
Setting `localized: true` on the group localizes **all** nested fields without marking each individually — one flag covers everything inside.
|
|
|
|
Requires [[wiki/payloadcms/localization|localization enabled]] in the base config.
|
|
|
|
## interfaceName — Reusable TypeScript Interface
|
|
|
|
```ts
|
|
{
|
|
name: 'pageMeta',
|
|
type: 'group',
|
|
interfaceName: 'Meta', // generates: interface Meta { title: string; description: string }
|
|
fields: [ ... ],
|
|
}
|
|
```
|
|
|
|
See [[wiki/payloadcms/typescript|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](https://payloadcms.com/docs/fields/group)
|
|
- Raw: `raw/fields__group.md`
|