(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.

Specs

Tokens

Structure

• elements - Defines the fields and their configuration for the pivot grid. This array contains DynamicPivotGridFieldComponent objects with properties like dataField, caption, area, and aggregation functions. For example, configuring a "region" field for rows, a "date" field for columns, and an "amount" field for data with sum aggregation.

(Configured in General Properties)

• displayName - Sets the display name of the component shown in the structure panel. For example, "Sales Analysis Grid" allows for easy identification of the component's purpose within the UI builder interface.

(Configured in Datasource)

• dataSourceId - Specifies the data source ID for retrieving pivot grid data. For example, "api/sales/analysis" connects the pivot grid to the sales analysis API endpoint.
• getEntityCollectionHttpRequestParametersMap - Configures HTTP parameters for data fetching. This object maps additional parameters needed for the data request, such as {"year": "currentYear"} to filter data for a specific year.
• useMockData - Determines whether sample data is used for the pivot grid. When enabled, the component will use built-in sample data instead of fetching from an API, useful for prototyping or demonstration purposes.

Styling

(Configured in Visual Properties)

• titleTranslations - Sets the title text displayed above the pivot grid, with support for multiple languages. For example, {"en-US": "Sales by Region", "de-DE": "Verkauf nach Region"} provides localized titles for different user languages.
• subtitleTranslations - Sets a secondary text displayed below the title, with language support. For example, {"en-US": "Annual Analysis", "fr-FR": "Analyse Annuelle"} provides additional context about the data being displayed.
• showBorders - Determines whether borders are displayed around the pivot grid cells. When enabled, grid cells are visually separated with border lines, making the data structure more clearly defined.
• allowFiltering - Enables the ability to filter data within the pivot grid. When enabled, users can apply filters to narrow down the displayed data based on specific criteria, such as showing only data for specific regions.
• allowSorting - Enables sorting functionality within the pivot grid. When enabled, users can sort data in ascending or descending order by clicking on column or row headers.

Columns & Rows

(Configured in Visual Properties)

• showColumnGrandTotals - Controls the visibility of grand totals for columns. When enabled, displays summary totals at the end of each column group, providing aggregated values across all rows.
• showRowGrandTotals - Controls the visibility of grand totals for rows. When enabled, displays summary totals at the end of each row group, providing aggregated values across all columns.

• showRowTotals - Controls the visibility of subtotals for individual row groups. When enabled, displays totals for each group of row values, providing intermediate summaries within the data hierarchy.
• showColumnTotals - Controls the visibility of subtotals for individual column groups. When enabled, displays totals for each group of column values, providing intermediate summaries within the data structure.

Field Panel

(Configured in Visual Properties)

• showFieldPanel - Activates the field panel interface for the pivot grid. When enabled, displays a panel that allows users to interactively drag and drop fields between different areas of the pivot grid.
• showDataFields - Controls the visibility of data fields in the field panel. When enabled and showFieldPanel is true, displays the available data fields that can be used for calculations and aggregations.
• showRowFields - Controls the visibility of row fields in the field panel. When enabled and showFieldPanel is true, displays fields that can be assigned to row dimensions of the pivot grid.
• showColumnFields - Controls the visibility of column fields in the field panel. When enabled and showFieldPanel is true, displays fields that can be assigned to column dimensions of the pivot grid.
• showFilterFields - Controls the visibility of filter fields in the field panel. When enabled and showFieldPanel is true, displays fields that can be used to filter the entire pivot grid dataset.
• allowFieldDragging - Enables drag-and-drop field rearrangement in the field panel. When enabled and showFieldPanel is true, users can drag fields between different areas to reorganize the pivot grid structure.

Actions & Variants

(Configured in Events)

• events - Configures the events that the component can trigger and respond to:
• ON_INIT - Triggered when the pivot grid component is initialized. Can be used to perform setup operations or fetch additional context data.
• ON_DESTROY - Triggered when the pivot grid component is removed from the DOM. Useful for cleanup operations when navigating away from a page.

Tests

(Configured in Testing Hooks)

• 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

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

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.