Blazor Chart Component

Add a Chart to a Blazor App

Four steps, and only the third involves any chart-specific thinking. Start with the package:

dotnet add package Blazor-ApexCharts

For .NET MAUI, install the companion package instead:

dotnet add package Blazor-ApexCharts-MAUI

Add the namespace to _Imports.razor. Note that the namespace is ApexCharts even though the package is Blazor-ApexCharts:

@using ApexCharts

Registering IApexChartService is optional for a single chart, and worth having as soon as you want shared theming, locales, or a handle on the chart instances on screen:

services.AddApexCharts(e =>
{
    e.GlobalOptions = new ApexChartBaseOptions
    {
        Debug = true,
        Theme = new Theme { Palette = PaletteType.Palette6 }
    };
});

On MAUI the equivalent is services.AddApexChartsMaui().

Why Does My Blazor Chart Render Blank?

Because the component is rendering statically and the JavaScript interop never runs.

From .NET 8, Blazor Web Apps render statically by default, and a component that needs JS interop has to opt into interactivity. Set the render mode on the page or the component:

@rendermode InteractiveServer

InteractiveWebAssembly and InteractiveAuto work equally well. There is no error and nothing in the browser console, which is why this costs people an afternoon. If a chart renders as empty space, check this first.

Configure Chart Options in C#

Through ApexChartOptions<T>, which mirrors the JavaScript options object as typed C# properties and enums.

<ApexChart TItem="Sale" Title="Revenue" Options="options">
    <ApexPointSeries TItem="Sale" Items="sales" Name="Revenue"
                     SeriesType="SeriesType.Line"
                     XValue="e => e.Month"
                     YValue="e => e.Revenue" />
</ApexChart>

@code {
    private ApexChartOptions<Sale> options = new()
    {
        Theme = new Theme { Mode = Mode.Dark },
        Stroke = new Stroke { Curve = Curve.Smooth, Width = 3 }
    };
}

Curve.Smooth and Mode.Dark are enums, and the option properties are typed, so a misspelled option name or an invalid value is a build error. That is the substantive difference from configuring the same chart in JavaScript, where an unrecognised option key is silently ignored at runtime.

Options that accept either one value or a list are modelled as a ValueOrList<T> with implicit conversions both ways, so you write the singular form and it still compiles. Stroke.Curve is typed CurveSelections, which is why Curve = Curve.Smooth and a list of curves are both valid.

Each chart instance needs its own ApexChartOptions instance. Options objects cannot be shared between charts.

Choosing a Chart Type

Change the SeriesType enum on the series. It covers twelve types: Area, Bar, Donut, Heatmap, Line, Pie, PolarArea, Radar, RadialBar, Scatter, Treemap and RangeArea.

Pie, donut, polar area and radial bar are single dimensional, so they normally pair SeriesType with YAggregate instead of YValue, collapsing many rows into one value per category:

<ApexChart TItem="Order" Title="Gross value by country">
    <ApexPointSeries TItem="Order"
                     Items="orders"
                     Name="Gross Value"
                     SeriesType="SeriesType.Donut"
                     XValue="@(e => e.Country)"
                     YAggregate="@(e => e.Sum(e => e.GrossValue))"
                     OrderByDescending="e => e.Y"
                     ShowDataLabels />
</ApexChart>

Chart types that need a different data shape have their own series components rather than a SeriesType value: <ApexBubbleSeries>, <ApexCandleSeries>, <ApexBoxPlotSeries>, <ApexRangeSeries>, <ApexRangeAreaSeries> and <ApexViolinSeries>. There is also a standalone <ApexGauge> component.

Update a Chart with New Data

Hold a reference with @ref and call UpdateSeriesAsync() after mutating the underlying collection. This is the part that surprises people coming from React or Vue: mutating the list does not re-render the chart on its own.

<button @onclick="Reload">Reload</button>

<ApexChart TItem="Sale" Title="Revenue" @ref="chart">
    <ApexPointSeries TItem="Sale" Items="sales" Name="Revenue"
                     SeriesType="SeriesType.Line"
                     XValue="e => e.Month"
                     YValue="e => e.Revenue" />
</ApexChart>

@code {
    private List<Sale> sales = new();
    private ApexChart<Sale> chart;

    private async Task Reload()
    {
        sales = await LoadSalesAsync();
        await chart.UpdateSeriesAsync(animate: true);
    }
}

UpdateSeriesAsync(bool animate = true) takes a single optional flag. UpdateOptionsAsync is the equivalent for changing options at runtime, and its signature is wider: UpdateOptionsAsync(bool redrawPaths, bool animate, bool updateSyncedCharts, ZoomOptions zoom = null). The first three are required, so there is no one-argument form.

One constraint worth knowing before you design your model: ApexChart<TItem> is declared where TItem : class, so the type you bind must be a reference type. A struct or record struct will not compile as TItem.

When to Use Something Else

• You need charts rendered on the server with no browser. This is a client-side engine driven through JS interop. A headless PNG report pipeline is not its job.
• Your team already lives in a JavaScript build. Use apexcharts directly. The value of this package is staying in C#, and if you are not staying in C# it is a layer you do not need.
• You need the interaction modules and cannot licence them. The charts are complete without a key, but undo and redo, crossfilter, measure and storyboard are not.