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