---
updatedAt: 2026-10-15T14:08:27.000Z
agentTools:
  projectIndex: https://docs.pebblestream.com/llms.txt
---

# template-out-group

Marks the output column that holds the **group key**. The records are bucketed by this column's value: all records of one group are written at the current anchor position, and when the group **changes**, every data column's anchor advances one step in the group's [direction](template-out-down.md) — so each group gets its own row/column of the template.

`pebblestream:template-out-group`

## Syntax

```
pebblestream:template-out-group
```

* No arguments.
* Placed on the **header cell of the column** holding the group key — at most one
  column per worksheet.
* Requires [`template-name`](template-name.md) on the same (output) worksheet.
* Cannot share a column with an anchor (`template-out-header`/`template-out-cell`)
  or a styling directive (`template-out-style`/`template-out-value-type`).

## Example

Template with one summary row per region; output worksheet `Results`:

| column | header   | comment                                        |
| ------ | -------- | ---------------------------------------------- |
| A      | `Region` | `pebblestream:template-out-group`              |
| A      | `Region` | `pebblestream:template-out-right`              |
| B      | `Total`  | `pebblestream:template-out-cell` (header `B2`) |

Records `(EMEA, 100) (EMEA, 20) (APAC, 70)` write `100`/`20` at the first group's
anchor, then the anchor advances one column right and `70` is written for `APAC`.

> **Dynamic group formulas.** When a formula value repeats for *every* group at
> the same relative location, the planner treats it as a *dynamic reference*: the
> formula is written literally once, at the first group's cell, and replayed at
> the shifted cells with adjusted references — exactly like Excel copy/paste.

## Errors

| Error                                 | Cause                                                     |
| ------------------------------------- | --------------------------------------------------------- |
| `dir-too-many-args`                   | Arguments were supplied.                                  |
| `dir-appears-multi`                   | More than one column carries the directive.               |
| `template-out-conflict`               | The group column also has an anchor or styling directive. |
| `missing-the-template-name-directive` | The sheet has no `template-name`.                         |

## Related

* [Template directives](template-directives.md) — the output fill flow
* [template-out-down](template-out-down.md) / [template-out-right](template-out-right.md) — the direction the anchor advances in
* [template-out-header](template-out-header.md) / [template-out-cell](template-out-cell.md) — anchors