DxPieChart<T> Class

A control that visualizes data as Pie and Donut charts.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v23.2.dll

NuGet Package: DevExpress.Blazor

Declaration

public class DxPieChart<T> :
    DxChartBase,
    IComponentContainer<IPieChartSeriesModel>

Type Parameters

Name	Description
T	The data item type.

Remarks

The DevExpress Pie Chart component (<DxPieChart>) allows you to create Pie and Donut chart types for Blazor applications.

Run Demo: Pie Charts

Add a Chart to a Project

Follow the steps below to add the Pie Chart component to an application:

1. Use a DevExpress Project Template to create a new Blazor Server or Blazor WebAssembly application. If you use a Microsoft project template or already have a Blazor project, configure your project to incorporate DevExpress Blazor components.
2. Add the <DxPieChart>…</DxPieChart> markup to a .razor file.
3. Bind the component to data.
4. Configure the component: add series, specify the chart’s size, define labels and tooltips, and so on (see the sections below).

Bind to Data

Use the Pie Chart’s Data property to specify an IEnumerable<T> data source. The chart should also contain at least one series to display data (see the section below for more information: Series). For a sample data source, refer to our GitHub repository.

Note

The chart component operates in bound mode only.

Razor

<DxPieChart Data="@SalesData">
    @* A place for series *@
</DxPieChart>

@code {
    IEnumerable<SaleInfo> SalesData;

    protected override async Task OnInitializedAsync() {
        SalesData = await Sales.GetSalesAsync();
    }
}

SaleInfo

using System;

public class SaleInfo {
    public int OrderId { get; set; }
    public string Region { get; set; }
    public string Country { get; set; }
    public string City { get; set; }
    public int Amount { get; set; }
    public DateTime Date { get; set; }
}

Sales

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

public class Sales {
    static IList<SaleInfo> dataSource;
    static Sales() {
        CreateDataSource();
    }

    public static Task<IQueryable<SaleInfo>> GetSalesAsync() {
        return Task.FromResult(dataSource.AsQueryable());
    }

    static void CreateDataSource() {
        dataSource = new List<SaleInfo> {
        new SaleInfo {
                OrderId = 10248,
                Region = "North America",
                Country = "United States",
                City = "New York",
                Amount = 1740,
                Date = DateTime.Parse("2017/01/06")
            },
            new SaleInfo {
                OrderId = 10249,
                Region = "North America",
                Country = "United States",
                City = "Los Angeles",
                Amount = 850,
                Date = DateTime.Parse("2017/01/13")
            },
            new SaleInfo {
                OrderId = 10250,
                Region = "North America",
                Country = "United States",
                City = "Denver",
                Amount = 2235,
                Date = DateTime.Parse("2017/01/07")
            },
            new SaleInfo {
                OrderId = 10251,
                Region = "North America",
                Country = "Canada",
                City = "Vancouver",
                Amount = 1965,
                Date = DateTime.Parse("2017/01/03")
            },
            new SaleInfo {
                OrderId = 10252,
                Region = "North America",
                Country = "Canada",
                City = "Edmonton",
                Amount = 880,
                Date = DateTime.Parse("2017/01/10")
            },
            new SaleInfo {
                OrderId = 10253,
                Region = "South America",
                Country = "Brazil",
                City = "Rio de Janeiro",
                Amount = 5260,
                Date = DateTime.Parse("2017/01/17")
            },
            new SaleInfo {
                OrderId = 10254,
                Region = "South America",
                Country = "Argentina",
                City = "Buenos Aires",
                Amount = 2790,
                Date = DateTime.Parse("2017/01/21")
            },
            new SaleInfo {
                OrderId = 10255,
                Region = "South America",
                Country = "Paraguay",
                City = "Asuncion",
                Amount = 3140,
                Date = DateTime.Parse("2017/01/01")
            },
            new SaleInfo {
                OrderId = 10256,
                Region = "Europe",
                Country = "United Kingdom",
                City = "London",
                Amount = 6175,
                Date = DateTime.Parse("2017/01/24")
            },
            new SaleInfo {
                OrderId = 10257,
                Region = "Europe",
                Country = "Germany",
                City = "Berlin",
                Amount = 4575,
                Date = DateTime.Parse("2017/01/11")
            },
            // ...
    };
    }
}

