Pivot Config

DimensionsPanel

Owns the shared search control and the empty state around the dimensions grid.

DimensionsPanel: ({ dimensions, selection, allowFieldDragging, onDragStart, onDragEnd, onSelectionChange, search, onSearch, i18n, }: DimensionsPanelProps) => preact.JSX.Element;

---

filterPivotDimensions

export function filterPivotDimensions(
  dimensions: PivotConfigDimension[],
  query = '',
  options: PivotFieldSearchOptions = {},
);

---

PivotFieldSearchOptions

interface PivotFieldSearchOptions {
  /** Include dimensions marked hidden in the returned field list. */
    showHidden?: boolean
}

---

pivotConfigUiDependencies

Dependencies

• Required aggregators: Uses Pro aggregation definitions for built-in value aggregation options.
• Required pro-ui: Uses Pro UI helper components and styles for configurator controls.

pivotConfigUiDependencies: PluginDependency[];

---

definePivotConfigurator

The PivotConfigurator component provides a flexible configuration interface for managing pivot table layouts. It allows users to drag and drop dimensions, rows, columns, and values into designated zones, facilitating dynamic pivot table setup.

Features:

• Supports drag-and-drop functionality for configuring rows, columns, and values.
• Enables dynamic selection and removal of dimensions, rows, columns, and values.
• Includes built-in aggregator selection for values based on dimensions.
• Provides customizable i18n support for localization of UI labels and messages.

Usage:

• Import PivotConfigurator and pass in the required dimensions, columns, rows, and values as props.
• Optionally, provide callbacks for onUpdateColumns, onUpdateRows, and onUpdateValues to handle configuration changes.

Example

import { definePivotConfigurator } from '@revolist/revogrid-pro'

definePivotConfigurator(yourElement, {
  dimensions: [...],
  rows: [...],
  columns: [...],
  values: [...],
}, {
  onUpdateColumns: (updatedColumns) => {
    // Handle column configuration changes
  },
  onUpdateRows: (updatedRows) => {
    // Handle row configuration changes
  },
  onUpdateValues: (updatedValues) => {
    // Handle value configuration changes
  },
}, undefined, {
  columnTypes: grid.columnTypes,
  additionalData: grid.additionalData,
})

The PivotConfigurator component is ideal for applications that require flexible, user-driven pivot table customization, especially in data management, reporting, and analytics tools.

Mounts the standalone Pivot configurator into any host element.

Use this when you want the drag-and-drop Pivot field panel outside of the default PivotPlugin wrapper, or when you need to drive Pivot state from an external UI shell.

definePivotConfigurator: (el: HTMLElement, config?: Partial<PivotConfig>, actions?: Partial<PivotConfigurationActions>, diagnostics?: PivotUiDiagnostics | undefined, templateContext?: { columnTypes?: ColumnTypes; additionalData?: unknown }) => () => void;

---

disposePivotConfigurator

Unmounts a standalone configurator and removes classes added by its mount helper.

disposePivotConfigurator: (el: HTMLElement) => void;

---

definePivotFieldPanel

Mounts the compact in-grid Pivot field panel into a host element.

Unlike the standalone configurator, this panel is intended to sit above the Pivot grid and expose the active filter, data, row, and column field areas.

definePivotFieldPanel: (el: HTMLElement, config?: Partial<PivotConfig>, actions?: Partial<PivotConfigurationActions>, layout?: { columns?: (ColumnRegular<ColumnProp, DataType<any, ColumnProp>> | ColumnGrouping<any>)[] | undefined; colSize?: number | undefined; resizedColumns?: ColumnResizeDetail; } | undefined, diagnostics?: PivotUiDiagnostics | undefined, templateContext?: { columnTypes?: ColumnTypes; additionalData?: unknown }) => () => void;

---

disposePivotFieldPanel

Unmounts a compact field panel and removes mount-helper presentation state.

disposePivotFieldPanel: (el: HTMLElement) => void;

---

PivotConfigurationActions

