---
title: Group field
description: Display multiple record keys as one composite value.
---

A group field combines multiple fields into one displayed property. Use it for
an address, a person name, or another value that is stored in separate record
keys but reads as one item.

Grouping happens when you compose the view. The raw record stays flat. The SDK
remaps the child values and puts them under the group name in the protocol data.

## API

```ts
fields.group<Name extends string>(
  name: Name,
  fields: Nodeable<Field>[],
  options?: GroupFieldOptions
): GroupFieldBuilder<Name>
```

| Option        | Input    | Result                                    |
| ------------- | -------- | ----------------------------------------- |
| `label`       | `string` | Sets the text shown for the group.        |
| `description` | `string` | Adds supporting text for the group label. |

`configure(options)` returns a configured clone. `clone()` returns an
independent copy with the same child fields and options. `configure` cannot
replace the child fields because that would define a different group.

The child field order controls the value order used by the renderer.

## Basic group field

Declare the raw fields on the resource. Create the group when you select fields
for the datalist.

<BacklitExample path="fields/group/basic" view="detail" />

## Description

The group description applies to the complete composite value.

<BacklitExample path="fields/group/description" view="detail" />

## Child fields

Each child keeps its field kind and presentation options. The SDK remaps every
child value before it creates the grouped protocol data.

<BacklitExample path="fields/group/child_fields" view="detail" />

## Nested group

A group can contain another group. The protocol keeps the same nested field and
data structure.

<BacklitExample path="fields/group/nested" view="detail" />

## Clone

Use `configure` to reuse the child field set with different group options. The
original group does not change.

<BacklitExample path="fields/group/clone" view="detail" />

## All options

You can use a label, description, child fields, and Panel composition with the
same group.

<BacklitExample path="fields/group/all_options" view="detail" />

## Form input

The input role uses a nested object at the group name. For an address group,
seed `address: { city, country }`; the submitted payload has the same structure.
Condition paths include the group name, such as `address.country`. Lookup
arguments in the group must name members of that group.

`resource.group(fields)` creates an anonymous group for a relation display.
Use a named `fields.group` when the group must occupy a record key in the output.