> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frogbot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Group Field

> Nest related fields under an object or group them visually.

The Group field places related fields together in the admin panel. A named group also nests their values under an object; an unnamed group changes only the layout.

## Named groups

```ts theme={"theme":"tokyo-night"}
import type { GroupField } from 'frogbot'

export const seoField: GroupField = {
  name: 'seo',
  type: 'group',
  interfaceName: 'SEO',
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'description',
      type: 'textarea',
    },
  ],
}
```

This produces `seo.title` and `seo.description` in stored records and generated types.

## Presentational groups

Omit `name` to keep nested field values at their existing level:

```ts theme={"theme":"tokyo-night"}
import type { GroupField } from 'frogbot'

export const contactFields: GroupField = {
  type: 'group',
  label: 'Contact',
  fields: [
    {
      name: 'email',
      type: 'email',
    },
    {
      name: 'phone',
      type: 'text',
    },
  ],
}
```

The record has `email` and `phone` at the current level, not inside a `contact` object.

## Config options

Options that describe a stored value apply only to named groups: `interfaceName`, `localized`, `defaultValue`, `validate`, `hooks`, `access`, `saveToJWT`, `virtual`, `disableDuplicate`, `unique`, and `index`. FrogBot ignores them on presentational groups.

| Option | Type | Default | Description |
| - | - | - | - |
| `type` | `'group'` | Required | Selects the Group field. |
| `fields` | `Field[]` | Required | Fields displayed inside the group. |
| `name` | `string` | — | Property name for a named group. Omit it for a presentational group. See [field names](https://docs.frogbot.ai/fields/overview.md#field-names). |
| `interfaceName` | `string` | — | Name of a reusable top-level generated TypeScript interface. Named groups only. |
| `label` | `string \| Record<string, string> \| (({ i18n, t }) => string) \| false` | Generated from `name`, if set | Label shown in the admin panel. Use an object keyed by language code for translations, or `false` to hide the label. |
| `required` | `boolean` | `false` | No built-in effect: groups have no default validator. Mark nested fields `required` or use `validate`. |
| `unique` | `boolean` | `false` | MongoDB only: creates a unique index on the whole stored value. SQL adapters ignore it. |
| `index` | `boolean` | `false` | MongoDB only: creates an index on the whole stored value. SQL adapters ignore it. |
| `localized` | `boolean` | `false` | Stores one value per configured locale. Ignored without [localization](https://docs.frogbot.ai/configuration/localization.md) or inside a localized parent. |
| `defaultValue` | `object` or `({ locale, req, user }) => value` | — | Value used when the field has no value. See [default values](https://docs.frogbot.ai/fields/overview.md#default-values). |
| `validate` | `Validate` | — | Validates the group's object value on save. Groups have no built-in validator. See [validation](https://docs.frogbot.ai/fields/overview.md#validation). |
| `hooks` | `{ beforeValidate, beforeChange, afterChange, afterRead, beforeDuplicate }` | — | Arrays of `FieldHook` functions for each phase. See [field hooks](https://docs.frogbot.ai/hooks/fields.md). |
| `access` | `{ create, read, update }` | Allowed | `FieldAccess` functions for each operation. See [field access control](https://docs.frogbot.ai/access-control/fields.md). |
| `hidden` | `boolean` | `false` | Removes the field from API responses and the admin panel while keeping stored data. |
| `saveToJWT` | `boolean \| string` | `false` | In an auth-enabled collection, copies the value into the user's token. A string sets the token key. See [token data](https://docs.frogbot.ai/authentication/token-data.md). |
| `virtual` | `boolean \| string` | `false` | `true` skips database storage; a string reads a value through a relationship path. Virtual fields are read-only in the admin panel unless `admin.readOnly` is `false`. See [virtual fields](https://docs.frogbot.ai/fields/overview.md#virtual-field-configuration). |
| `disableDuplicate` | `boolean` | `false` | Leaves the value out when a document is duplicated, so the copy uses `defaultValue`. |
| `admin` | `object` | — | Admin-panel options. See [Admin options](#admin-options). |
| `custom` | `Record<string, any>` | — | Server-only metadata for your own code and plugins. Use `admin.custom` for data the browser also needs. |
| `jsonSchema` | `Array<({ jsonSchema }) => JSONSchema4>` | — | Functions that modify the JSON Schema used by [type generation](https://docs.frogbot.ai/typescript/generating-types.md). |

## Admin options

Groups inherit the standard [field admin options](https://docs.frogbot.ai/fields/overview.md#admin-options) and add:

| Option | Type | Default | Description |
| - | - | - | - |
| `hideGutter` | `boolean` | `false` | Removes the vertical gutter and padding shown when the group is nested inside another group. |

## Custom components

```tsx theme={"theme":"tokyo-night"}
import { GroupField } from '@frogbotai/ui/admin'
import type { GroupFieldServerProps } from 'frogbot'

export const CustomGroupField = ({
  clientField,
  path,
  permissions,
  schemaPath,
}: GroupFieldServerProps) => {
  return (
    <GroupField
      field={clientField}
      path={path}
      permissions={permissions}
      schemaPath={schemaPath}
    />
  )
}
```

Use `GroupFieldClientProps` for a client component and `GroupFieldLabelServerProps` or `GroupFieldLabelClientProps` to replace only the label.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.