interface PivotConfigurationActions {
  /** Applies several related layout changes as one Pivot regeneration. */
    onUpdateConfiguration?: (patch: PivotConfigurationPatch) => void;
  /** Called whenever the configurator updates the ordered column dimension list. */
    onUpdateColumns?: (cols: ColumnProp[]) => void;
  /** Called whenever the configurator updates the ordered row dimension list. */
    onUpdateRows?: (rows: ColumnProp[]) => void;
  /** Called whenever the configurator updates the selected measures or aggregators. */
    onUpdateValues?: (values: PivotConfigValue[]) => void;
  /** Called whenever the configurator updates the ordered filter field list. */
    onUpdateFilters?: (filters: ColumnProp[]) => void;
  /** Called whenever the configurator changes selected filter values. */
    onUpdateFilterSelections?: (selections: PivotFilterSelectionMap) => void;
  /** Current sorting order used by the field panel. */
    sorting?: SortingOrder;
  /** Called when a field-panel sort control is toggled. */
    onToggleSort?: (prop: ColumnProp) => void;
  /** Called when the user clears the active Pivot layout. */
    onResetLayout?: () => void
}

---

PivotConfigurationPatch

export type PivotConfigurationPatch = Pick<
  Partial<PivotConfig>,
  'columns' | 'rows' | 'values' | 'filters'
>;

---

PivotConfigurator

PivotConfigurator: ({ dimensions, columns, rows, values, filters, filterSelections, i18n, fieldPanel, showColumns, showRows, showValues, showFilters, onUpdateConfiguration, onUpdateColumns: onUpdateColumnsCallback, onUpdateRows: onUpdateRowsCallback, onUpdateValues: onUpdateValuesCallback, onUpdateFilters: onUpdateFiltersCallback, onUpdateFilterSelections, onResetLayout, diagnostics, }?: Partial<PivotConfigurationComponentProps>) => preact.JSX.Element;

---

PivotFieldPanel

PivotFieldPanel: ({ dimensions, columns, rows, values, filters, filterSelections, fieldPanel, i18n, showColumns, showRows, showValues, showFilters, onUpdateConfiguration, onUpdateColumns, onUpdateRows, onUpdateValues, onUpdateFilters, onUpdateFilterSelections, sorting, onToggleSort, onResetLayout, diagnostics, }?: Partial<PivotFieldPanelProps>) => preact.JSX.Element;

---

DropZone

DropZone: ({ title, panel, items, dimensions, placeholder, i18n, renderItem, onRemove, onDrop, onDragOver, onDragEnter, onItemDragStart, onItemDragEnd, allowFieldDragging, }: DropZoneProps) => preact.JSX.Element;

---

ValueSelector

ValueSelector: ({ value, aggregators, ariaLabel, onUpdateValue, }: ValueSelectorProps) => preact.JSX.Element;

---

FilterSelector

FilterSelector: ({ allLabel, ariaLabel, options, selected, onUpdateSelection, }: FilterSelectorProps) => preact.JSX.Element;

---

PIVOT_DIMENSION_DRAG_MIME

PIVOT_DIMENSION_DRAG_MIME: string;

---

DraggingItem

The item being dragged

interface DraggingItem {
  /** The source panel of the dragging item */
    source: PanelType;
  /** The index of the dragging item in the source panel */
    index: number;
  /** Dragging item */
    prop: ColumnProp;
  /** Ordered field bundle when a dimensions group is dragged. */
    props?: ColumnProp[];
  /** The drag originated from a synthetic dimensions group row. */
    isGroup?: boolean
}

---

PIVOT_CONFIG_EN

PIVOT_CONFIG_EN: {
  fields: string;
  rows: string;
  columns: string;
  values: string;
  filters: string;
  fieldPanel: string;
  rowsPanelHint: string;
  columnsPanelHint: string;
  valuesPanelHint: string;
  filtersPanelHint: string;
  dropFilterFieldsHere: string;
  dragHereRows: string;
  dragHereColumns: string;
  dragHereValues: string;
  dragHereFilters: string;
  dragDimension: (label: string) => string;
  dragDimensionGroup: (label: string) => string;
  searchFields: string;
  noFieldsFound: string;
  otherFields: string;
  swapRowsColumns: string;
  resetLayout: string;
  sortField: (label: string) => string;
  filterValue: (label: string) => string;
  all: string;
  pivotWarnings: string;
  pivotError: string;
  remove: string;
};

---

getPivotFieldPanelRowsWidth

