Choose Fields

A Pivot dimension is the reusable definition of a field. It tells Pivot what the field is called, how it should behave in generated headers, and which aggregators are valid when that field is used as a measure source.

Start with your question

For sales by region and quarter, choose Region for Rows, Quarter for Columns and Sales for Values. A field catalog adds friendly names and tells the controls which fields are available. It does not change your source records.

Read Rows, Columns and Values if these areas are new to you. Try moving fields in the live example below, then show multiple measures.

What A Dimension Is

Each dimension is a PivotConfigDimension. In practice it is a partial RevoGrid column definition plus Pivot-specific metadata.

import type { PivotConfigDimension } from '@revolist/pivot';

const dimensions: PivotConfigDimension[] = [
  { prop: 'region', name: 'Region' },
  { prop: 'quarter', name: 'Quarter' },
  {
    prop: 'sales',
    name: 'Sales',
    dataType: 'number',
    allowedRoles: ['values'],
  },
];

prop is the source-of-truth field id. rows, columns, and values all refer back to these same prop values.

How Dimensions Are Reused

Interactive example

Dimensions

Example for Dimensions

Define a field once and place it on Rows, Columns or Values

The example loads when visible.

Reset

• In rows, a dimension becomes part of the leading row hierarchy.
• In columns, a dimension becomes part of the generated header hierarchy.
• In values, the same field acts as the carrier for the aggregated measure.

This shared model is what keeps Pivot configuration consistent. You define a field once, then reuse it on whichever analytical axis makes sense.

Column Options That Matter In Pivot

PivotConfigDimension extends Partial<ColumnRegular>, so the most useful inherited options are:

• prop: The field id Pivot uses everywhere.
• name: Display label for generated headers and configurator entries.
• sortable: Enables sorting of generated members for that dimension.
• order: Initial sort direction for generated members when sorting is enabled.
• filter: Filter metadata carried into generated columns.
• columnType: Lets generated value columns reuse an existing column type.
• cellTemplate: Custom rendering for generated cells.
• columnTemplate: Custom rendering for column headers.
• cellProperties: Per-cell visual or behavioral overrides.
• size, minSize, maxSize: Width behavior for generated columns.

The most important rule is that Pivot does not invent a second metadata model. Generated columns are still RevoGrid columns, and the dimension is where their base behavior comes from.

Aggregators Live On The Dimension

For a first report, use the built-in aggregation IDs such as sum and avg in values. You only need a custom aggregators map when exposing a particular set of operations or an application callback. The map belongs to the field definition.

Advanced: register custom aggregation callbacks

For new local reports, prefer the V2 numeric/scalar presets. The native maps below demonstrate ID registration with default callbacks: they do not declare strict input policies. A nonempty map replaces that field’s built-ins. Datatype metadata controls authoring defaults, not aggregate coercion or validation.

import type { PivotConfigDimension } from '@revolist/pivot';
import { commonAggregators } from '@revolist/revogrid-pro/aggregations';

const marginDimension: PivotConfigDimension = {
  prop: 'margin',
  name: 'Margin',
  aggregators: {
    sum: commonAggregators.sum,
    avg: commonAggregators.avg,
    max: commonAggregators.max,
  },
};

This matters in two places:

• values[].aggregator resolves against the dimension.
• The configurator uses the dimension’s registered aggregators to populate its value selector.

Good Dimension Design

• Keep prop stable. Changing it breaks saved Pivot layouts.
• Use business-friendly name values because generated headers reuse them.
• Define aggregators only where they make semantic sense.
• Avoid using display labels as identifiers. prop should be the identifier, name should be presentation.

Common Mistakes

• Expecting an unused source field to appear in the picker without adding it to the dimension catalog. Referenced fields can be inferred when the catalog is omitted; provide an explicit catalog for additional choices.
• Registering an aggregator on a text field just because the function exists.
• Expecting dimension order to control row or column placement. Placement is controlled by rows and columns, not by the dimensions array order.

Next

Continue with Aggregations to see how measures are resolved from these dimensions.