Group Field - Vextro Docs

The group field nests related fields under a single key. Unlike the array field, a group stores exactly one object. Groups are useful for organizing related fields like SEO metadata, addresses, or configuration sections without creating separate collections.

Config Options

Option	Type	Default	Description
`fields`	`Record<string, Field>`	required	Sub-field definitions for the group
`label`	`string`	—	Display label for the group header
`description`	`string`	—	Description shown below the header
`collapsible`	`boolean`	`false`	Whether the group can be collapsed
`collapsed`	`boolean`	`false`	Whether the group starts collapsed
`flat`	`boolean`	`false`	Flatten group fields into the parent level instead of nesting under the group name. Fields are stored flat in the document rather than under a nested key.
`required`	`boolean`	`false`	Whether the group object is required

Example Usage

import { f } from "vextro";

const fields = {
  seo: f.group({
    label: "SEO",
    fields: {
      metaTitle: f.text(),
      metaDescription: f.textarea(),
      ogImage: f.image({ relationTo: "media" }),
    },
  }),
  advancedOptions: f.group({
    label: "Advanced Options",
    collapsible: true,
    collapsed: true,
    fields: {
      cacheControl: f.text({ placeholder: "max-age=3600" }),
      customHeaders: f.json(),
    },
  }),
};

Flat groups

When flat is true, the group's fields are stored at the parent document level instead of nested under the group key. This is useful for organizing fields visually in the admin UI without affecting the document structure.

const fields = {
  meta: f.group({
    flat: true,
    label: false,
    sidebar: true,
    sidebarSection: "SEO",
    fields: {
      metaTitle: f.text(),
      metaDescription: f.textarea(),
      ogImage: f.image({ relationTo: "media" }),
    },
  }),
};

With flat: true, the stored document contains { metaTitle: "...", metaDescription: "...", ogImage: "..." } at the top level rather than { meta: { metaTitle: "...", ... } }. The group header still renders in the admin UI when label is set, providing visual organization without structural nesting.

Nesting and Conditions

Groups can be nested inside other groups or array fields. They also support conditional visibility -- when a condition evaluates to false, the entire group is hidden and the field becomes optional in the schema.

externalLinkOptions: f.group({
  condition: { field: "linkType", equals: "external" },
  fields: {
    openInNewTab: f.checkbox(),
    nofollow: f.checkbox(),
  },
})

Admin Options

All common admin options are supported including condition, sidebar, sidebarSection, sidebarCollapsed, listColumn, and viewTransition. See Overview for details.

Stored Data

Group fields store a nested object: { seo: { metaTitle: "My Page", metaDescription: "...", ogImage: "..." } }.