Customization and Export

Pivot Charts separate portable model presentation from renderer-wide styling. Use presentation and chartOptions when the choice must persist with one chart. Configure createPivotChartsRenderer when an application needs a shared palette, typography, tooltip, or export pipeline.

The Layout and Display inspectors group related controls into collapsible sections. Layout starts with ordered row and column fields and checkbox measure selection; sorting, ranking, member filters, and the Pivot connection are separate sections. Valid query edits update automatically. Display starts with labels and legend, with appearance, axes, colors, navigation, interaction, and references available in their own sections. Collapsing a section preserves its draft edits. Switching tabs also preserves Display drafts and expanded sections. Presentation, colors, annotations and query edits update automatically. Incomplete numeric or reference edits stay local with validation feedback until valid. Color controls use the shared Pro palette and native color chooser, without a free-text color field. Automatic restores the default color where supported. Reset colors preserves combination layer and axis assignments, including changes still being processed.

The picker captions and swatch names are customizable through localeText.colors.picker.customColor and localeText.colors.picker.colorLabels. Each existing color control policy continues to hide or disable its picker. Apply policy and translation keys are accepted; the inspector no longer renders those actions.

The whole-layout Reset action is hidden by default. To expose it, set pivotChartsUi.controls['query.reset'] = 'enabled'.

Rename section titles with localeText.inspector. Hide or disable a whole section with pivotChartsUi.controls['inspector.<section>']; existing leaf control policies continue to apply. Section IDs are source, fields, sort, filters, connection, presentation, appearance, axes, colors, navigation, interaction, and annotations.

1
grid.pivotChartsUi = {
2
  localeText: {
3
    inspector: { fields: 'Fields to compare', annotations: 'Notes and targets' },
4
  },
5
  controls: {
6
    'inspector.navigation': 'hidden',
7
    'inspector.axes': 'disabled',
8
  },
9
};

Existing chartOptions.heading, colors.heading, annotations.heading, navigation.heading, and interaction.heading overrides remain section-title fallbacks. An explicit inspector title takes precedence.

Pivot Charts consume the report’s committed aggregate values. Configure numeric/scalar eligibility, counts and execution pins in the Pivot aggregation contract. Chart normalization, formatting or a shared dataset shape does not establish identical local/server results or increase arithmetic precision. A remote provider must supply complete aggregates under its backend policy, not averages or distinct totals reconstructed from a visible page.

For an embedded chart mounted with controls: 'standard', set pivotChartsUi.settingsMountTo to an application-owned element to place the configurator in a drawer. The chart fills its original container. The application owns opening and closing the drawer; destroying the chart removes its controls from the target. Chart dialogs retain their own settings panel.

Portable presentation

Interactive example

Chart presentation

Change titles, legend placement, and data labels to compare the chart's presentation.

1
await chart.update({
2
  presentation: {
3
    title: 'Quarterly sales',
4
    subtitle: 'Committed orders only',
5
    legendPosition: 'bottom',
6
    dataLabels: true,
7
    xAxisTitle: 'Region',
8
    yAxisTitle: 'Revenue',
9
  },
10
  theme: 'material',
11
});

legendPosition accepts top, right, bottom, left, or none. theme accepts auto or a renderer-supported theme string. The standard UI offers follow-grid, default, material, compact, dark material, and dark compact choices, plus high contrast and dark high contrast.

Chart-specific options

The catalog generates a typed option schema for every chart:

Option	Availability	Valid values
`showGridLines`	Charts with axes.	Boolean.
`markOpacity`	Every built-in type.	`0.2`–`1` in `0.05` steps.
`strokeWidth`	Line, area, combination, radar line, and radar area.	`1`–`6` in `0.5` steps.
`fillOpacity`	Area-family, area-line, radar area, confidence band, and range area.	`0.1`–`0.9` in `0.01` steps.
`facetScaleMode`	Small multiples.	`independent` (default) or `shared`.

1
await chart.update({
2
  chartOptions: {
3
    showGridLines: false,
4
    markOpacity: 0.9,
5
    strokeWidth: 2.5,
6
  },
7
});

Unsupported keys, out-of-range values, and values that do not align with the declared step are rejected during update and restore.

Small multiples use independent value domains by default. This emphasizes each series’ trend; equal panel heights can represent very different values. Choose shared scales when comparing magnitudes:

1
await chart.update({
2
  chartType: 'smallMultiples',
3
  chartOptions: { facetScaleMode: 'shared' },
4
});

Panels show their scale mode and value ticks. Shared domains use the complete visible series data, including values omitted by path sampling or outside the current viewport. Independent domains use each series’ complete values. Changing visibility can change these domains. Reference lines and notes follow the same panel scales as the plotted data.

Semantic colors and visibility

Portable colors settings complement the renderer palette. The default paletteMode: 'index' preserves palette order; opt into 'semantic' to assign colors by measure and field-qualified member identity across reordering and refresh. Labels do not determine identity. Semantic mode requires field metadata for nonempty member paths; providers supply it through hierarchy definitions or selection fields. Missing metadata is rejected instead of reverting to an unstable index color.

Configured measure IDs keep semantic colors stable when measures are reordered. Without a configured ID, measure identity includes its original configured index to distinguish repeated measures; reordering that configuration can therefore change its palette assignment.

1
await chart.update({
2
  colors: {
3
    paletteMode: 'semantic',
4
    measures: [{
5
      measure: { prop: 'sales', aggregator: 'sum', valueIndex: 0 },
6
      color: '#2563eb',
7
    }],
8
    members: [{
9
      axis: 'row',
10
      path: [{ field: 'region', value: 'North' }],
11
      color: '#f97316',
12
      pattern: 'diagonal',
13
    }],
14
  },
15
});

Member overrides match the exact field-qualified path; they do not implicitly color descendants or synthetic Other members with a matching label. Authored colors accept #RGB or #RRGGBB. Unavailable identities remain dormant so styling can return when a member or series reappears. When measure selectors overlap, the first matching measure-color entry wins. Duplicate exact member paths or measure selectors are rejected.

Supported discrete marks can map their analytical value to color:

1
await chart.update({
2
  colors: {
3
    valueMap: {
4
      type: 'diverging',
5
      min: -100,
6
      midpoint: 0,
7
      max: 100,
8
      colors: ['#2563eb', '#ffffff', '#dc2626'],
9
    },
10
  },
11
});

continuous maps between two colors. conditional applies the first matching numeric gt, lt, equal, or inclusive between rule, with an optional fallback color. Mappings use analytical values, preserve missing observations, and clamp outside explicit domains. Automatic domains use the visible series’ full data, independently of viewport sampling.

Numeric mappings display a separate color key even when the ordinary legend is hidden. Gradient keys show their domain; conditional keys show a bounded set of swatches and the number of additional rules. The Customize controls retain the complete rule list.

Value mapping takes precedence over explicit series/member colors, followed by measure colors and the palette. Mapping is supported for grouped bar and column, heatmap/calendar heatmap, and pie/donut/semi-donut charts. Line colors represent series; numeric mapping of an entire line is unsupported. Aggregated heatmap buckets cannot receive canonical member or value mappings.

For independently visible series, seriesOverrides can persist color and visible. Line-bearing charts also support lineDash and marker:

1
await chart.update({
2
  seriesOverrides: {
3
    [forecastSeriesId]: {
4
      color: '#475569',
5
      visible: true,
6
      lineDash: 'dash',
7
      marker: 'diamond',
8
    },
9
  },
10
  presentation: { legendAction: 'toggleVisibility' },
11
});

Visibility removes a series from plotted geometry, scales, stacks, tooltips, and rendered exports while retaining the canonical chart dataset. Hidden series remain available in the legend and Customize controls. Hiding every series leaves a recoverable empty plot. Appearance and visibility changes do not request new provider data or change the shared Pivot.

Series visibility is supported by bar/column and line/area families, combination charts, annotated time series, and small multiples. Required relationship or financial channels cannot be hidden as independent series. Unsupported authored settings are rejected according to chart capabilities.

colors and seriesOverrides updates replace their whole authored objects; omit them to preserve settings or pass {} to reset. Custom renderers must opt into the new appearance and visibility capabilities.

Reference lines, bands, and notes

Persist thresholds and notes in annotations. References use logical axes: category, primary, or secondary. On horizontal bars, the primary value axis runs horizontally. Secondary references require a combination chart.

1
await chart.update({
2
  annotations: {
3
    references: [
4
      {
5
        id: 'target',
6
        kind: 'line',
7
        axis: 'primary',
8
        value: 2500,
9
        label: 'Sales target',
10
        color: '#dc2626',
11
        lineDash: 'dash',
12
      },
13
      {
14
        id: 'expected-range',
15
        kind: 'band',
16
        axis: 'primary',
17
        min: 1000,
18
        max: 2000,
19
        color: '#2563eb',
20
        opacity: 0.2,
21
      },
22
    ],
23
    notes: [{
24
      id: 'launch',
25
      target: {
26
        row: [{ field: 'region', value: 'North' }],
27
        column: [],
28
        measure: { prop: 'sales', aggregator: 'sum' },
29
      },
30
      text: 'New product launch',
31
      placement: 'above',
32
    }],
33
  },
34
});

Category lines use at; category bands use from and to. Each coordinate is either { scale: 'category', path: [{ field, value }], measure? } or { scale: 'time', value: utcEpochMilliseconds }. Time coordinates require an actual time axis. Category bands span the centers of their semantic endpoints in the current order. They do not create extra category buckets.

References use the existing plot domain: off-domain lines disappear and bands are clipped. They never stretch the scale. Numeric bounds must be finite and ordered; references on logarithmic axes must be positive. In small multiples, a primary reference applies the same authored value to each panel’s own scale.

Notes match exact field-qualified row and column paths plus a measure, rather than labels or array indexes. Use a configured measure ID to distinguish repeated measures; an explicit valueIndex further constrains the match. Group and collapsed aggregate points can have notes. Subtotals, grand totals, synthetic Other members, and ambiguous targets are unavailable.

A missing, hidden, null, off-screen, or omitted-panel target keeps its authored note dormant. When that exact observation returns, the note follows its current value. Drilling to children never reassigns a parent’s note. Nonempty paths require provider field metadata. Notes can anchor observations omitted by visual sampling, and do not intercept chart selection or drill actions.

The Display tab applies valid edits automatically and provides Clear controls for editing references and notes. Annotation edits preserve provider data and survive refresh, unlink, and JSON restoration. Pass annotations: {} to clear them; omit the field to preserve them. Updates replace the whole annotation object. Each array accepts up to 32 entries, IDs up to 128 characters, reference labels up to 256 characters, and nonblank note text up to 512 characters.

Supported families are grouped bar/column, unstacked line/area variants, combination charts, annotated time series, and small multiples. Unsupported families reject authored annotations. Custom renderers opt in through capabilities.annotations. Existing automatic extrema labels are independent of authored notes. Rendered references and notes follow the chart’s label, theme, and image/document export pipeline. The label formatter receives annotationId and annotationKind (reference or note) for authored labels. Notes retain their canonical datum context; numeric reference labels expose the threshold value without pretending to be a data observation. Long labels wrap within the panel, with complete text retained in accessible titles.

Renderer styling

Interactive example

Chart styling and labels

Compare label formatting, typography, and presentation in the chart.

1
const renderer = createPivotChartsRenderer({
2
  className: 'sales-chart',
3
  fontFamily: '"IBM Plex Sans", sans-serif',
4
  categorySeparator: ' / ',
5
  palette: ['#2563eb', '#f97316', '#16a34a'],
6
  theme: ({ theme }) => ({
7
    ...theme,
8
    background: '#fffdf8',
9
    foreground: '#292524',
10
    grid: '#e7e5e4',
11
  }),
12
});

The theme callback receives the resolved light/dark base theme and current render input. Renderer classes, theme colors, palette, fonts, labels, and visible chart options are retained in image and document exports.

Semantic label pipeline

Every visible label passes through one formatter. Kinds are title, subtitle, axisTitle, axisTick, category, legend, data, annotation, summary, and specialized.