If the data source collection implements the INotifyCollectionChanged interface, the Chart is updated automatically each time the collection changes. Otherwise, use the RefreshData method to reload data and redraw the component. To re-render the Chart area without a data reload, call the RedrawAsync method.

To track the moment when the chart rendering is finished and the component is completely loaded, handle the Rendered event.

Series

Use the DxPieChartSeries<T, TArgument, TValue> object to create a PieChart-specific series. You should use the following series properties to bind the data source fields to the series:

• ArgumentField: specifies the data source field that contains arguments for chart points.
• ValueField: specifies the data source field that contain values for chart points.

The table below lists settings for a pie series:

Member	Description
SummaryMethod	Specifies the method that calculates summaries for points with the same argument value.
ArgumentField	Specifies a data source field that contains arguments for series values.
Filter	Specifies an expression used to filter series values.
Name	Specifies the name for a series.
ValueField	Specifies a data source field that contains values for series points.
Visible	Specifies the series visibility.

Place several series at the same chart hierarchy level to create a nested donut as shown in the example below:

<DxPieChart Data="@SalesData"
            T="SaleInfo">
    <DxPieChartSeries T="SaleInfo"
                      TArgument="string"
                      TValue="double"
                      ValueField="si => si.Amount"
                      ArgumentField="si => si.Region"
                      SummaryMethod="Enumerable.Sum"
                      Name="Region Sales">
    </DxPieChartSeries>
    <DxPieChartSeries T="SaleInfo"
                      TArgument="string"
                      TValue="double"
                      ValueField="si => si.Amount"
                      ArgumentField="si => si.City"
                      SummaryMethod="Enumerable.Sum"
                      Name="City Sales">
    </DxPieChartSeries>
    @* ... *@
</DxPieChart>

@code {
    @* ... *@
    protected override async Task OnInitializedAsync() {
        SalesData = (await Sales.GetSalesAsync()).Where(si => si.Region != "Africa" && si.Region != "Australia");
    }
}

Run Demo: Pie Charts - Nested Donut

Donut

Use the InnerDiameter property to change the chart’s shape to Donut. The InnerDiameter is a value from 0 to 1 that is the ratio of the inner diameter to the outer diameter (Diameter).

The following code creates a donut with an outer diameter of 0.7 * 300 = 210 pixels, and inner diameter of 210 * 0.5 = 105 pixels.

<DxPieChart Data="@SalesData"
            Diameter="0.7"
            InnerDiameter="0.5"
            Height="300"
            Width="950">
    <DxPieChartSeries T="SaleInfo"
                      TArgument="string"
                      TValue="double"
                      ValueField="si => si.Amount"
                      ArgumentField="si => si.Region"
                      SummaryMethod="Enumerable.Sum">
    </DxPieChartSeries>
    <DxChartLegend Visible="false" />
</DxPieChart>

Sizing

You can change the size of the Pie Chart component.

Use the Width and Height properties to specify a custom size for the chart component. The example below sets the chart component size to 75% of the parent component (<div>).

<div style="width: 932px; height: 440px">
    <DxPieChart Data="@SalesInfo" Width="75%" Height="75%"> @* Width = 699px; Height = 330px *@
        @* ... *@
    </DxPieChart>
</div>

You can also use the RedrawOnResize property to specify whether to redraw the chart when its container size changes.

Labels

Use the DxChartSeriesLabel component to show and configure labels for series data points. These settings apply to all labels in the series.

To override individual label settings, handle the chart’s CustomizeSeriesPoint event and use the event argument’s PointLabel property.

The following example demonstrates how to:

• Use the DxChartSeriesLabel component to specify the position of all labels.
• Use the DxChartSeriesLabelConnector component to customize connectors between data points and labels.
• Handle the CustomizeSeriesPoint event to show only labels whose values are greater than 20.

Razor

<DxPieChart Data="@DataList" CustomizeSeriesPoint="@PreparePointLabel">
    <DxPieChartSeries T="DailyData"
                      TArgument="DateTime"
                      TValue="int"
                      ArgumentField="@(s => s.Date)"
                      ValueField="@(s => s.Value)">
        <DxChartSeriesLabel Position="RelativePosition.Outside">
            <DxChartSeriesLabelConnector Visible="true" Width="2" />
        </DxChartSeriesLabel>
    </DxPieChartSeries>
    <DxChartLegend Visible="false" />
