Configuration Reference

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. Use this page for defaults, behavior, and practical guidance.

Minimal Example

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 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<PivotAxisViewport>
• Default: { offset: 0, limit: 100 }
• Behavior: initial row-axis analytical window hint

engine.columnAxis

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

Realistic Example

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
• Configurator API
• Field Panel
• Server-Side Pivot
• OLAP Best Practices