diff --git a/raw/fields__group.md b/raw/_processed/fields__group.md similarity index 100% rename from raw/fields__group.md rename to raw/_processed/fields__group.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index d725f3e..a8ad4f3 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 | | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 | | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 | -| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 69 | +| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 70 | | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 | | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 | diff --git a/wiki/payloadcms/_index.md b/wiki/payloadcms/_index.md index 0f209ad..d09dd6c 100644 --- a/wiki/payloadcms/_index.md +++ b/wiki/payloadcms/_index.md @@ -70,3 +70,4 @@ | [[wiki/payloadcms/fields-collapsible\|Collapsible Field]] | Presentational-only layout field — groups nested fields under a collapsible header; no DB column; supports dynamic label via `({ data, path })` | raw/fields__collapsible.md | 2026-05-15 | | [[wiki/payloadcms/fields-date\|Date Field]] | Date picker field — ISO 8601 storage, pickerAppearance modes, timezone support with separate `_tz` column, custom UTC offsets, GraphQL enum names | raw/fields__date.md | 2026-05-15 | | [[wiki/payloadcms/fields-email\|Email Field]] | Email field with built-in format validation — unique index, saveToJWT, index, placeholder, autoComplete, custom components | raw/fields__email.md | 2026-05-15 | +| [[wiki/payloadcms/fields-group\|Group Field]] | Nest fields under a shared property (named) or visually group without nesting (presentational); `localized` covers all nested fields at once | raw/fields__group.md | 2026-05-15 | diff --git a/wiki/payloadcms/fields-group.md b/wiki/payloadcms/fields-group.md new file mode 100644 index 0000000..e391d23 --- /dev/null +++ b/wiki/payloadcms/fields-group.md @@ -0,0 +1,114 @@ +--- +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`