1
const renderer = createPivotChartsRenderer({
2
  labels: {
3
    styles: {
4
      title: { fontSize: 20, fontWeight: 700 },
5
      category: { fill: '#475569', fontSize: 11 },
6
      data: { fontWeight: 600 },
7
    },
8
    formatter(context) {
9
      if (context.kind === 'legend') {
10
        return `Measure: ${context.defaultText}`;
11
      }
12
      if (context.kind === 'axisTick' && context.axis === 'y') {
13
        return null;
14
      }
15
      if (context.kind === 'data' && context.formattedValue) {
16
        return {
17
          text: context.formattedValue,
18
          ariaLabel:
19
            `${context.category?.label}: ${context.formattedValue}`,
20
          className: 'sales-chart-value',
21
        };
22
      }
23
      return undefined;
24
    },
25
  },
26
});

Return a string, a structured result, null to suppress one label, or undefined to retain the default. Structured results can override text, accessible text, classes, safe SVG typography, opacity, and visibility.

Annotated time series automatically arranges endpoint and extrema labels inside the plot after applying your formatter and typography. Labels move apart with leaders pointing to their observations. If no clear position fits, the optional label is omitted; the full value remains available on the point’s tooltip and accessible label. Zooming uses the visible observations. Return null for context.kind === 'annotation' to hide these labels and their leaders.

1
const renderer = createPivotChartsRenderer({
2
  tooltip: {
3
    showDelayMs: 100,
4
    hideDelayMs: 60,
5
    followPointer: true,
6
    className: 'sales-chart-tooltip',
7
    formatter(context, defaultContent) {
8
      return {
9
        ...defaultContent,
10
        footer: context.drillable
11
          ? 'Open the next sales level'
12
          : 'Leaf value',
13
      };
14
    },
15
  },
16
});

The formatter receives raw and formatted values, category and series metadata, relationship channels, mark color, and drillability. Return structured content, plain text, an HTMLElement, or null to suppress one tooltip. Set tooltip: false to disable tooltips.

Full localization

pivotCharts.localeText supports deep partial overrides for dialog actions, status and errors, breadcrumbs, gallery tabs/families, all chart names and descriptions, compatibility reasons, chart options, data controls and table, legend overflow, tooltips, accessibility text, context actions, themes, totals, and number formatting.

1
grid.pivotCharts = {
2
  renderer: createPivotChartsRenderer(),
3
  localeText: {
4
    actions: {
5
      exportChart: 'Exportar',
6
      downloadPdf: 'Transferir PDF',
7
      viewData: 'Ver dados',
8
      viewChart: 'Ver gráfico',
9
    },
10
    chartTypes: {
11
      groupedColumn: 'Colunas agrupadas',
12
      boxPlot: 'Diagrama de caixa',
13
    },
14
    renderer: {
15
      formatNumber: (value) =>
16
        new Intl.NumberFormat('pt-PT').format(value),
17
    },
18
  },
19
};

Chart graphics and data export

The built-in SVG renderer exports PNG, SVG, and PDF. CSV is provided by the chart plugin independently of the graphics backend. Use charts.getChartDownloadCapabilities(chart.id) to discover the formats available for an existing chart; custom renderers advertise only the formats they implement. The Canvas adapter provides PNG graphics and chart-data CSV.

Graphics capture the committed rendered chart, including its resolved theme, viewport, series visibility, labels, and annotations. SVG remains vector output. Font-family styles are captured, but font files are not embedded in SVG, PNG, or the default raster PDF. A web font loaded only into the page may be unavailable when the browser rasterizes the exported SVG, causing a fallback font. Use a system font or an application-supplied imageEncoder that embeds the needed fonts when exact raster typography is required. See the browser’s SVG image restrictions. The default PDF contains a raster image; an optional local vector encoder is shown below. pdfEncoding reports raster, vector, or custom when known. Programmatic downloads default to PNG:

1
await charts.downloadChart(chart.id, {
2
  fileName: 'quarterly-sales',
3
  fileFormat: 'pdf',
4
  width: 1_600,
5
  height: 900,
6
});
7

8
const dataUrl = await charts.getChartImageDataURL(chart.id, {
9
  width: 1_200,
10
  height: 675,
11
});

Chart-data CSV

Interactive example

Chart exports

Compare CSV from the current chart window with the full dataset, using raw or formatted values.

1
await charts.downloadChart(chart.id, {
2
  fileName: 'quarterly-sales',
3
  fileFormat: 'csv',
4
  dataScope: 'current',
5
});
6

7
// Include hidden series and categories outside the current viewport.
8
const csv = charts.getChartCSV(chart.id, {
9
  dataScope: 'all',
10
  valueFormat: 'raw',
11
});

current exports every canonical value in the current viewport for visible series. Sampling and View data virtualization do not reduce the CSV. all exports the complete committed chart frame, including hidden series and categories outside the viewport. Both scopes retain the chart’s query, drill frame, and selected measures; neither fetches original transactions or reloads the provider. The data table’s temporary sort does not reorder the export.

CSV uses numeric values and blank missing cells by default. Choose valueFormat: 'formatted' to use display values and localized number formatting. Hierarchy labels and series labels form the headers; they are presentation text, not a lossless identity interchange format. CSV preserves Unicode and quotes commas, newlines, and double quotes. escapeFormulas: true prefixes spreadsheet formula-like strings with an apostrophe while preserving numeric negative values. This option defaults to false. Comma and CRLF are the default delimiters; columnDelimiter, rowDelimiter, and bom can override the output. The BOM is omitted by default. Width and height are graphics options and are rejected for CSV.

Optional vector PDF

Install and import jspdf and svg2pdf.js in your application, then inject a local encoder. Pivot does not fetch these libraries or fonts automatically.

1
import { jsPDF } from 'jspdf';
2
import 'svg2pdf.js';
3
import {
4
  createPivotChartsRenderer,
5
  createPivotChartsVectorPdfEncoder,
6
} from '@revolist/pivot';
7

8
const pdfEncoder = createPivotChartsVectorPdfEncoder({
9
  createDocument: options => new jsPDF({
10
    ...options,
11
    format: [...options.format],
12
  }),
13
}, {
14
  fonts: [
15
    {
16
      fileName: 'Report-Regular.ttf',
17
      fontFamily: 'Report',
18
      fontStyle: 'normal',
19
      dataBase64: reportRegularTtfBase64,
20
    },
21
    {
22
      fileName: 'Report-Bold.ttf',
23
      fontFamily: 'Report',
24
      fontStyle: 'bold',
25
      dataBase64: reportBoldTtfBase64,
26
    },
27
  ],
28
});
29