Resolves the pixel width of the Pivot “rows” section based on current grid columns and optional live resize payload.

export function getPivotFieldPanelRowsWidth(
  config: Partial<PivotConfig> | null | undefined,
  columns: (ColumnGrouping | ColumnRegular)[] = [],
  defaultSize = 100,
  resizedColumns?: ColumnResizeDetail,
);

---

ColumnResizeDetail

export type ColumnResizeDetail = Record<number, ColumnRegular> | undefined;

---

hasPivotDiagnostics

export function hasPivotDiagnostics(diagnostics?: PivotUiDiagnostics);

---

PivotUiDiagnostics

interface PivotUiDiagnostics {
  warnings?: string[];
  error?: string
}

---

PivotDiagnostics

PivotDiagnostics: ({ diagnostics, i18n, }: { diagnostics?: PivotUiDiagnostics | undefined; i18n?: { fields: string; rows: string; columns: string; values: string; filters: string; fieldPanel: string; rowsPanelHint: string; columnsPanelHint: string; valuesPanelHint: string; filtersPanelHint: string; dropFilterFieldsHere: string; dragHereRows: string; dragHereColumns: string; dragHereValues: string; dragHereFilters: string; dragDimension: (label: string) => string; dragDimensionGroup: (label: string) => string; searchFields: string; noFieldsFound: string; otherFields: string; swapRowsColumns: string; resetLayout: string; sortField: (label: string) => string; filterValue: (label: string) => string; all: string; pivotWarnings: string; pivotError: string; remove: string; } | undefined; }) => preact.JSX.Element | null;

---

PivotAxes

interface PivotAxes {
  rows: ColumnProp[];
  columns: ColumnProp[]
}

---

transposePivotAxes

transposePivotAxes: (rows: readonly ColumnProp[], columns: readonly ColumnProp[]) => PivotAxes;

---

PivotAxisSwap

PivotAxisSwap: ({ disabled, label, onClick, }: PivotAxisSwapProps) => preact.JSX.Element;

---

usePivotDimensionColumns

export function usePivotDimensionColumns({
  allowFieldDragging,
  nested,
  selectionRef,
  groupPropsRef,
  i18n,
}: PivotDimensionColumnsOptions);

---

usePivotDimensionDrag

export function usePivotDimensionDrag({
  boundaryRef,
  allDimensions,
  groupPropsRef,
  nativeDraggingRef,
  suppressSelectionEventsRef,
  cancelPendingSelection,
  restoreSelectionAfterDragGesture,
  onDragStartRef,
  onDragEndRef,
}: PivotDimensionDragOptions);

---

PivotDimensionEventController

Owns DOM subscriptions and adjacent resources for one dimensions-grid scope. Keeping teardown here prevents listener options and cleanup order from drifting across hooks as interactions evolve.

class PivotDimensionEventController {
  listen<TEvent extends Event>(
    target: EventTarget,
    type: string,
    listener: (event: TEvent) => void,
    options?: boolean | AddEventListenerOptions,
  );

  addCleanup(cleanup: EventCleanup);

  dispose();
}

---

usePivotDimensionGridLifecycle

export function usePivotDimensionGridLifecycle({
  boundaryRef,
  gridRef,
  rows,
  columns,
  plugins,
  grouped,
  nested,
  search,
  groupLabelTemplate,
  searchRef,
  expandedGroupsRef,
  nativeDraggingRef,
  suppressSelectionEventsRef,
  syncSelection,
}: PivotDimensionGridLifecycleOptions);

---

usePivotDimensionSelection

export function usePivotDimensionSelection({
  gridRef,
  rows,
  selection,
  nativeDraggingRef,
  onSelectionChange,
}: PivotDimensionSelectionOptions);

---

createExpandedGroupOverlay

export function createExpandedGroupOverlay(): ExpandedGroupOverlay;

---

readExpandedGroups

export function readExpandedGroups(
  source: Record<string, unknown>[],
  overlay: ExpandedGroupOverlay,
);

---

resolvePivotDimensionGrouping

export function resolvePivotDimensionGrouping(
  rows: PivotDimensionGridRow[],
  search: string,
  overlay: ExpandedGroupOverlay,
  groupLabelTemplate: GroupLabelTemplateFunc,
): GroupingOptions;

---

