Blazor-ApexCharts 8.0.0

Blazor-ApexCharts

A blazor wrapper for ApexCharts.js

Demo

Installation

NuGet

For Blazor projects running in a web browser, WinForms, or WPF. Blazor-ApexCharts

dotnet add package Blazor-ApexCharts

For Blazor projects running on .NET MAUI. Blazor-ApexCharts-MAUI

dotnet add package Blazor-ApexCharts-MAUI

ChartService

ApexChartService is an optional service that will manage global options, set locales, manage charts on the screen. Add the chart service to the DI container by using the extension AddApexCharts(). This will add a scoped IApexChartService to the container.

services.AddApexCharts();

or add it with global options

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

These global options are the startup defaults. Each IApexChartService (one per DI scope, which on Blazor Server is one per user circuit) starts from its own deep copy of them, so a change made at runtime through ChartService.GlobalOptions, SetGlobalOptionsAsync or SetLocaleAsync only affects the current user. Every option object is copied, including your own subclasses of the option classes (or your own IApexChartBaseOptions implementation), even when they also implement IDisposable. Strings, delegates and objects of other types that you place in the options (for example items bound to a series) are not copied and stay shared.

To change the global options after startup, change ChartService.GlobalOptions and call ChartService.SetGlobalOptionsAsync(true), or pass new options to ChartService.SetGlobalOptionsAsync(options, true). Changing the object given to AddApexCharts (or the injected ApexChartsServiceOptions.GlobalOptions) after startup only reaches chart services created afterwards, never one that already exists. Earlier versions shared that object with every chart service, so code that relied on changing it at runtime to update every user now has to call SetGlobalOptionsAsync in each user's scope instead.

Registering ApexChartsServiceOptions and IApexChartService as scoped by hand, instead of calling AddApexCharts, still works but is no longer needed to keep users apart.

The same as above can be used for .NET MAUI, just make sure to use the method below to add the chart service.

services.AddApexChartsMaui();

Usage

Imports

Add a reference to Blazor-ApexCharts in your _Imports.razor

@using ApexCharts

.NET 8

If you are on .NET 8 you need to set the rendermode to Interactive.

Interactive Server, Interactive WebAssembly or Interactive Auto

Your first chart

    <ApexChart TItem="MyData"
               Title="Sample Data">

        <ApexPointSeries TItem="MyData"
                         Items="Data"
                         Name="Net Profit"
                         SeriesType="SeriesType.Bar"
                         XValue="e => e.Category"
                         YValue="e=> e.NetProfit" />

        <ApexPointSeries TItem="MyData"
                         Items="Data"
                         Name="Revenue"
                         SeriesType="SeriesType.Bar"
                         XValue="e => e.Category"
                         YValue="e=> e.Revenue" />
    </ApexChart>
    
@code {
    private List<MyData> Data { get; set; } = new();
    protected override void OnInitialized()
    {
        Data.Add(new MyData { Category = "Jan", NetProfit = 12, Revenue = 33 });
        Data.Add(new MyData { Category = "Feb", NetProfit = 43, Revenue = 42 });
        Data.Add(new MyData { Category = "Mar", NetProfit = 112, Revenue = 23 });
    }

    public class MyData
    {
        public string Category { get; set; }
        public int NetProfit { get; set; }
        public int Revenue { get; set; }
    }
}

Chart Options

Apex Chart options are available in the ApexChartOptions class that can be passed to the chart. More info in Apex documentation ApexCharts Docs.

The chart options cannot be shared. Each chart instance must have its own ApexChartOptions instance

Premium Features & Licensing

ApexCharts 6.0 introduced a set of premium interaction modules: history (undo/redo), perspectives (shareable view state), link (crossfilter / linked views), ink (draggable annotations), measure (delta ruler), contextMenu (point actions) and storyboard (scroll-driven views). All chart types and every other option remain free and are never gated.

The premium modules work fully in trial mode, but a chart that uses one shows an unobtrusive APEXCHARTS watermark until a valid license key is applied. The key format is shared across the ApexCharts family (apexgantt, apextree, apexsankey) and is validated offline (no network call).

Apply a key one of three ways:

1. Application-wide via the chart service (recommended; the key is applied once before any chart renders):

services.AddApexCharts(e =>
{
    e.LicenseKey = "APEX-your-license-key";
});

For .NET MAUI use AddApexChartsMaui(...) with the same option.

2. From configuration / environment:

services.AddApexCharts(e =>
{
    e.LicenseKey = builder.Configuration["APEXCHARTS_LICENSE_KEY"];
});

3. Per-chart via the chart options (works without the service, and never causes a first-render flash):

<ApexChart TItem="MyData" Options="@(new ApexChartOptions<MyData> { Chart = new Chart { License = "APEX-your-license-key" } })">
    ...
</ApexChart>

You can also apply or change a key at runtime through the service; a late valid key followed by a chart update clears an on-screen watermark without a full re-render:

await ChartService.SetLicenseAsync("APEX-your-license-key");

Without any key, AddApexCharts() still works; premium features simply render watermarked.

Ignite UI Theming

From Blazor-ApexCharts 8.0.0 (which bundles ApexCharts.js 8.8.1), charts can follow the Ignite UI theme on the page: the series palette, text, gridlines, the tooltip, the font, light or dark. It is an add-on, it is free, and it needs no license key. Turn it on in the chart service:

services.AddApexCharts(e =>
{
    e.IgniteUI = true;
});

The service then loads _content/Blazor-ApexCharts/js/features/ignite-ui.js once, before the first chart renders. For .NET MAUI use AddApexChartsMaui(...) with the same option. Use this option rather than a script tag: the add-on registers on the ApexCharts instance the component loads, which a tag in index.html would not see.

The Ignite UI tokens (--ig-*) are the lowest-ranked layer above the built-in defaults. Anything above them wins:

To turn it off for one chart, set Theme = new Theme { DesignSystem = false }; the --apx-* tokens still apply. Tokens = false stops every token read (--apx-* and --ig-*). Without the add-on the --ig-* tokens are ignored, with no error.

The chart reads its theme on every render. After a change that does not render, such as swapping the Ignite UI stylesheet for its dark variant, call RefreshTokensAsync() on the chart.

The theme names its font but does not load it (--ig-font-family is usually a web font, and the Ignite UI theme sheets carry no @font-face for it), so include the font's stylesheet on the page, in index.html or App.razor, as the Ignite UI setup already asks. The font applies only once that stylesheet has loaded it; the chart waits for it and re-measures, so the labels are measured with it.

Acknowledgments

Credits to @thirstyape for making production release possible.