30
const renderer = createPivotChartsRenderer({
31
  fontFamily: 'Report',
32
  pdfEncoder,
33
});

Supply the base64 contents of licensed TTF files whose glyphs cover your chart’s text, and register the font styles your labels use. The vector helper maps CSS weights and oblique styles to the registered normal, bold, italic, or bold-italic PDF style and matches family names without regard to case. Registered family names may contain spaces and commas; quotes, backslashes, and control characters are rejected because the converter cannot reliably parse them. SVG and PNG keep the original CSS styles. Standard PDF fonts do not provide general Unicode coverage. Language shaping, font coverage, and converter support determine the result; this is not a universal Unicode or PDF/UA guarantee.

The helper creates a fresh document per export and converts the captured SVG to vector PDF locally. It preserves the SVG’s drawing, including supported patterns and clipping, and converts CSS pixels to PDF points. Conversion errors propagate without falling back to a raster image or a remote server. An arbitrary custom pdfEncoder reports custom; the first-party vector helper reports vector.

Graphics dimensions must be positive and finite. Output is limited to 16,384 pixels per dimension and 64 × 1,024 × 1,024 pixels in total; omitted dimensions use the rendered chart size.

Download lifecycle

Listen to pivot-chart-before-download and call preventDefault() to cancel a download before encoding. The detail contains the chart ID, format, operation ID, and owned model/options snapshots. Changing those snapshots does not update the chart or alter the download. pivot-chart-downloaded reports completion of the download action; it cannot confirm that the user saved the file. pivot-chart-download-error reports failures and aborted operations.

Pass an AbortSignal in download options to cancel an operation. Graphics are captured before asynchronous encoding, and the renderer checks cancellation and disposal again before starting a download. Updating the chart while encoding does not change the captured graphics. Injected encoders may finish their own work after cancellation, but the renderer will not start a later download. A canceled before-download event produces no completion event. Invalid options are rejected before a download operation is created, so they do not emit download lifecycle events.

The first-party renderer also accepts imageEncoder and pdfEncoder callbacks for applications that need a different rasterization or PDF pipeline. These callbacks receive an owned SVG snapshot. They must return the encoded data URL and propagate failures; the plugin does not send chart data to an export server.

Previous: Drill-down and interactions · Next: Headless API and persistence · API reference

Localize and configure the chart UI

pivotCharts.localeText supplies shared chart and renderer text. pivotChartsUi.localeText supplies UI overrides, merged deeply over that text. Both properties are reactive: replacing either configuration updates existing chart dialogs and embedded chart panels. Partial overrides retain all other labels, descriptions, option labels, accessible names, and formatter functions.

1
grid.pivotCharts = {
2
  renderer,
3
  localeText: {
4
    controls: { totals: 'Totales' },
5
    dataTable: { categoryHeader: 'Categoría', emptyValue: 'Sin valor' },
6
    renderer: { formatNumber: value => numberFormatter.format(value) },
7
  },
8
};
9
grid.pivotChartsUi = {
10
  localeText: {
11
    context: {
12
      heading: 'Detalles de los datos',
13
      close: 'Cerrar detalles',
14
      rows: 'Filas',
15
      columns: 'Columnas',
16
      frame: (categories, series) => `${categories} categorías · ${series} métricas`,
17
      formatFilterValue: value => String(value),
18
    },
19
    actions: { chartLabel: 'Gráfico', dataLabel: 'Tabla', viewData: 'Ver datos', viewChart: 'Ver gráfico' },
20
    chartOptions: { labels: { strokeWidth: 'Grosor de línea' } },
21
    gallery: { tabs: { chart: 'Gráfico', data: 'Datos', customize: 'Estilo' } },
22
  },
23
  controls: {
24
    'context.note': 'hidden',
25
    'controls.keepLinked': 'hidden',
26
    'controls.totals': 'disabled',
27
    'tabs.chart': 'hidden',
28
    'chartTypes.pie': 'hidden',
29
    'chartOptions.showGridLines': 'hidden',
30
    'chartOptions.strokeWidth': 'disabled',
31
    annotations: 'hidden',
32
    'export.pdf': 'disabled',
33
  },
34
  dataGrid: {
35
    sorting: true,
36
    range: true,
37
    resize: true,
38
    columnGrouping: true,
39
    rowSize: 36,
40
    categoryColumn: { name: 'Categoría', size: 220 },
41
    seriesColumn: series => ({ name: series.measure?.label ?? series.label, size: 180 }),
42
    filter: false,
43
  },
44
};

controls accepts enabled, disabled, or hidden. Unspecified controls are enabled when their data and renderer capabilities permit them. Hidden controls are not rendered; disabled controls remain visible and cannot be activated. A parent restriction wins over an enabled child. For example, disabling navigation also disables navigation.enabled, even if the child is explicitly enabled. A UI policy never enables an unsupported renderer capability or removes a loading/read-only restriction.

The close policy also gates Escape, and drill.navigate gates Alt+Left and Home in the chart area. Re-enabling these controls restores their shortcuts.

For the transient data-details popup, context.close controls its close button; Escape and clicking outside still dismiss the popup. Restrict context or context.heading to disable access. Restricting the details or export trigger also closes its already-open popup or menu. Disabled tabs stay visible; if no tab is enabled, no settings panel is active. Hiding every tab removes the sidebar.

Visible numeric option values can be localized independently of the numeric API:

1
grid.pivotChartsUi = {
2
  localeText: {
3
    chartOptions: {
4
      formatValue: (value, key, step) => new Intl.NumberFormat('de-DE', {
5
        maximumFractionDigits: step < 1 ? 2 : 0,
6
      }).format(value),
7
    },
8
  },
9
};

formatValue(value, key, step) affects range-value captions. Option updates still use numbers. Omit it to retain the default step-based decimal formatting.

The policy changes available UI actions. It does not rewrite the chart model, disable model-defined rendering behavior, or restrict programmatic API calls. Use ref.update(...) to configure chart behavior, and the UI policy to control which settings users may change. Disable reset actions too when their broader scope is inappropriate for your application.