getPivotDimensionRowSelectPlugin

export function getPivotDimensionRowSelectPlugin(plugins: unknown[]);

---

isPivotDimensionsGridReady

export function isPivotDimensionsGridReady(grid: HTMLRevoGridElement);

---

getPivotDimensionsViewportHeight

export function getPivotDimensionsViewportHeight(
  dimensions: PivotConfigDimension[],
  grouped: boolean,
  otherFieldsLabel: string,
);

---

createPivotDimensionGroupProps

export function createPivotDimensionGroupProps(
  dimensions: PivotConfigDimension[],
  nested: boolean,
  otherFieldsLabel: string,
  getGroupId: (path: string[]) => string,
);

---

PIVOT_DIMENSION_GROUP_PROP

PIVOT_DIMENSION_GROUP_PROP: string;

---

PIVOT_DIMENSION_ROW_TYPE

PIVOT_DIMENSION_ROW_TYPE: string;

---

PIVOT_DIMENSION_COMPACT_ROW_SIZE

PIVOT_DIMENSION_COMPACT_ROW_SIZE: 24;

---

CurrentRef

interface CurrentRef {
  current: T
}

---

ExpandedGroupOverlay

interface ExpandedGroupOverlay {
  expanded: Set<string>;
  collapsed: Set<string>;
  known: Set<string>
}

---

renderPivotDimensionIcon

export function renderPivotDimensionIcon(
  createElement: HyperFunc<VNode> | typeof import('preact').h,
  dimension?: Pick<PivotConfigDimension, 'columnType'>,
);

---

createPivotDimensionGroupLabelTemplate

export function createPivotDimensionGroupLabelTemplate(): GroupLabelTemplateFunc;

---

createPivotDimensionDragCellTemplate

export function createPivotDimensionDragCellTemplate({
  allowFieldDragging,
  selectionRef,
  groupPropsRef,
  i18n,
}: PivotDimensionTemplateOptions): DimensionCellTemplate;

---

createPivotDimensionFieldCellTemplate

export function createPivotDimensionFieldCellTemplate(): DimensionCellTemplate;

---

createPivotDimensionFieldCellProperties

export function createPivotDimensionFieldCellProperties(): DimensionCellProperties;

---

PivotDimensionsGrid

PivotDimensionsGrid: ({ dimensions, allDimensions, selection, allowFieldDragging, search, otherFieldsLabel, i18n, onDragStart, onDragEnd, onSelectionChange, }: PivotDimensionsGridProps) => preact.JSX.Element;

---

getPivotDimensionLabel

export function getPivotDimensionLabel(dimension: PivotConfigDimension);

---

indexPivotDimensionsByProp

export function indexPivotDimensionsByProp(
  dimensions: readonly PivotConfigDimension[],
);

---

getUniquePivotDimensions

export function getUniquePivotDimensions(
  dimensions: readonly PivotConfigDimension[],
);

---

hasPivotDimensionGroups

export function hasPivotDimensionGroups(
  dimensions: readonly PivotConfigDimension[],
);

---

getPivotDimensionGroupPath

export function getPivotDimensionGroupPath(
  dimension: PivotConfigDimension,
): string[];

---

hasNestedPivotDimensionGroups

export function hasNestedPivotDimensionGroups(
  dimensions: readonly PivotConfigDimension[],
);

---

createPivotDimensionGridRows

export function createPivotDimensionGridRows(
  dimensions: readonly PivotConfigDimension[],
  options: {
    grouped: boolean;
    otherFieldsLabel: string;
    allDimensions?: readonly PivotConfigDimension[];
  },
): PivotDimensionGridRow[];

---

getPivotDimensionGroupId

export function getPivotDimensionGroupId(path: readonly string[]);

---

createPivotDimensionTreeRows

Projects variable-depth group paths into a flat source for TreeDataPlugin.

export function createPivotDimensionTreeRows(
  dimensions: readonly PivotConfigDimension[],
  options: {
    otherFieldsLabel: string;
    allDimensions?: readonly PivotConfigDimension[];
  },
): PivotDimensionGridRow[];

---

getSelectedPivotDimensionProps

export function getSelectedPivotDimensionProps(
  state: PivotDimensionSelectionState,
);

---

resolvePivotDimensionSelectionTarget

