# Drill-Down
URL: https://pro.rv-grid.com/guides/pivot/concepts/drilldown/
Source: src/content/docs/guides/pivot/concepts/drilldown.mdx
Description: Understand row expansion, column collapse, and the state that controls Pivot exploration.
Drill-down lets users move between summary and detail inside the Pivot structure. In the current implementation there are two separate drill-down concepts: grouped row expansion and generated column collapse.

## Row Drill-Down

Row drill-down is enabled when:

- the effective row hierarchy has more than one level
- `collapsed` is a boolean or `expanded` state exists

```ts
const pivot: PivotConfig = {
  rows: ['region', 'rep'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  collapsed: true,
};
```

Behavior:

- `collapsed: true` starts grouped rows collapsed
- `collapsed: false` starts grouped rows expanded
- `expanded` stores per-group overrides using grouped path keys

`PivotPlugin` translates the Pivot row structure into RevoGrid grouping options, then emits `pivot-config-update` when users expand or collapse groups.

## Grouped Row Aggregates

Set `groupAggregations: true` to render aggregate values inside grouped Pivot rows.

```ts
const pivot: PivotConfig = {
  rows: ['region', 'rep'],
  columns: ['year'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  collapsed: true,
  groupAggregations: true,
};
```

Behavior:

- the grouped row still shows the expand/collapse UI and group label
- generated Pivot value columns show the aggregate for the current grouped branch
- nested groups aggregate only their own descendants
- collapsed groups still show their aggregate values

If you hide the grouped row field column (for example with `hide-columns="region"`), you can move the grouped label into the first visible row cell:

```ts
const pivot: PivotConfig = {
  rows: ['region', 'product'],
  columns: ['quarter'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
  collapsed: true,
  groupAggregations: true,
  groupLabelColumn: 'firstVisible',
};
```

`groupLabelColumn` modes:

- `'grouped'` (default): keep label in the grouped field column
- `'firstVisible'`: render label in the first currently visible row cell

Current limitation:

- `groupAggregations` currently applies to the client-side Pivot path
- server-side Pivot still renders grouped labels only unless backend-precomputed grouped aggregates are added

## Column Drill-Down

Column drill-down is controlled by `columnCollapse`.

```ts
columnCollapse: {
  enabled: true,
  collapsed: false,
  aggregator: 'sum',
}
```

Behavior:

- generated Pivot column groups become collapsible
- collapsed groups render a placeholder header/cell
- placeholder cells use a collapsed-bucket aggregator, not a naive sum of visible child cells

Persisted state for generated groups lives in `collapsedColumns`.

## Related Options

- `collapsed`: row drill-down default
- `expanded`: persisted row group expansion state
- `groupAggregations`: render aggregate values inside grouped client-side Pivot rows
- `groupLabelColumn`: choose where grouped row labels render (`'grouped'` or `'firstVisible'`)
- `columnCollapse`: enable and configure generated column collapse
- `collapsedColumns`: persisted generated column collapse state

## Placeholder Behavior

When a column group is collapsed, Pivot can render:

- a default placeholder header based on the group name
- a custom placeholder header or cell template
- a custom collapsed aggregator, globally or per value field

This is useful when a collapsed analytical bucket should still show a meaningful aggregate instead of just hiding all child columns.

## State Persistence

`PivotPlugin` emits `pivot-config-update` as users interact with grouped rows or collapsible columns. That event is the right place to persist the current Pivot state if you want drill-down state to survive reloads.

## Common Mistakes

- Expecting row drill-down with only one row field.
- Expecting grouped rows to show metric values without enabling `groupAggregations`.
- Expecting `columnCollapse` to work without generated column groups.
- Treating `expanded` as UI row indexes. It is persisted grouped state, not viewport position.

## Next

Continue with [Sorting And Filtering](../pivot/sorting-filtering/) or [Plugin Lifecycle](../pivot/plugin-lifecycle/).
