Page History
(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)
Pivot Grid
Link to Figma: tba
Overview
- The Pivot Grid is an advanced data visualization component.
- It allows analyzing multi-dimensional data by grouping, filtering, and summarizing.
- It provides interactive capabilities for exploring and pivoting data across dimensions.
- Users can view aggregated metrics in a customizable grid format.
...
- dataTestId - Sets the testing hook ID for automated testing. For example, setting it to "sales-pivot-grid" allows test scripts to reliably locate this specific pivot grid component.
Guidelines
[NO DATA AVAILABLE]
Accessibility
...
Pivot Grid — Guidelines
Usage
- Use the component to analyze multi-dimensional data with configurable fields and aggregations defined in elements; enable the field panel when users must pivot dimensions themselves using showFieldPanel, showDataFields, showRowFields, showColumnFields, showFilterFields, and allowFieldDragging.
- Hide the field panel when users only need to read results to keep attention on the matrix using showFieldPanel set to false.
- Enable allowFiltering when users need to narrow visible data without changing the underlying dataSourceId or getEntityCollectionHttpRequestParametersMap.
- Enable allowSorting when comparative or ranked views are required so users can sort by row or column headers.
- Surface summary context by turning on showColumnGrandTotals and showRowGrandTotals when high-level rollups are essential.
- Provide intermediate summaries by enabling showRowTotals and showColumnTotals for grouped analyses; disable them when they add clutter.
- Use useMockData for demos or prototyping when a live dataSourceId is not yet available.
Sizing & Layout
- Provide concise context via titleTranslations and subtitleTranslations; keep text short to avoid header truncation the component cannot manage automatically.
- Improve legibility in dense matrices by turning on showBorders to delineate cells.
Data-Driven / Conditional Behavior
- Define analytic structure in elements by assigning fields to row, column, data, and filter roles with appropriate aggregations so the grid renders meaningful pivots.
- Keep grand totals and subtotals consistent with field roles by pairing showRowTotals with row groups and showColumnTotals with column groups.
Content & Localization
- Localize the grid title and subtitle using titleTranslations and subtitleTranslations to match user locale.
- Use displayName for authoring clarity in the structure panel without affecting end-user strings.
- Keep localized titles succinct and specific; avoid placing critical instructions here because titles and subtitles are static text, not interactive hints.
Dos & Don’ts
| Do | Don’t | Article setting(s) |
|---|---|---|
| Show the field panel only when users need to re-pivot data. | Leave the field panel visible when users only need to read results. | showFieldPanel, showDataFields, showRowFields, showColumnFields, showFilterFields, allowFieldDragging |
| Enable sorting for ranked comparisons. | Rely on backend order for user-driven ranking tasks. | allowSorting |
| Offer filtering controls for narrowing results. | Force dataset changes only via server requests when client filtering suffices. | allowFiltering |
| Turn on grand totals when overall rollups matter. | Show grand totals by default in already compact summaries. | showColumnGrandTotals, showRowGrandTotals |
| Use subtotals to clarify group structure. | Enable all totals everywhere, creating visual noise. | showRowTotals, showColumnTotals |
| Localize all titles and subtitles. | Hard-code English strings. | titleTranslations, subtitleTranslations |
| Prototype with mock data before the API is ready. | Point to an empty dataSourceId and ship a blank grid. | useMockData, dataSourceId |
| Provide a stable test hook for automation. | Target the grid by visual text in tests. | dataTestId |
Accessibility
- Localize visible titles via titleTranslations and subtitleTranslations so assistive technologies announce appropriate context.
- Keep titles concise and specific using titleTranslations and subtitleTranslations.
- Improve structural clarity for low-vision users by enabling showBorders when cell separation is ambiguous.
- Provide stable analysis structure by setting elements and totals flags during events.ON_INIT to avoid disruptive reflow.
- Expose a deterministic handle for automated a11y checks with dataTestId.
- Avoid color-only distinctions; convey grouping and summaries with showRowTotals, showColumnTotals, showRowGrandTotals, and showColumnGrandTotals.
- Hide the field panel via showFieldPanel when not needed to reduce cognitive load in reading-first scenarios.
