@kanunilabs/pivotgrid / PivotField

Interface: PivotField<TRow, TCellTemplate, TStyle>

Describes a single field (dimension or measure) in the pivot grid.

Type Parameters

TRow

TRow = any

Shape of source data rows.

TCellTemplate

TCellTemplate = PivotCellTemplate

Custom cell render function type.

TStyle

TStyle = any

Style object type for conditional formatting rules.

Properties

area?

optional area?: PivotArea

Which pivot area this field belongs to.

areaIndex?

optional areaIndex?: number

Position index within the area.

calculateCustomSort?

optional calculateCustomSort?: (a, b, cellA?, cellB?) => number

Custom sort comparator for header values.

Parameters

a

any

b

any

cellA?

PivotCell<any>

cellB?

PivotCell<any>

Returns

number

calculateCustomSummary?

optional calculateCustomSummary?: string | ((options) => void)

The summary for summaryType: 'custom', run once per cell (leaf, subtotal and grand total alike) over that cell's own rows.

A function gets one options object per cell through three phases: 'start' (once), 'calculate' (once per row, in source order, with the row's value in value) and 'finalize' (once). The cell shows totalValue after finalize; other properties you set on the object persist between phases.
A string names an aggregator registered with registry.registerAggregator(id, fn); fn receives the cell's values. An unregistered name is an engine error, not a silent sum.

calculateExpression?

optional calculateExpression?: string | ((row) => string | number)

Row-level expression evaluated via CSP-safe engine.

calculateSummaryExpression?

optional calculateSummaryExpression?: string | ((cellValues) => number)

Summary-level expression combining other data field values.

caption

caption: string

Display label shown in headers and field chooser.

cellTemplate?

optional cellTemplate?: TCellTemplate

Custom cell render function.

conditionalFormatting?

optional conditionalFormatting?: PivotConditionRule<TStyle>[]

Conditional formatting rules evaluated per cell.

dataField?

optional dataField?: string | Extract<keyof TRow, string>

Source property name in the data row.

dataType

dataType: "string" | "number" | "boolean" | "date"

Data type used for encoding, formatting, and grouping.

filterType?

optional filterType?: "include" | "exclude"

Whether filterValues is an include list or exclude list.

filterValues?

optional filterValues?: Set<any>

Active filter values for header filter (include/exclude mode).

format?

optional format?: NumberFormatOptions | DateTimeFormatOptions | ((value) => string)

Intl format options or custom formatter for cell display values.

formulaString?

optional formulaString?: string

formulaType?

optional formulaType?: "row" | "summary"

groupInterval?

optional groupInterval?: number | PivotGroupInterval

Grouping interval: 'year' | 'quarter' | 'month' | 'week' | 'day' for a date field, or a bin width as a number for a number field (100 → 0–99, 100–199, …). 'week' is the ISO 8601 week, Monday first, keyed by its week-year: 2027-01-01 groups under "2026-W53". Dates are read as local calendar dates. 'numeric' and 'custom' have no effect.

id

id: string

Unique identifier for this field.

isCalculated?

optional isCalculated?: boolean

True for calculated (virtual) fields that derive from other fields.

labelFilter?

optional labelFilter?: PivotLabelFilter

Keep only the members whose CAPTION passes a condition — "cities starting with A". Compares the member's value as text, case-insensitively unless caseSensitive; a blank member reads as empty text.

sortBySummaryField?

optional sortBySummaryField?: string

Data field ID to sort rows by summary value.

sortBySummaryPath?

optional sortBySummaryPath?: string

Column path key for sort-by-summary targeting.

sortOrder?

optional sortOrder?: "asc" | "desc"

Sort direction for this field's header values.

summaryDisplayMode?

optional summaryDisplayMode?: PivotSummaryDisplayMode

Post-aggregation display transformation (e.g. percent of total).

summaryType?

optional summaryType?: PivotSummaryType

Aggregation type. The built-ins are computed in the Web Worker; 'custom' runs PivotField.calculateCustomSummary on the main thread over rows the worker grouped.

topN?

optional topN?: number

Show only top N values; requires sortBySummaryField.

topNOthersCaption?

optional topNOthersCaption?: string

Custom caption for the "Others" row when topN is active.

topNShowOthers?

optional topNShowOthers?: boolean

Whether to aggregate remaining values into an "Others" row.

valueFilter?

optional valueFilter?: PivotValueFilter

Keep only the members of this row or column field whose TOTAL for a data field passes a condition — "regions selling over 1 million". Applied per level after the sort and before topN; the totals keep counting every member, as with topN. Tests the summary value, before any summaryDisplayMode.

visible?

optional visible?: boolean

Whether the field is visible in the field chooser.