# Configuration Reference
URL: https://pro.rv-grid.com/guides/pivot/concepts/configuration-reference/
Source: src/content/docs/guides/pivot/concepts/configuration-reference.mdx
Description: Complete reference for every public PivotConfig option in the current implementation.
`PivotConfig` is the public configuration model for both client-side and server-side Pivot. This page explains every option in the current implementation and how the options interact.

For raw signatures, see [Pivot Config API](/api/pivot-config/). Use this page for defaults, behavior, and practical guidance.

## Minimal Example

```ts
const pivot: PivotConfig = {
  dimensions: [
    { prop: 'region', name: 'Region' },
    { prop: 'quarter', name: 'Quarter' },
    { prop: 'sales', name: 'Sales', aggregators: commonAggregators },
  ],
  rows: ['region'],
  columns: ['quarter'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
};
```

## Core Data Model

### `dimensions`

Reusable field definitions. This is where you configure field labels, column behavior, and available aggregators.

- Purpose: Define the fields Pivot can reuse.
- Accepted value: `PivotConfigDimension[]`
- Default: `[]`
- Important interactions: `values[].aggregator` resolves against the matching dimension.

### `rows`

Ordered row hierarchy.

- Purpose: Define the vertical analytical hierarchy.
- Accepted value: `ColumnProp[]`
- Default: required
- Important interactions: row drill-down only becomes meaningful when the effective row hierarchy has more than one level.

### `columns`

Ordered generated column hierarchy.

- Purpose: Define the horizontal analytical hierarchy.
- Accepted value: `ColumnProp[]`
- Default: `[]`
- Important interactions: `flatHeaders`, `columnCollapse`, and column totals only matter when column fields exist.

### `values`

Measures to aggregate.

- Purpose: Define which fields are summarized inside each Pivot cell.
- Accepted value: `PivotConfigValue[]`
- Default: required
- Important interactions: values can render as columns or as synthetic rows through `valuesOnRows`.

## Layout Options

### `flatHeaders`

Flattens grouped column headers into single labels.

- Purpose: Reduce visible nesting in generated columns.
- Accepted value: `boolean`
- Default: `false`
- Common pitfall: flat headers still preserve analytical grouping, they only change header presentation. With `flatHeaders: false`, generated Pivot columns use RevoGrid grouped headers so repeated parent labels are visually grouped.

### `mergeValueHeaders`

Merges generated value headers into the terminal column header labels.

- Purpose: Remove repeated measure headers such as `Revenue` under every generated column member.
- Accepted value: `boolean`
- Default: `false`
- Behavior: with one value, terminal columns use the column member label, for example `Q1`; with multiple values, the value label is appended, for example `Q1 Revenue`.
- Important interactions: can be combined with `flatHeaders`; `valuesOnRows` already moves measures out of generated value columns.

### `valuesOnRows`

Moves values into the row hierarchy.

- Purpose: Render measures as synthetic row members.
- Accepted value: `boolean`
- Default: `false`
- Important interactions: affects row drill-down behavior because values become part of the effective row structure.

### `rowTree`

Controls the effective row hierarchy, including where measures appear.

- Purpose: Place the `$values` pseudo-field at the beginning, middle, or end of the row tree.
- Accepted value: `(ColumnProp | '$values')[]`
- Default: derived from `rows`, with `$values` appended only when `valuesOnRows: true`
- Important interactions: when provided, `rowTree` overrides the value placement implied by `valuesOnRows`.

## Configurator Options

### `hasConfigurator`

Enables the built-in Pivot configurator panel.

- Purpose: Let users rearrange fields visually.
- Accepted value: `boolean`
- Default: `false`

### `mountTo`

Custom configurator mount target.

- Purpose: Render the configurator outside the default grid wrapper.
- Accepted value: `HTMLElement`
- Default: internal grid wrapper mount

### `showColumns`

Hide or show the configurator columns zone.

- Purpose: Control configurator UI visibility.
- Accepted value: `boolean`
- Default: `true`

### `showRows`

Hide or show the configurator rows zone.

- Purpose: Control configurator UI visibility.
- Accepted value: `boolean`
- Default: `true`

### `showValues`

Hide or show the configurator values zone.

- Purpose: Control configurator UI visibility.
- Accepted value: `boolean`
- Default: `true`

### `i18n`

Configurator strings.

- Purpose: Override built-in English labels.
- Accepted value: `typeof PIVOT_CONFIG_EN`
- Default: built-in English copy

## Totals

### `totals`

Controls grand totals and subtotals.