Interactive example

Chart controls

Change the visible category or time window, then reset the chart navigation.

For a chart type whose catalog definition advertises navigation, configure its rendered toolbar and plot gestures through the chart model:

1
ref.update({
2
  navigation: {
3
    enabled: true,
4
    navigator: true,
5
    crosshair: true,
6
    tooltipMode: 'shared',
7
    actions: {
8
      zoomIn: 'enabled',
9
      zoomOut: 'disabled',
10
      reset: 'hidden',
11
    },
12
    gestures: { wheel: false, pan: true, pinch: false },
13
  },
14
});

Each action accepts enabled, disabled, or hidden; omitted actions default to enabled. Disabled actions cannot activate through pointer or keyboard input. Plot gestures require enabled: true, and each omitted gesture defaults to allowed. Navigator handles and its range band remain independent of that flag. Action policies alone do not create a toolbar; toolbar availability still follows the enabled, navigator, and viewport configuration.

A supplied navigation record replaces the previous record, including its nested action and gesture policies. Omitting it from an update preserves the current configuration; supplying {} restores defaults. These policies survive model serialization and restoration. Unsupported chart types reject a nonempty navigation record with a localizable error.

Use localeText.navigation to rename toolbar actions, navigator accessible names, instructions, and range summaries. Visible button text is independent of its accessible action name:

1
const localeText = {
2
  navigation: {
3
    zoomInButtonText: 'Zoom in',
4
    zoomOutButtonText: 'Zoom out',
5
    panLeftButtonText: 'Earlier',
6
    panRightButtonText: 'Later',
7
    resetViewportButtonText: 'Reset',
8
    formatNavigatorValue: (value, scale, handle, defaultText) =>
9
      `${handle}: ${defaultText}`,
10
  },
11
};

Translated text is measured and shortened with an ellipsis when space is limited. If no text prefix fits, the button shows its distinct default action glyph instead. The full text remains in the button title, and accessible action names remain independently configurable. Default glyph buttons retain their compact geometry. formatNavigatorValue customizes slider aria-valuetext; value matches numeric aria-valuenow (epoch milliseconds for time, a boundary ordinal for categories). The category end boundary is exclusive, while its defaultText names the last included category. Numeric slider bounds and behavior remain unchanged. localeText.renderer.invalidNavigation and navigationUnsupported(chartType) customize validation messages. These renderer/model policies also work through the standalone charts API, without a RevoGrid host.

ID or prefix	Controlled UI
`settings`	Entire settings sidebar; hiding it gives the chart the full width
`tabs.chart`, `tabs.data`, `tabs.customize`	Individual settings tabs; selection and arrow navigation skip unavailable tabs
`inspector`, `inspector.<section>`	All collapsible inspector sections, or one section listed above; restrictions cascade to its controls
`gallery`, `chartTypes.<type>`	Gallery and individual chart types, including recommendations
`data`, `query`, `relationship.x/y/size`	Data settings, independent query editor, and relationship bindings
`query.rows/columns/filters`	Hierarchy and member-filter editors
`controls.<key>`	Individual presentation/data controls: title, subtitle, description, legend, dataLabels, xAxisTitle, yAxisTitle, totals, drillSyncMode, keepLinked, valueSeries, theme
`presentation`, `customize`	Presentation controls or all customization settings
`chartOptions.<key>`	Each catalog option, including its reset action
`chartOptions.resetAll`	Reset all chart options
`axes.y.<field>`, `axes.ySecondary.<field>`	Primary/secondary axis scale, min, max, title, unit, notation and precision
`axes.seriesLayer`, `axes.seriesAxis`	Combination series layers and axis assignment
`navigation`, `interaction`, `annotations`, `colors`	Whole feature groups; individual controls use the same prefix
`actions.viewData`, `dataView`	Chart/data switch or the data view itself; hiding an active data view returns to the chart
`dataView.sorting/selection/resize/filtering`	Native data-grid interaction features
`context`, `context.heading`, `context.close`	Data details popup, trigger and close action
`context.overview/rows/columns/totals/filters/localFilters/note`	Individual information groups within the popup
`export`, `export.png/pdf/svg/csv`, `actions.exportChart`	Export menu, formats and trigger
`drill`, `drill.navigate`, `drill.retry`	Drill navigation controls
`actions.retry`, `actions.close`	Chart retry and close actions

Import PIVOT_CHART_UI_CONTROLS, PivotChartUiControlId, PivotChartUiControlState, PivotChartsUiConfig, and PivotChartDataGridConfig from @revolist/pivot or @revolist/pivot/charts for the concrete control inventory and public types. Each rendered control also exposes its stable ID in data-pivot-chart-control; IDs are independent of translated labels.

Native data-grid configuration

The current-frame RevoGrid is always read-only. Its source and formatting stay owned by the chart. dataGrid exposes sorting, selection (range), resizing, focus, clipboard, row/column sizes, theme, and category/series column names, sizes, bounds, sortability, and pinning. Global sorting restrictions win over a column’s sortable: true setting.

Column-axis members use native grouped headers: Q1 › Revenue becomes a Q1 group with a Revenue child column. Nested paths and multiple measures share their adjacent parent groups without changing series order. Standalone series without a column path retain their flat names. Values-on-rows layouts use the last column member as the leaf name. columnGrouping: false restores full flat series labels; groupLabel(label, series, level) overrides group names, and seriesColumn overrides leaf names. Groups use semantic member keys, so equal display names do not merge distinct members. Labels come from the dataset; display text is never split to infer a hierarchy.

Sorting and Pro filtering are enabled by default. Category columns offer text conditions and series columns offer numeric conditions against raw values, independent of formatted cell text. The native filter popup is supplied by AdvanceFilterPlugin. Pass RevoGrid’s ColumnFilterConfig through dataGrid.filter, including its localization captions and filter names. Setting filter: false, or disabling dataView.filtering, removes filtering. RevoGrid’s native filter-localization contract is retained rather than introducing a second set of filter strings. categoryColumn.filter and seriesColumn(...).filter can select Pro filter types (such as ['selection']) or disable individual column filters. Global filtering and sorting restrictions win over column overrides. Sorting/filtering affect only the current data grid; they do not change the chart dataset, Pivot report, or exports. They refresh against new frame values and reset when the series schema changes.

