Field Metadata

Field metadata is the information Pivot uses to describe fields before they become row groups, column groups, filters, or measures. Use it to give users clearer labels, keep internal fields out of normal field lists, and make generated totals easier to read.

Open the full demo and framework source.

Hidden Dimensions

Interactive example

Field metadata

Search descriptions/props/type/folder and opt into hidden fields

The example loads when visible.

Reset

Mark a dimension as hidden when it should still be available to the Pivot config but should not appear in normal field lists.

const dimensions = [
  { prop: 'region', name: 'Region' },
  { prop: 'quarter', name: 'Quarter' },
  {
    prop: 'internalSegment',
    name: 'Internal Segment',
    description: 'Internal reporting segment.',
    hidden: true,
  },
];

const pivot = {
  dimensions,
  rows: ['region'],
  columns: ['quarter', 'internalSegment'],
  filters: ['internalSegment'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
};

Hidden does not remove the field from the Pivot engine. In this example, internalSegment can still be used in columns and filters; it is only hidden from helper-driven field lists unless you explicitly show hidden fields.

Show Hidden Fields In Search

Use filterPivotDimensions for searchable field lists. Hidden dimensions are omitted by default. Pass { showHidden: true } when you want an admin or advanced-user mode that reveals them.

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

const visibleFields = filterPivotDimensions(dimensions, searchText);

const allFields = filterPivotDimensions(dimensions, searchText, {
  showHidden: true,
});

The helper searches prop, name, description, dataType, and fieldGroup, so descriptions are useful for discovery even when the visible label is short.

Empty And Null Group Labels

Real data often contains empty strings, null, or undefined. Pivot can replace those values with user-facing labels in row and column groups.

const pivot = {
  rows: ['region', 'channel'],
  columns: ['quarter'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
  groupLabels: {
    empty: '(Empty)',
    null: '(No value)',
  },
};

groupLabels.empty is used for empty strings (''). groupLabels.null is used for null and undefined. Without these options, the current implementation displays empty labels for those group members.

Measure Aliases

Each value can have its own display label. Use label for the preferred generated measure name. Use name as a fallback when label is not set.

const pivot = {
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue $' },
    { prop: 'units', aggregator: 'sum', name: 'Units Sold' },
  ],
};

Aliases are useful when the source field name is technical, abbreviated, or shared by multiple reports.

Disabled Subtotals

Global subtotals can stay enabled while specific subtotal rows or subtotal columns are skipped. Target subtotals by axis field or by zero-based axis level.

const pivot = {
  rows: ['region', 'channel', 'product'],
  columns: ['quarter', 'internalSegment'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
  totals: {
    grandTotal: true,
    subtotals: true,
    disabledSubtotals: {
      rows: {
        fields: ['channel'],
      },
      columns: {
        levels: [0],
      },
    },
  },
};

In this example, Pivot keeps subtotal generation enabled overall, skips row subtotals for the channel field, and skips column subtotals at level 0.

Complete Config

const pivot = {
  dimensions: [
    { prop: 'region', name: 'Region', description: 'Sales territory.' },
    { prop: 'channel', name: 'Channel', description: 'Go-to-market channel.' },
    { prop: 'product', name: 'Product' },
    { prop: 'quarter', name: 'Quarter' },
    { prop: 'internalSegment', name: 'Internal Segment', hidden: true },
    { prop: 'revenue', name: 'Revenue' },
    { prop: 'units', name: 'Units' },
  ],
  rows: ['region', 'channel', 'product'],
  columns: ['quarter', 'internalSegment'],
  filters: ['internalSegment'],
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue $' },
    { prop: 'units', aggregator: 'sum', name: 'Units Sold' },
  ],
  groupLabels: {
    empty: '(Empty)',
    null: '(No value)',
  },
  totals: {
    grandTotal: true,
    subtotals: true,
    disabledSubtotals: {
      rows: { fields: ['channel'] },
      columns: { levels: [0] },
    },
  },
};

Common Mistakes

• Expecting hidden: true to prevent a field from being used in rows, columns, filters, or values. It only affects field-list helpers.
• Passing { showHidden: true } to the Pivot config. It belongs to filterPivotDimensions, not pivot.
• Using only groupLabels.empty when the source data contains null or undefined.
• Disabling totals.subtotals and then expecting disabledSubtotals to do anything. Selective disabling only matters when subtotals: true.