</DxPieChart>

@code {
  protected override void OnInitialized()
  {
        DataList = GetData();
  }
  protected void PreparePointLabel(ChartSeriesPointCustomizationSettings pointSettings)
  {
        int value = (int)pointSettings.Point.Value;
        if (value > 20)
            pointSettings.PointLabel.Visible = true;
  }
}

Data Source

public class DailyData
{
    public DateTime Date { get; set; }
    public int Value { get; set; }
}
private List<DailyData> DataList = new List<DailyData>();
public List<DailyData> GetData()
{
    DataList.Add(new DailyData() { Date = new DateTime(2020, 05, 12), Value = 22 });
    DataList.Add(new DailyData() { Date = new DateTime(2020, 05, 13), Value = 18 });
    DataList.Add(new DailyData() { Date = new DateTime(2020, 05, 14), Value = 19 });
    DataList.Add(new DailyData() { Date = new DateTime(2020, 05, 15), Value = 14 });
    DataList.Add(new DailyData() { Date = new DateTime(2020, 05, 16), Value = 15 });
    DataList.Add(new DailyData() { Date = new DateTime(2020, 05, 17), Value = 18 });
    DataList.Add(new DailyData() { Date = new DateTime(2020, 05, 18), Value = 24 });
    DataList.Add(new DailyData() { Date = new DateTime(2020, 05, 19), Value = 21 });
    DataList.Add(new DailyData() { Date = new DateTime(2020, 05, 20), Value = 20 });
    return DataList;
}

Run Demo: Charts - Series Label Customization

Use the LabelOverlap property to specify how the chart resolves overlapping labels.

The code below hides point labels that overlap:

<DxPieChart Data="@SalesData" LabelOverlap="PieChartLabelOverlap.Hide">
    @*...*@
</DxPieChart>

Legend

A Pie Chart’s legend lists all chart sectors. The DxChartLegend component implements the chart legend. Use the Visible property to hide or show the legend, and the Position property to specify the legend’s position.

Enable the AllowToggleSeries property to display checkboxes that toggle the visibility of individual sectors.

<DxPieChart Data="@SalesData">
    <DxPieChartSeries T="SaleInfo"
                      TArgument="string"
                      TValue="double"
                      ValueField="si => si.Amount"
                      ArgumentField="si => si.Region"
                      SummaryMethod="Enumerable.Sum">
    </DxPieChartSeries>
    <DxChartLegend AllowToggleSeries="true"
                   Position="RelativePosition.Outside" />
</DxPieChart>

Titles and Subtitles

The <DxPieChart> component can display titles (DxChartTitle) and subtitles (DxChartSubTitle) for the following items:

• The Pie Chart component (<DxPieChart>)
• Legend (<DxChartLegend>)

<DxPieChart Data="@SalesData" Width="950">
    <DxChartTitle Text="Sales Amount">
        <DxChartSubTitle Text="by regions" />
    </DxChartTitle>
    <DxPieChartSeries T="SaleInfo"
                      TArgument="string"
                      TValue="double"
                      ValueField="si => si.Amount"
                      ArgumentField="si => si.Region"
                      SummaryMethod="Enumerable.Sum">
    </DxPieChartSeries>
    <DxChartLegend HorizontalAlignment="HorizontalAlignment.Right"
                   Orientation="Orientation.Vertical">
        <DxChartTitle Text="Region">
            <DxChartSubTitle Text="(2017-2019)" />
        </DxChartTitle>
    </DxChartLegend>
</DxPieChart>

Tooltips

The Pie Chart can display tooltips when the mouse pointer is above a chart series. Use the DxChartTooltip element to specify tooltip templates.

The Tooltip class contains the following properties:

• Enabled - Specifies whether tooltips are enabled. Set this property to true to display tooltips.
• Position - Specifies the tooltip position.