The data view uses localeText.dataTable for its accessible name, category header, missing values, and sort actions/announcements. Series names come from the dataset and may be overridden with seriesColumn. Numbers use the supplied formatted dataset values or localeText.renderer.formatNumber.

Formatters and standalone charts

Function overrides cover dynamic strings as well as fixed labels. In addition to number and data-table formatting, context.frame, context.more, and context.formatFilterValue customize data details. Annotation target/path text and the UTC input hint use annotations.targetLabel, annotations.pathLabel, and annotations.utcPlaceholder.

For a stacked-axis tick whose mathematical value exceeds JavaScript’s finite number range, renderer.formatScaledNumber(value, multiplier) formats the value without requiring their product to fit in a number. The default uses scientific notation, such as 2.697 × 10^308. Override this callback through pivotCharts.localeText to control the complete plotted label. Ordinary representable ticks continue to use renderer.formatNumber. Shared renderer formatters belong in pivotCharts.localeText; pivotChartsUi.localeText overrides inspector and data-view UI text without replacing the plot/export locale.

Radar’s category prerequisite message is customizable with renderer.minimumCategoriesRequired(chartTypeLabel, minimum). Both radar types require three non-total categories; empty frames retain the no-data view.

Use query.formatMemberValue for member-picker values and context.formatFieldLabel for row and column dimension headings and filter headings in data details. The latter receives the configured dimension label when available, otherwise the field name. Their defaults are String(value) and the unchanged resolved field label.

Generated inspector labels also expose formatter callbacks: query.formatMeasureLabel(prop, aggregator) controls the fallback caption when a measure has no configured label, colors.measureLabel(prop, aggregator) controls measure-color captions, colors.memberPathLabel(path) formats member paths, and annotations.coordinateLabel(label, path) formats category reference choices. Configured field and measure names remain application data; rename those in the Pivot configuration.

1
grid.pivotChartsUi = {
2
  localeText: {
3
    query: { formatMemberValue: value => `Member: ${String(value)}` },
4
    context: { formatFieldLabel: label => `Field: ${label}` },
5
  },
6
};

A zero-grid chart created with createStandalonePivotChart accepts the same localeText options for its renderer and export text. It does not render the settings sidebar or data-details popup, so UI policies belong to PivotChartsUiPlugin; standalone behavior is configured through the controller’s model/update API and renderer capabilities.

Numeric color-map keys expose localeText.colors.formatValueMapValue(value, role) for the complete displayed number. role is minimum, midpoint, or maximum. An explicit callback is used unchanged, including localized small or long values. When omitted, keys use renderer.formatNumber with the existing compact scientific fallback for small values or long labels. For example:

1
import type { PivotChartsLocaleTextOptions } from '@revolist/pivot';
2

3
const localeText: PivotChartsLocaleTextOptions = {
4
  colors: {
5
    formatValueMapValue: (value, role) => `${role}: ${new Intl.NumberFormat('de-DE').format(value)}`,
6
  },
7
};

The toolbar’s short captions use actions.chartLabel and actions.dataLabel; actions.viewChart and actions.viewData name their accessible actions. Configure the buttons independently with controls['actions.viewChart'] and controls['actions.viewData']. dataView controls the entire view switch. gallery.tabs.chart/data caption overrides remain fallbacks when the corresponding short caption is not supplied.

Every native dropdown choice supports <controlId>.options.<value>, for example:

1
grid.pivotChartsUi = {
2
  controls: {
3
    'controls.totals.options.all': 'hidden',
4
    'controls.totals.options.grand': 'disabled',
5
    'query.sortDirection.options.desc': 'disabled',
6
  },
7
};

These policies configure the editor, without rewriting the chart model. A hidden current choice retains its selected value and label but cannot be chosen from the menu. Parent restrictions and existing capability restrictions still apply. For dynamic choices, use the option’s native value, exposed alongside its full ID in data-pivot-chart-control.

Automatic category grouping and authored axis formatting are also translatable:

1
grid.pivotCharts = {
2
  renderer,
3
  localeText: {
4
    renderer: {
5
      otherCategoryLabel: 'Autres',
6
      groupedCategoryLabel: (label, index) => `${label} (groupe ${index})`,
7
      formatAxisTick: (value, format) => new Intl.NumberFormat('fr-FR', format).format(value),
8
      formatTimeAxisTick: (epochMilliseconds, dateOnly) =>
9
        new Intl.DateTimeFormat('fr-FR', dateOnly
10
          ? { dateStyle: 'medium', timeZone: 'UTC' }
11
          : { dateStyle: 'short', timeStyle: 'short', timeZone: 'UTC' }).format(epochMilliseconds),
12
    },
13
  },
14
};

Axis formatter callbacks also receive the built-in text as their last argument, so an application can selectively override formats. User-authored titles, field and series labels, units and notes remain application data; use their existing model, column-label and formatter APIs to translate them. Backend diagnostic text can be mapped through status.formatError and drill.formatError.

Shared axis and flow options

Pivot uses the shared axis contract, including signed scales, numeric ticks, grouped category labels, named X/Y assignments and measured gutters. Customize → Axes authors named X definitions and their navigation/brush targets. Declared named Y axes appear as editable value forms. Horizontal bars expose primary value/category forms plus horizontal secondary/named forms; gallery transitions clear incompatible positions and unsupported assignments atomically. Direct API transitions remain strict.

Sankey layout/sort/color/label/highlight fields come from the shared schema. Supply runtime sankey callbacks or categoryAxis.groups callbacks to createPivotChartsRenderer; reattach callbacks on restore. Heatmap row/column navigation uses the same canonical IDs and export scope as standalone Charts.

All grouped/stacked/normalized bars and columns also use the shared named-X authoring controls. Their category axes accept path levels, ID-based label mappings, grouped rows, reversal and independent viewport/brush targets. Additional bar category axes use left/right positions; columns use top/bottom. See bar/column category assignments.

Scatter, bubble and quadrant charts also accept axes.ySecondary, axes.yAxes[id] and seriesOverrides[boundYId].yAxis. The Pivot inspector limits assignment controls to bound Y measures. Scale/domain/reversal/ticks, error bars, value references, semantic notes and regression overlays follow that Y axis. Y navigation and synchronization remain primary-only; named/secondary hover shares X only. See all relationship axis options and limits.

