Blazor PivotGrid Overview

The Blazor PivotGrid component, also known as a pivot table, is a powerful data visualization, statistics and reporting tool that allows you to perform operations and analysis over multi-dimensional pivot data. It can work with local data or a remote XMLA data such as an OLAP cube. The PivotGrid also supports filtering and sorting for the values of the row and column fields.

Telerik UI for Blazor Ninja image

The PivotGrid component is part of Telerik UI for Blazor, a professional grade UI library with 110+ native components for building modern and feature-rich applications. To try it out sign up for a free 30-day trial.

Definitions

The PivotGrid component and this documentation use terms row, column, and measure. Each of these terms signifes one field in the data source:

  • The rows and columns represent categories or date periods.
  • The distinct values of a row field display in rows headers. The number of rendered rows will match the number of distinct values of the row field.
  • The distinct values of a column field display in column headers. The number of rendered columns will match the number of distinct values of the column field.
  • The measures usually represent numerical data. The aggregated (calculated) values of a measure display in the inner cells of the Pivot Grid. A measure is also known as dimension. On the other hand, a fact is a non-aggregated "raw" value on the data.

Components

The PivotGrid is an integrated product that includes several Razor components:

Component Description
<TelerikPivotGrid> The PivotGrid displays the aggregate measures.
<TelerikPivotGridConfigurator> The Configurator enables end users to add or remove rows, columns and measures.
<TelerikPivotGridConfiguratorButton> The Button toggles the visibility of the configurator.
<TelerikPivotGridContainer> The Container wraps the above components.
  • The Container is required when using a Configurator.
  • The Container supports any order of the PivotGrid, Button and Configurator.
  • The <TelerikPivotGridContainer> is a standard Blazor RenderFragment and allows any ChildContent. Nevertheless, do not place any other custom components or markup inside it.

Creating Blazor PivotGrid

  1. Add a <TelerikPivotGrid> tag to a Razor file.
  2. Set the DataProviderType parameter to a member of the PivotGridDataProviderType enum, according to your data provider. The example below uses Local flat data for simplicity. In this case, the PivotGrid also needs a Data parameter, which points to an IEnumerable<TItem>.
  3. (optional) To show initial data, add at least one row, column, and measure with a Name parameter that points to a field name in the data:
    • One <PivotGridColumn> instance inside the <PivotGridColumns> tag.
    • One <PivotGridRow> instance inside the <PivotGridRows> tag.
    • One <PivotGridMeasure> instance inside the <PivotGridMeasures> tag. Set a Name and Aggregate.
  4. (optional) To give users more flexibility, add a Configurator and a toggle Button next to the <TelerikPivotGrid> tag:
    • Add a <TelerikPivotGridConfigurator>.
    • Add a <TelerikPivotGridConfiguratorButton>.
    • Wrap both tags and <TelerikPivotGrid> with a <TelerikPivotGridContainer>.

PivotGrid with configurator and local data

<TelerikPivotGridContainer>

    <TelerikPivotGridConfigurator />

    <TelerikPivotGridConfiguratorButton />

    <TelerikPivotGrid Data="@PivotData"
                      DataProviderType="@PivotGridDataProviderType.Local">
        <PivotGridColumns>
            <PivotGridColumn Name="@nameof(PivotModel.City)" Title="City" />
        </PivotGridColumns>
        <PivotGridRows>
            <PivotGridRow Name="@nameof(PivotModel.Category)" Title="Category" />
            <PivotGridRow Name="@nameof(PivotModel.Product)" />
        </PivotGridRows>
        <PivotGridMeasures>
            <PivotGridMeasure Name="@nameof(PivotModel.ContractValue)"
                              Title="Contract Value"
                              Aggregate="@PivotGridAggregateType.Sum" />
        </PivotGridMeasures>
    </TelerikPivotGrid>

</TelerikPivotGridContainer>

@code {
    private List<PivotModel> PivotData { get; set; } = new List<PivotModel>();

    protected override void OnInitialized()
    {
        var dataItemCount = 100;
        var categoryCount = 3;
        var productCount = 5 + 1; // effectively 5, as rnd.Next() will never return 6
        var cityCount = 3 + 1; // effectively 3
        var rnd = new Random();

        for (int i = 1; i <= dataItemCount; i++)
        {
            var productNumber = rnd.Next(1, productCount);

            PivotData.Add(new PivotModel()
            {
                Category = $"Category {productNumber % categoryCount + 1}",
                Product = $"Product {productNumber}",
                City = $"City {rnd.Next(1, cityCount)}",
                ContractDate = DateTime.Now.AddDays(-rnd.Next(1, 31)).AddMonths(-rnd.Next(1, 12)).AddYears(-rnd.Next(0, 5)),
                ContractValue = rnd.Next(123, 987)
            });
        }

        base.OnInitialized();
    }

    public class PivotModel
    {
        public string Category { get; set; } = null!;
        public string Product { get; set; } = null!;
        public string City { get; set; } = null!;
        public DateTime ContractDate { get; set; }
        public decimal ContractValue { get; set; }
    }
}

