Drill Through

Choose Drill Through from a Pivot value cell’s context menu to inspect the source records that contributed to that cell. The dialog grid uses the compact theme by default and starts read-only, with sorting, resizing, column movement, and filtering enabled. It has its own grid instance; configuring it does not change the main Pivot grid.

Choose available and visible fields

The Columns dropdown supports multiple selections, field-name search, selecting or clearing all search results, and sorting its list in source order, ascending, or descending label order. Sorting this list does not sort source records. Use the detail grid’s column headers to sort records.

const nextConfig = {
  ...pivot.getRuntimeSnapshot()!.config,
  contextMenu: {
    drillThrough: {
      pageSize: 200,
      columns: ['region', 'representative', 'sales'],
      visibleColumns: ['representative', 'sales'],
      columnChooser: true,
    },
  },
};
await pivot.updatePivotConfig(nextConfig);

• columns controls the requested/available field scope. When omitted, the chooser discovers fields in the returned records, excluding internal __ properties. An empty columns array retains automatic discovery.
• visibleColumns controls the initial visible subset. Omit it to show all available columns; use [] to hide all of them. Hidden definitions remain available in the chooser.
• columnChooser: false hides the dropdown; programmatic visibility updates still work.
• pageSize limits the requested/displayed records and defaults to 100.

These settings are serializable in saved reports. Chooser changes apply to the current dialog; use onColumnsChange below to keep application state and pass it as visibleColumns when opening the next dialog. Showing a field through the chooser does not request additional records or fields from the server. Make sure the drill-through provider returns every field users may select.

Configure the full detail grid

Obtain the installed PivotPlugin instance and call setDrillThroughOptions() before opening the dialog. Its grid accepts Partial<Components.RevoGrid> from @revolist/revogrid: theme, column definitions, column types, custom editors, plugins, additional data, row sizing, editing, selection, and other grid properties are supported. Properties are applied after the dialog defaults. Complete grid.columns definitions override generated columns and define the chooser’s available fields, including grouped columns.

import { PivotPlugin } from '@revolist/pivot';

const plugins = await grid.getPlugins();
const pivot = plugins.find(plugin => plugin instanceof PivotPlugin)!;
let visibleColumns = ['representative', 'sales'];

pivot.setDrillThroughOptions({
  grid: {
    theme: 'darkCompact', // Override the compact default.
    rowSize: 32,
    readonly: true,
    additionalData: { currency: 'EUR' },
    columns: [
      { prop: 'representative', name: 'Representative', filter: true, sortable: true },
      {
        prop: 'sales',
        name: 'Sales',
        size: 160,
        filter: 'number',
        sortable: true,
        columnTemplate: () => 'Sales · EUR',
        cellTemplate: (_h, { model, prop }) =>
          new Intl.NumberFormat('en', {
            style: 'currency', currency: 'EUR',
          }).format(Number(model[prop])),
        cellProperties: ({ model, prop }) => ({
          class: { 'negative-sales': Number(model[prop]) < 0 },
        }),
      },
    ],
  },
  onColumnsChange(columns) {
    visibleColumns = [...columns].map(String);
  },
  onGridReady(session) {
    // Use native grid events for cell interaction and other extensions.
    const handleCellClick = (event: Event) => {
      console.log('Detail grid interaction', event, session.context);
    };
    session.grid.addEventListener('click', handleCellClick);
    return () => session.grid.removeEventListener('click', handleCellClick);
  },
});

Generated columns also inherit matching Pivot dimension metadata, including cellTemplate, columnTemplate, cellProperties, column types, and formatters. Explicit grid.columns give you complete control over individual columns and cells. To enable editing, configure readonly: false and any column-level readonly settings. Editing affects the dialog’s records; persisting edits or refreshing Pivot aggregates remains application-owned.

Runtime options apply to future dialogs. setDrillThroughOptions() replaces the previous options; call it with {} to restore defaults. Functions, plugin constructors, and grid objects stay outside report JSON. Reapply these options when creating a new Pivot plugin instance.

Update an open dialog

const session = pivot.getDrillThroughDialog();
if (session) {
  session.setVisibleColumns(['sales']);
  console.log(session.getVisibleColumns());
  console.log(session.getAvailableColumns());
  session.updateGrid({ theme: 'compact', rowSize: 28 });
  // New columns replace the chooser inventory and initially show all new fields.
  session.updateGrid({
    columns: [{ prop: 'sales', name: 'Amount', filter: 'number', sortable: true }],
  });
  // session.close();
}

getDrillThroughDialog() returns undefined when no detail grid is open or while records are still loading. setVisibleColumns() ignores unknown fields and invokes onColumnsChange. getAvailableColumns() returns leaf definitions; column group structure and pinning are retained when hiding/showing fields. Use updateGrid({ columns }) when replacing columns so the chooser stays in sync. Other grid properties can also be updated directly on session.grid.

onGridReady runs after the detail grid is added to the dialog. It may return a cleanup function, which runs once when the dialog closes, is replaced, or its owner is destroyed, including the header close button and Escape paths. The session’s context contains the clicked cell’s Pivot paths and report snapshot.

Client and server records

Client Pivot resolves source records locally. Server Pivot requires a provider with drill-through support and uses the clicked cell paths, requested columns, and record limit. The footer displays the returned record count and the total reported by the provider. Grid customization changes presentation and interaction; it does not change the analytical scope of the drill-through request.