Relationship groups also support axes.xAxes[id], seriesOverrides[boundYId].xAxis, viewport.xAxes[id], navigation.xAxis and rangeSelection.xAxis. The bound Y measure owns both assignments; bindings.x supplies numeric X values. Named X forms default to linear and omit category mapping controls. Named X scales, errors, annotations, brushes, navigator, synchronization and async full-domain metadata use that projection. See the full relationship X contract.

Candlestick and OHLC charts expose the shared primary price-axis form: axes.y supports linear/log/symlog/sqrt, bounds, reversal, vertical placement, title/unit/colors, numeric ticks and tick formatting. Price marks and annotations use the same clipped projection, and styled labels use measured gutters. See all financial price options and limits. Volume-price uses fixed price/volume controls described below; additional financial axis collections remain unsupported.

volumePrice shares category/time/numeric X navigation across aligned panes. axes.y configures prices and axes.ySecondary configures volume, including independent transforms, bounds, reversal, placement, units, formatting and ticks. Fixed roles preserve canonical data and reject swaps. Pivot exposes both forms. Notes/references/drawings use their pane’s scale; full-source/synchronized Y metadata remains price-only. See all volume-price options and limits.

Bound range columns/bars/areas, confidence bands and error intervals also support primary/secondary/named value axes and named X projections. The bound high measure owns each range group; low and actual fields follow it. Pivot exposes assignment controls on high measures. Scales, bounds, reversal, formatting, ticks, measured labels, clipping, annotations, navigator and brushes use the shared projections. See all range-axis options and limits.

Box plots, violins and statistical intervals also expose primary axes.y, secondary axes.ySecondary and named axes.yAxes numeric controls. Actual distributions own box/violin projections, and bound matrix observations own statistical intervals. Clipping, measured labels and annotations share those projections. Horizontal boxes retain physical value/category forms in Pivot. See all statistical-axis options and limits.

Statistical charts also support category windows, reversal/grouped labels, navigator/brush controls and primary-domain/category synchronization. Box/violin overviews and shared hover use displayed medians; canonical CSV cells remain unchanged. See statistical navigation options and boundaries.

Statistical primary X also supports time and all four numeric scales, including horizontal boxes. Raw key spacing, continuous brushes, annotations, navigator, source snapshots and remote detail/overview requests share that projection. See all statistical continuous-X options and physical-axis roles.

Histograms also expose primary aggregate-Y controls and optional numeric bin-boundary X scales. X comes from bound sample values; Y configures counts, sums or means. Bounds clip bins without rebucketing, and canonical CSV/observation identities remain intact. See all histogram-axis options and boundaries.

Histograms support local raw-sample X windows, zoom/pan, a bin-metric navigator, independent numeric brushes and compatible domain/window synchronization. Bins remain stable while the window clips their rectangles. See all histogram navigation options and boundaries. Histograms also support shared/crosshair/peer bin readouts and typed formatter metadata. Remote histogram loading uses complete-bin source summaries; typed metadata keeps global metrics separate from loaded raw rows.

Histogram Data views provide native Samples rows with numeric bin membership columns and a separate complete Bins inspection table. See all shared snapshot fields, scopes and localization.

Path sampling

Customize → Appearance → Path sampling controls the shared Charts chartOptions.sampling setting for line/area and combination charts. Choices are Automatic, None, M4, Minimum / maximum, and Largest triangle (LTTB); resetting appearance returns to automatic. The exported PivotChartSampling type names these values. Models retain the choice, including server rendering. Read path sampling for supported types, stack alignment, raw-data guarantees, marker handling, and budgets.

Step endpoints

Customize → Axes → [series] Step endpoints offers Automatic, Expanded bands, and Strict points for line/area layers. It writes seriesOverrides[id].strictStepCurve (false by default). Expansion applies to stepped categorical combination bands; native point and continuous X layouts retain exact geometry. The flag persists in models and SVG/SSR. Switching to a column/scatter/range layer or resetting appearance clears it. Read the step endpoint policy for gaps, reversal, sampled paths, and source identity.

Category placement

Customize → Axes → [axis] Category placement writes axes.x.categoryPlacement or axes.xAxes[id].categoryPlacement independently. Choose Automatic, Point positions, or Centered bands on supported line/area and combination categorical axes. Native defaults stay points; combinations default to bands. Scale/gallery transitions clear incompatible settings while preserving sibling axes and compatible category-ID ranges. The PivotChartCategoryPlacement type names 'point' | 'band'. Read category placement for step expansion, column margins, grouped labels, navigator behavior and saved models.

Transient point highlights

Chart appearance → Disable point highlights writes chartOptions.disableLineItemHighlight. Axes → [series] Point highlights writes seriesOverrides[id].disableHighlight using Automatic/Enabled/Disabled. Both booleans default to false and share the standalone Charts implementation. They suppress the transient glyph while retaining source inspection and regular markers. See transient highlights for saved endpoint substitution, tooltips, keyboard traversal and clean export snapshots.

Statistical value-axis collections

boxPlot, violin and rangeInterval share axes.y, axes.ySecondary, named axes.yAxes and seriesOverrides[id].yAxis in Charts and Pivot. Numeric scale, bounds, reversal, units, ticks and formatting apply independently to each assigned group. Named IDs must be declared; secondary can be implicit. Box/violin domains use genuine distribution samples/summaries; violin supports multiple selected distributions, series color and visibility, while keeping its single-series category palette by default. Statistical intervals accept two or more measures without a three-measure cap and aggregate only within each assigned value-axis group. A singleton group preserves source activation; aggregates remain read-only inspection targets.

Vertical extra axes use left/right/none; horizontal box extra axes use top/bottom/none. Horizontal boxes retain their primary physical aliases (axes.x for value appearance, numeric settings in axes.y). Pivot reconciles extra-axis positions on orientation/type changes. Invalid direct updates are atomic. References, shapes, semantic notes, model persistence and SVG export use the assigned projection. Primary runtime Y hints do not fix secondary/named scales: author their bounds as needed. Named statistical X collections are described below.