Data Binding

The PivotGrid component supports different data binding options and data providers, for example local flat data and XML for Analytics (XMLA) with an OLAP cube. It can load data on demand or perform all aggregate calculations in memory.

Configurator

In the simpler case, the PivotGrid supports fixed configuraton of its rows, columns, and measures. However, most scenarios and users may require greater flexibility where one can use the PivotGrid Configurator to change, filter and sort the displayed fields and aggregations.

Templates

The PivotGrid supports templates for its header and data cells. The templates enable you to customize the cell content and appearance.

PivotGrid Parameters

The tables below list the parameters of all components, which comprise the PivotGrid:

Grid Parameters

The following table lists the TelerikPivotGrid parameters. Also check the PivotGrid API Reference.

Parameter Type and Default Value Description
Class string A custom CSS class for the <div class="k-pivotgrid"> element. Use it to override theme styles.
ColumnHeadersWidth string The width of each column in any supported CSS unit.
Data IEnumerable<TItem> The Pivot Grid component data. Use only with Local DataProviderType.
DataProviderType PivotGridDataProviderType enum
(Local)
The type of data source that the Pivot Grid will use.
EnableLoaderContainer bool (true) Defines if a built-in LoaderContainer will show during long-running operations (over 600ms).
Height string A height style in any supported CSS unit.
LoadOnDemand bool
(true)
Defines if the PivotGrid will request only the data to display in the current view, or all data. When loading on demand is disabled or when using the Local DataProviderType, the component performs all calculations in-memory. In such cases, large amounts of data may impact the performance, especially in WebAssembly apps.
RowHeadersWidth string The width of all row headers in any supported CSS unit.
TItem object The PivotGrid @typeparam. Required if the data item type cannot be inferred at compile-time.
Width string A width style in any supported CSS unit.

Row, Column and Measure Parameters

The following table lists parameters of the PivotGridRow, PivotGridColumn and PivotGridMeasure tags.

Parameter Type and Default Value Description
Aggregate PivotGridAggregateType enum
(Sum)
The nature of the calculated aggregate values. Applies to PivotGridMeasure only.
Format string The display format of the calculated aggregate values, for example "{0:C2}". Applies to PivotGridMeasure only.
HeaderClass string Adds a custom CSS class to the respective row header, column header or measure. Use it to apply custom styles or override the default PivotGrid styles.
Name string The field name of the respective row, column or measure.
Title string The label to be displayed in the Configurator for the respective row, column or measure.

Configurator Parameters

The following table lists parameters of the TelerikPivotGridConfigurator component.

Parameter Type Description
Class string A custom CSS class for the <div class="k-pivotgrid-configurator"> element. Use it to override theme styles.
EnableLoaderContainer bool (true) Defines if a built-in LoaderContainer will show during long-running operations (over 600ms).

Button Parameters

The following table lists parameters of the TelerikPivotGridConfiguratorButton component.

Parameter Type Description
Class string A custom CSS class for the <div class="k-pivotgrid-configurator-button"> element. Use it to override theme styles.

Container Parameters

The following table lists parameters of the TelerikPivotGridContainer component.

Parameter Type Description
Class string A custom CSS class for the Container <div> element. Use it for custom styling.

PivotGrid Reference and Methods

The Pivot Grid exposes methods for programmatic operation. To use them, define a reference to the component instance with the @ref directive. The PivotGrid methods are:

Method Description
Rebind Processes the component Data and refreshes the UI. See the Refresh Data section in the common Data Binding article for details.

Obtain reference to the PivotGrid instance and execute methods

<TelerikPivotGrid @ref="@PivotGridRef" />

<TelerikButton OnClick="@OnButtonClick">Rebind PivotGrid</TelerikButton>

@code {
    private TelerikPivotGrid<PivotModel> PivotGridRef { get; set; } = null!;

    private void OnButtonClick()
    {
        PivotGridRef.Rebind();
    }

    public class PivotModel
    {

    }
}

Next Steps

See Also

In this article