Resolves where a newly checked dimension should be placed.

export function resolvePivotDimensionSelectionTarget(
  dimension: PivotConfigDimension,
): NonNullable<PivotConfigDimension['selectionTarget']>;

---

reconcilePivotDimensionSelection

Reconciles checkbox state for only the rows currently represented by the dimensions grid. Fields hidden by search are deliberately left untouched.

export function reconcilePivotDimensionSelection(
  state: PivotDimensionSelectionState,
  visibleDimensions: readonly PivotConfigDimension[],
  selectedVisibleProps: ReadonlySet<ColumnProp>,
): PivotDimensionSelectionState;

---

movePivotDimensionBundle

Places an ordered field-group bundle using the same role rules as a single field: axes are exclusive while Filters and Values remain independent.

export function movePivotDimensionBundle(
  state: PivotDimensionLayoutState,
  target: Exclude<PanelType, 'dimensions'>,
  props: readonly ColumnProp[],
  options: {
    index?: number;
    createValue: (prop: ColumnProp) => PivotConfigValue;
  },
): PivotDimensionLayoutState;

---

areColumnPropArraysEqual

export function areColumnPropArraysEqual(
  left: readonly ColumnProp[],
  right: readonly ColumnProp[],
);

---

arePivotValuesEqual

export function arePivotValuesEqual(
  left: readonly PivotConfigValue[],
  right: readonly PivotConfigValue[],
);

---

createPivotConfigValue

export function createPivotConfigValue(
  prop: ColumnProp,
  dimension?: PivotConfigDimension,
): PivotConfigValue;

---

getPivotDimensionAggregators

export function getPivotDimensionAggregators(
  dimension?: PivotConfigDimension,
);

---

movePivotField

Places one source field using Excel-compatible Pivot roles. Rows and Columns are exclusive axis placements. Filters and Values are independent roles, so a field can filter source data without disappearing from an axis or the summarized values.

export function movePivotField(
  state: PivotFieldLayoutState,
  _source: PanelType,
  target: Exclude<PanelType, 'dimensions'>,
  prop: ColumnProp,
  options: {
    index?: number;
    createValue: (prop: ColumnProp) => PivotConfigValue;
  },
): PivotFieldLayoutState;

---

PIVOT_DIMENSION_MODEL

PIVOT_DIMENSION_MODEL: string;

---

PIVOT_DIMENSION_INDEX

PIVOT_DIMENSION_INDEX: string;

---

PIVOT_DIMENSION_LABEL

PIVOT_DIMENSION_LABEL: string;

---

PIVOT_DIMENSION_TREE_ID

PIVOT_DIMENSION_TREE_ID: string;

---

PIVOT_DIMENSION_TREE_PARENT_ID

PIVOT_DIMENSION_TREE_PARENT_ID: string;

---

PIVOT_DIMENSION_ROW_CLASS

PIVOT_DIMENSION_ROW_CLASS: string;

---

PIVOT_DIMENSION_GROUP_PATH

PIVOT_DIMENSION_GROUP_PATH: string;

---

PivotDimensionGridRow (Extended from pivot.config.dimension.model.ts)

interface PivotDimensionGridRow {
  [PIVOT_DIMENSION_MODEL]?: PivotConfigDimension;
  [PIVOT_DIMENSION_INDEX]: number;
  [PIVOT_DIMENSION_LABEL]: string;
  [PIVOT_DIMENSION_TREE_ID]?: string;
  [PIVOT_DIMENSION_TREE_PARENT_ID]?: string | null;
  [PIVOT_DIMENSION_ROW_CLASS]?: string;
  [PIVOT_DIMENSION_GROUP_PATH]?: string[];
  fieldGroup?: string
}

---

PivotDimensionSelectionState

interface PivotDimensionSelectionState {
  rows: ColumnProp[];
  columns: ColumnProp[];
  values: PivotConfigValue[]
}

---

PivotDimensionLayoutState (Extended from pivot.config.dimension.model.ts)

interface PivotDimensionLayoutState {
  filters: ColumnProp[]
}

---

PivotDimensionSelectionChangeDetail

interface PivotDimensionSelectionChangeDetail {
  /** More than one visible leaf changed in the same RowSelect event. */
    bulk: boolean
}