Named statistical X axes

Box plots, violins and statistical intervals accept named axes.xAxes and per-series seriesOverrides[id].xAxis, plus primary/named data and level X mappings. Each X frame has its own category/time/numeric scale and viewport.xAxes[id]; navigation.xAxis and rangeSelection.xAxis select interaction targets. Statistical intervals partition observations by the X/Y assignment pair, while each Y domain includes its full assigned source statistics across X frames. Named X decorations use top/bottom/none vertically, left/right/none for horizontal boxes. Pivot shares the controls and reconciles positions on orientation changes. References/shapes/notes, save/SSR, activation and canonical data use the assigned projections. See the axes guide for fields, defaults and limits.

Financial numeric X

Candlestick, OHLC and volume-price charts accept primary axes.x.scale: 'linear' | 'log' | 'symlog' | 'sqrt' plus data/level X mappings, numeric bounds, reversal, units, tick formatting/policy and physical styles/placement. Both volume-price panes share raw X coordinates and navigation; glyph widths follow the nearest distinct visible numeric gap. Source activation, annotations, model/SSR and canonical CSV retain their existing contracts. Pivot exposes primary mapping/numeric controls, with named X on all financial collections and named Y on candlestick/OHLC. See the axes guide for defaults, field limits and remaining collection/pane capabilities.

Candlestick/OHLC collections

Candlestick and OHLC accept parallel open/high/low/close binding arrays. Close fields uniquely own groups and their seriesOverrides[id].xAxis/yAxis assignments; open/high/low helpers can broadcast and inherit their owners. Use axes.xAxes, axes.ySecondary and axes.yAxes for independent scale/style/window controls. Groups keep canonical source indexes, stable slots and independent value domains; missing rows omit only the incomplete group. CSV windows include every owned OHLC field, and primary runtime Y hints exclude secondary/named price groups. Pivot preserves explicit grouped bindings and exposes axis selectors on close owners. See the axes guide for channel rules, limits, annotations and source contracts. Volume-price paired collections retain one shared price pane and one shared volume pane, as described below.

Paired volume-price collections

volumePrice supports parallel OHLC/volume binding arrays, distinct paired close/volume owners and named X axes. Each close owns X for its prices and volume; Y remains primary for prices and secondary for all volumes. Both panes share aligned group slots, windows and raw source identity. Missing volume preserves complete prices; incomplete OHLC observations omit both sides of that pair. chartOptions.volumePaneRatio accepts 0.1–0.8 of post-gap height; unset/reset retains automatic 24% sizing and its small-pane policy. Pivot exposes close-owner X selectors, fixed Y forms and the ratio control. See the axes guide for pairing, mappings, helper transitions, hover, annotations, exports, source/SSR and remaining additional-pane/Y limits.

Source keyboard inspection

Pivot uses the shared Charts source traversal for native line/area charts and combination line/area layers. Hidden or sampled-out glyphs remain keyboard reachable with raw source tooltips and activation; derived/synthetic values stay inspection-only. The temporary focus ring is independent of visual-highlight suppression and excluded from export snapshots. No Pivot-specific option is required. See keys, eligibility, order and focus restoration.

Pie slice geometry

Pie, donut and semi-donut expose saved outerRadius, paddingAngle, cornerRadius, arcLabelRadius and arcLabelMinAngle under Customize → Appearance. The shared renderer preserves adaptive ring placement when label radius is omitted; the editor preset is 0.7. Fields persist through models and exports. See units, defaults, ranges and limits.

Stack baselines

Customize → Appearance → Stack baseline selects diverging, none or expand. The per-series selector under Axes and scales overrides its actual stack partition. Automatic removes the override; conflicting member policies reject. See default behavior, signed values and normalization precedence.

Native line and area groups

Native paths expose a per-series stack group field under Axes and scales, plus group order and baseline policies. Multiple groups and independent raw paths use the same Charts engine; no composition adapter changes their public chart type. See defaults, normalized groups, baseline conflicts and sampling.

Compact sparklines

Enable Customize → Chart appearance → Sparkline on a native line/area or grouped-column chart. It uses the shared persisted chartOptions.sparkline mode, keeps raw source identity and keyboard/tooltip inspection, and hides chart furniture while fitting the host. Turn it off to restore authored headings, axes, legend and navigation. See sparklines for supported types, defaults and sizing/export rules.

Histogram collections

Explicit histogram sample bindings can use shared or independent axes and per-sample paint/visibility. In Data, Sample series switches between each distribution’s raw records and complete bins. Existing axis controls target the samples, while weighted helper measures stay out of the legend. See histogram collections for bindings, all options and complete remote-source contracts.

Pie highlighting and fading

Shared pieHighlight and pieFade appearance controls select item/ring scope and peer fading. Saved highlightedArc/fadedArc styles and highlightedPieItem controlled identity configure geometry and paint. See all fields, units, defaults, callbacks and snapshot behavior.

Radar metric axes

Radar line and area share independent numeric metric domains/scales, reversible projection, authored grid bands and value labels through axes.radar and radar appearance options. See radar axis contracts and Pivot editing.

Polar columns and radial bars share saved polar geometry controls in Customize → Appearance, including rotation, partial sweeps, direction, radius ratios and category/series gaps.

The six polar/radial-bar types share polar numeric value axes in Customize → Axes and scales, including scale/bounds, reversal, numeric ticks, units and independent value/category/grid visibility.

Customization and Export

Portable presentation

Chart presentation

Chart-specific options

Semantic colors and visibility

Reference lines, bands, and notes

Renderer styling

Chart styling and labels

Semantic label pipeline

Tooltip customization

Full localization

Chart graphics and data export

Chart-data CSV

Chart exports

Optional vector PDF

Download lifecycle

Localize and configure the chart UI

Native chart navigation policies

Chart controls

Native data-grid configuration

Formatters and standalone charts

Shared axis and flow options

Path sampling

Step endpoints

Category placement

Transient point highlights

Statistical value-axis collections

Named statistical X axes

Financial numeric X

Candlestick/OHLC collections

Paired volume-price collections

Source keyboard inspection

Pie slice geometry

Stack baselines

Native line and area groups

Compact sparklines

Histogram collections

Pie highlighting and fading

Radar metric axes