Blazor-ApexCharts: putting ApexCharts.js inside a Razor component

A wrapper whose job is interop, not charting

ApexCharts.js is a JavaScript charting library. Blazor-ApexCharts is the .NET face of it: a set of Razor components and a service that let a Blazor application declare a chart, bind it to a strongly typed data item, and let the wrapper talk to the JavaScript library on the page. The repository describes itself plainly as a blazor wrapper for ApexCharts.js, and the demo site is published at apexcharts.github.io/Blazor-ApexCharts.

The audience is narrow and well defined. It is a Blazor team that has decided on ApexCharts.js as the chart engine and does not want to hand-roll the JavaScript interop, the option object serialisation, and the update callbacks for every chart in the product. The wrapper also covers the parts of Blazor that people forget: the render mode. On .NET 8 the documentation says you need to set the render mode to Interactive, and it names the three options as Interactive Server, Interactive WebAssembly, or Interactive Auto. Charts are a browser-side rendering problem, and that requirement is the wrapper telling you so rather than letting you discover it as an empty div.

The repository layout matches a real component library rather than a single file. There is a solution file, a src directory, a tests directory, a docs directory, a RELEASE_NOTES.md, and both the older .sln and the newer .slnx format. The licence is MIT for the wrapper itself, which is worth separating from the licensing situation of the charting library underneath it, since that changed with the v7 release.

Two NuGet packages, because MAUI is not the same as a browser

Installation splits along host platform. For Blazor projects running in a web browser, in WinForms, or in WPF, the package is Blazor-ApexCharts:

dotnet add package Blazor-ApexCharts

For Blazor projects running on .NET MAUI, there is a separate package, Blazor-ApexCharts-MAUI:

dotnet add package Blazor-ApexCharts-MAUI

The split is small but it is a real maintenance surface, since MAUI applications embed the WebView and need the host registration handled differently. The chart service registration reflects the same split, with AddApexChartsMaui() for MAUI hosts and AddApexCharts() everywhere else. Once the package is in place you add a namespace reference in your _Imports.razor:

@using ApexCharts

One caveat before you start. A wrapper tracks the library it wraps, and this one has just crossed a major version boundary. The v7.0.0 release, published on 2026-07-24, is titled as an ApexCharts.js 6.5.0 upgrade plus premium licensing, which means the wrapper version number and the underlying library version number now have to be read together.

ChartService for global options, locales, and screen management

ChartService is optional, and the documentation is explicit about that. When you register it, it manages global options, sets locales, and manages charts on the screen. Registration is one call that adds a scoped IApexChartService to the dependency injection container:

services.AddApexCharts();

If you want global options at registration time, the same extension method takes a configuration callback:

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

The scoped lifetime is the detail worth noting. A scoped service means one instance per request in a server-side Blazor application, so global option changes do not leak between users, which is exactly what you want for a service that manages the charts on the screen. Without the service, each chart carries its own options and nothing is shared, so the question to ask is whether your application has a single global theme or per-page themes. If it is the former, the service saves you repeating a theme on every chart component. If the latter, it may be one more thing to configure than you need.

The first chart: typed series bound with lambdas

The first chart example binds two series to a list of a locally defined class. The generic parameter TItem is the data type, the series element carries the item list, the series name, the series type, and two lambda expressions for the X and Y values:

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

The lambdas are the ergonomic core of the wrapper. Instead of maintaining a separate data adapter in JavaScript, you write an expression against your own model, and the wrapper does the projection. The cost of that convenience is that the series is tied to a compile-time type, so a heterogeneous chart needs a common type or a different approach.

A second rule is stated in bold in the documentation and is the one most likely to bite: the chart options cannot be shared, and each chart instance must have its own ApexChartOptions instance. The options live in the ApexChartOptions class, with more detail in the ApexCharts documentation. A shared options object is a tempting optimisation when you have forty charts on one dashboard, and it is the wrong move.

Premium modules arrive watermarked until a key is applied

ApexCharts 6.0 introduced a set of premium interaction modules: history for undo and redo, perspectives for shareable view state, link for crossfilter and linked views, ink for draggable annotations, measure for a delta ruler, contextMenu for point actions, and storyboard for scroll-driven views. The documentation states that all chart types and every other option remain free and are never gated, which is the reassuring part of the story.

The behaviour of a premium module without a licence is specific rather than broken. The modules work fully in trial mode, but a chart that uses one shows an unobtrusive APEXCHARTS watermark until a valid licence key is applied. The key format is shared across the ApexCharts family, which includes apexgantt, apextree, and apexsankey, and it is validated offline with no network call, so key validation does not add a runtime dependency on a licence server.

A key can be applied in three ways. Application-wide through the service, which the documentation recommends because the key is applied once before any chart renders:

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

From configuration or environment, reading the key out of the host builder configuration:

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

Or per chart through the chart options, which the documentation notes 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>

A key can also be set or changed at runtime through the service, and the documentation states that a late valid key followed by a chart update clears an on-screen watermark without a full re-render. Without any key at all, AddApexCharts() still works and the premium features simply render watermarked, so the wrapper does not fail closed.

What the wrapper does not decide for you

Two limitations are worth naming before you commit.

The first is the one already mentioned: the options object is per chart instance. On a dashboard with many charts this means many option objects, and it rules out the common pattern of a shared, centrally configured options instance.

The second is the boundary of the wrapper itself. The documentation points you at the ApexCharts documentation for the full list of options, which is a good sign for coverage and a reminder that the wrapper does not add semantics of its own beyond the C# surface. Anything you want to do that the wrapper does not expose is done in JavaScript against the underlying library, and you are back to writing interop. The wrapper is the fast path, not the full API surface.

On maintenance, the last push to the repository was on 2026-07-24, the same day as the v7.0.0 release, and the preceding releases were v6.1.0 on 2026-01-17 and v6.0.2 on 2025-08-22. The pattern is a release when the underlying library moves, with patch releases in between, which is a reasonable cadence for a wrapper and means your upgrade decisions are driven by ApexCharts.js versions rather than by wrapper features.

Editorial conclusion

Adopt Blazor-ApexCharts if your team already writes Blazor and wants ApexCharts.js behaviour without writing the JavaScript interop yourself, and if the premium modules in ApexCharts.js 6.0 are worth a licence key. Do not adopt it for server-side rendering of charts or for teams that need a chart library with no JavaScript dependency. Verify first whether a per-chart ApexChartOptions instance is workable in your design, because the options object cannot be shared between chart instances.

Frequently asked questions

Official sources

1. apexcharts/Blazor-ApexCharts on GitHub
2. License: MIT
3. Project website
4. README
5. Releases