- Purpose: Add analytical summary rows and columns.
- Accepted value: `PivotConfigTotals`
- Default: all disabled

Nested options:

- `grandTotal`
- `subtotals`
- `grandTotalLabel`
- `subtotalLabel`
- `suppressSingleChildSubtotals`
- `suppressGrandTotalWhenSingleLeaf`

See [Totals](/guides/pivot/totals/) for behavior examples.

## Drill-Down State

### `collapsed`

Initial row drill-down state.

- Purpose: Enable grouped row expansion behavior.
- Accepted value: `boolean`
- Default: disabled unless `expanded` is provided
- Important note: only matters when the effective row hierarchy has more than one level

### `expanded`

Persisted grouped row expansion state.

- Purpose: Restore row drill-down state.
- Accepted value: `Record<string, boolean>`
- Default: `undefined`

### `groupAggregations`

Render aggregate values inside grouped Pivot drill-down rows.

- Purpose: Show grouped branch aggregates under generated Pivot metric columns, not only the group label.
- Accepted value: `boolean`
- Default: `false`
- Important note: currently applies to the client-side Pivot path. Server-side Pivot still needs backend-precomputed grouped aggregates for exact support.

### `groupLabelColumn`

Controls which visible row cell renders grouped row labels.

- Purpose: Keep grouped labels visible when grouped fields are hidden with column-hide.
- Accepted value: `'grouped' | 'firstVisible'`
- Default: `'grouped'`
- Behavior:
  - `'grouped'` keeps labels in the grouped field column.
  - `'firstVisible'` renders labels in the first currently visible row cell.

### `columnCollapse`

Generated column collapse config.

- Purpose: Enable collapsible Pivot column groups.
- Accepted value: `boolean | PivotColumnCollapseConfig`
- Default: disabled

Nested options when using the object form:

- `enabled`
- `collapsed`
- `aggregator`
- `placeholder`

### `collapsedColumns`

Persisted generated column collapse state.

- Purpose: Restore collapsed column groups.
- Accepted value: `boolean | Record<string, boolean>`
- Default: `undefined`

## Engine Options

### `engine`

Switches between local and remote analytical execution.

- Purpose: Keep the same public Pivot config while changing where computation happens.
- Accepted value: object
- Default: omitted, which keeps current client-side behavior

Nested options:

### `engine.mode`

- Accepted value: `'client' | 'server'`
- Default: omitted
- Behavior: `'server'` makes `PivotPlugin` load through an adapter or remote store

### `engine.adapter`

- Accepted value: `PivotEngineAdapter`
- Behavior: custom execution boundary used directly by the plugin

### `engine.remoteStore`

- Accepted value: `PivotRemoteStore`
- Behavior: framework-agnostic HTTP or transport-backed store used by the server adapter

### `engine.viewId`

- Accepted value: `string`
- Default: `'default'`
- Behavior: backend semantic view or dataset identifier

### `engine.fieldsVersion`

- Accepted value: `string`
- Default: `'local'`
- Behavior: field registry version or checksum

### `engine.rowAxis`

- Accepted value: `Partial`
- Default: `{ offset: 0, limit: 100 }`
- Behavior: initial row-axis analytical window hint

### `engine.columnAxis`

- Accepted value: `Partial`
- Default: `{ offset: 0, limit: 24 }`
- Behavior: initial column-axis analytical window hint

## Realistic Example

```ts
const pivot: PivotConfig = {
  dimensions: [
    { prop: 'region', name: 'Region', sortable: true },
    { prop: 'rep', name: 'Rep' },
    { prop: 'year', name: 'Year' },
    { prop: 'quarter', name: 'Quarter' },
    {
      prop: 'sales',
      name: 'Sales',
      aggregators: commonAggregators,
    },
  ],
  rows: ['region', 'rep'],
  columns: ['year', 'quarter'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  totals: { grandTotal: true, subtotals: true },
  collapsed: true,
  groupAggregations: true,
  hasConfigurator: true,
};
```

## Common Mistakes

- Treating `dimensions` as optional metadata only. They are the field model Pivot depends on.
- Expecting `columns` to be required. A row-only Pivot is valid.
- Using `columnCollapse` without generated column groups.
- Assuming `engine` changes the public config shape. It only changes the execution path.

## Related Guides

- [Plugin Lifecycle](/guides/pivot/plugin-lifecycle/)
- [Configurator API](/guides/pivot/configurator-api/)
- [Field Panel](/guides/pivot/field-panel/)
- [Server-Side Pivot](/guides/pivot/server-side/)
- [OLAP Best Practices](/guides/pivot/olap-best-practices/)