<DxPieChart Data="@SalesData">
    <DxChartTooltip Enabled="true"
                    Position="RelativePosition.Outside">
        <div style="margin: 0.75rem">
            <div class="font-weight-bold">@context.Point.Argument</div>
            <div>Sales: @($"${context.Point.Value:#,0.00}")</div>
        </div>
    </DxChartTooltip>
    <DxPieChartSeries T="SaleInfo"
                      TArgument="string"
                      TValue="double"
                      ValueField="si => si.Amount"
                      ArgumentField="si => si.Region"
                      SummaryMethod="Enumerable.Sum">
        <DxChartSeriesLabel Visible="true"
                            Position="RelativePosition.Outside"
                            Format="ChartElementFormat.Thousands(1)">
            <DxChartSeriesLabelConnector Visible="true" />
        </DxChartSeriesLabel>
    </DxPieChartSeries>
    @* ... *@
</DxPieChart>

Run Demo: Charts - Tooltip Customization

Selection

Use the PointSelectionMode property to enable selection for pie chart sectors. You can choose between the following modes: None, Single, and Multiple.

Run Demo: Charts - Selection

Handle the DxPieChart.SelectionChanged event to track changes to selected sectors, and to respond to user selection.

Call the DxChartBase.ClearSelectionAsync method to deselect all selected sectors.

Palette

The DxPieChart component allows you to create a custom palette to colorize chart series. To apply a palette, assign it to the Palette property.

When the number of series points (for DxPieChart) exceeds the number of palette colors, you can use the PaletteExtensionMode property to extend the palette.

The following example uses drop-down menus to change the color palette and its extension mode:

<div class="flex-container">
    <DxPieChart Data="@GetData()"
                Width="400"
                InnerDiameter="0.5"
                Palette="@CurrentColors"
                PaletteExtensionMode="@CurrentPaletteMode">
        <DxChartLegend Visible="false" />
        <DxPieChartSeries ArgumentField="@((DataPoint s) => s.Argument)"
                          ValueField="@((DataPoint s) => s.Value)" />
    </DxPieChart>
    <div class="palette-container">
        @foreach (var color in CurrentColors) {
            <div class="palette-item" style="background-color: @color"></div>
        }
    </div>
</div>

@code {
    public enum Palettes {
        Material,
        Bootstrap,
        Tailwind
    }
    Dictionary<Palettes, string[]> Colors = new Dictionary<Palettes, string[]>() {
        { Palettes.Material, new string[] { "#1db2f5", "#f5564a", "#97c95c", "#ffc720", "#eb3573", "#a63db8" } },
        { Palettes.Bootstrap, new string[] { "#0d6efd", "#6c757d", "#28a745", "#dc3545", "#ffc107", "#17a2b8" } },
        { Palettes.Tailwind, new string[] { "#ef4444", "#eab308", "#22c55e", "#0ea5e9", "#8b5cf6", "#ec4899" } }
    };
    string[] CurrentColors;
    Palettes currentPalette = Palettes.Material;
    Palettes CurrentPalette {
        get => currentPalette;
        set {
            CurrentColors = Colors[value];
            currentPalette = value;
        }
    }
    ChartPaletteExtensionMode CurrentPaletteMode = ChartPaletteExtensionMode.Alternate;
    List<DataPoint> GetData() {
        List<DataPoint> result = new List<DataPoint>();
        for(var i = 0; i < 20; i++) {
            result.Add(new DataPoint($"Item{i}", 1));
        }
        return result;
    }
    public class DataPoint {
        public string Argument { get; set; }
        public int Value { get; set; }
        public DataPoint(string argument, int value) {
            Argument = argument;
            Value = value;
        }
    }
    protected override void OnInitialized() {
        CurrentColors = Colors[currentPalette];
    }
}

Run Demo: Chart - Palette

Troubleshooting

If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.

Implements

IHandleEvent

IHandleAfterRender

IAsyncDisposable

IComponent

Inheritance

Object

ComponentBase

DevExpress.Blazor.Base.DxAsyncDisposableComponent

DevExpress.Blazor.Base.DxDecoratedComponent

DxComponentBase

DxComponentBase<DevExpress.Blazor.Internal.JSInterop.ChartsJSInteropProxyBase>

DxControlComponent<DevExpress.Blazor.Internal.JSInterop.ChartsJSInteropProxyBase>

DxControlComponent<DevExpress.Blazor.Internal.JSInterop.ChartsJSInteropProxyBase, DevExpress.Blazor.Internal.IChartModel>

DxChartBase

DxPieChart<T>