Atheox.ECharts 1.0.0

Atheox.ECharts

Blazor wrapper for Apache ECharts.

• Supports .NET >= 6.0
• Ships with echarts 6.0
• Apache-2.0 Licensed (same as echarts)
• Lots of examples in the Atheox.ECharts.Demo project
• Refer to the official echarts cheat sheet for a quick introduction

Supported Chart Types:

• Line
• Bar
• Pie
• Scatter
• Geo/Map
• Candlestick
• Radar
• Boxplot
• Heatmap
• Graph
• Tree
• Treemap
• Sunburst
• Parallel
• Sankey
• Funnel
• Gauge
• Pictorial Bar
• Theme River
• Custom

How to include

1. Add a package reference to Atheox.ECharts
2. Add atheox-echarts-bundle-min.js OR atheox-echarts-min.js to your _Host.cshtml or _Layout.cshtml file
   • atheox-echarts-bundle-min.js includes apache echarts and echarts-stat.
   • atheox-echarts-min.js ONLY contains the binding code and requires you to manually include apache-echarts and plugins.

<script src="_content/Atheox.ECharts/js/atheox-echarts-bundle-min.js"></script>

See the example from the demo application.

How to use

The bindings are nearly identical to the javascript/typescript version. This makes it very easy to translate the examples from the official documentation to C#.

For example: a simple pie chart.

Add a using statement:

@using Atheox.ECharts;

Chart component in your .razor file:

<Atheox.ECharts.EChart Options="@options" />

Chart options in the code section of your razor file:

private ChartOptions options = new()
{
	Title = new()
	{
		Text = "Referer of a Website",
		Subtext = "Fake Data",
		Left = "center"
	},
	Tooltip = new()
	{
		Trigger = ECharts.TooltipTrigger.Item
	},
	Legend = new()
	{
		Orient = Orient.Vertical,
		Left = "left"
	},
	Series = new()
	{
		new PieSeries()
		{
			Name = "Access From",
			Radius = new CircleRadius("50%"),
			Data = new List<PieSeriesData>()
			{
				new() { Value = 1048, Name = "Search Engine" },
				new() { Value = 735, Name = "Direct" },
				new() { Value = 580, Name = "Email" },
				new() { Value = 484, Name = "Union Ads" },
				new() { Value = 300, Name = "Video Ads" },
			},
			Emphasis = new()
			{
				ItemStyle = new()
				{
					ShadowBlur = 10,
					ShadowOffsetX = 0,
					ShadowColor = Color.FromRGBA(0, 0, 0, 0.5)
				}
			}
		}
	}
};

See the full C# code.

Chart Sizing

By default, charts are responsive and will fill their container width with a minimum height of 300px.

Default Behavior

@* Responsive: width 100%, min-height 300px *@
<Atheox.ECharts.EChart Options="@options" />

Fixed Size

Use Width and Height parameters for fixed dimensions:

<Atheox.ECharts.EChart Options="@options" Width="800px" Height="400px" />

Custom Sizing via Style

The Style parameter can override default sizing. When Style contains width or height values, the defaults are not applied:

@* Custom height, default width (100%) *@
<Atheox.ECharts.EChart Options="@options" Style="height: 500px" />

@* Fully custom sizing *@
<Atheox.ECharts.EChart Options="@options" Style="width: 50%; height: 400px" />

@* Viewport-based sizing *@
<Atheox.ECharts.EChart Options="@options" Style="height: 50vh" />

Sizing Priority

1. If Width/Height parameter is set → use it
2. Else if Style contains width/height → use Style (no default added)
3. Else → use defaults (width: 100%, min-height: 300px)

Responsive Container

For charts that should fill their parent container completely, ensure the parent has explicit dimensions:

@* Parent with explicit height *@
<div style="height: 500px">
    <Atheox.ECharts.EChart Options="@options" Style="height: 100%" />
</div>

@* Flexbox container *@
<div style="display: flex; flex-direction: column; height: 100vh">
    <Atheox.ECharts.EChart Options="@options" Style="flex: 1; min-height: 0" />
</div>

Data loading

Most examples that you will find online have very basic datasets. However, in real life, data sets are often huge and come from various different sources.

Atheox.ECharts allows you to define data in 3 different ways:

1. Inside the ChartOptions, as demonstrated in most examples.
2. Using async data loaders in C#, allowing you to fetch data directly from the database.
3. Using external data sources (e.g.: REST API) fetched by the browser.

Async data loading

Specify the DataLoader parameter, this can be a sync or async function.

<Atheox.ECharts.EChart Options="@options" DataLoader="@LoadChartData" />

Typically in the data loader function you update the Series property. However, you can update any chart option.

private async Task LoadChartData()
{
	options.Series = ... ;
}

See full example.

External Data Sources (fetch)

The short version: ExternalDataSource is provided as an EChart parameter, ExternalDataSourceRef is used in the ChartOptions to refer to a specific ExternalDataSource.

Any Data property inside the ChartOptions of type object? accepts a ExternalDataSourceRef allowing you to specify a reference to an external data source.

... = new ExternalDataSourceRef(dataSource);

An array of ExternalDataSource instances must be supplied to the the EChart ExternalDataSources parameter.

<Atheox.ECharts.EChart ExternalDataSources="@(new[] { extData })" ... />

An example on how to construct an ExternalDataSource instance:

... = new ExternalDataSource("https://example.com/api/data/sunburst_simple.json")

See full example.

It is also possible to provide a simple path expression to retrieve only a part of the external data:

... = new ExternalDataSource("https://example.com/api/data/sankey_simple.json", path: "nodes")

See full example.

Or you can execute a function after load to manipulate the loaded data:

... = new ExternalDataSource("/data/les-miserables.json", ExternalDataFetchAs.Json)
{
	AfterLoad = new JavascriptFunction(@"function (graph) {
		graph.nodes.forEach(function (node) { node.symbolSize = 5; });
		return graph;
	}")
};

See full example.

See Javascript functions chapter in the readme for more details about JS functions.

An ExternalDataSourceRef also supports a path expression to select a child object.

... = new ExternalDataSourceRef(graph, "nodes")
... = new ExternalDataSourceRef(graph, "links")
... = new ExternalDataSourceRef(graph, "categories")
}

See example.

Additional credentials, headers, policies, ... can also be supplied. See ExternalDataSource and FetchOptions for more details.

Remark 1: Never make an ExternalDataSource static, you need 1 instance per chart.

Remark 2: You will get a InvalidOperationException if you try to use ExternalDataSource in the chart options.

Datasets

ECharts supports dataset transformations. This allows for simplified data retrieval, without the need to have a separate dataset for different charts or chart types.

See example # and example 2 .

See also the echarts dataset documentation and tutorial .

Javascript functions

ECharts sometimes allows you to assign custom functions instead of values. This can be achieved with the JavascriptFunction class. The class accepts a string literal containing the Javascript function. The function is evaluated inside the brower. Be carefull: syntax errors in the JS function will break the chart serialization.

For example:

Formatter = new JavascriptFunction("function (param) { return param.name + ' (' + param.percent * 2 + '%)'; }")

See full example.

Updating charts

Chart options and/or data can be updated. For example: to show a never ending line chart, a temperature gauge, ... .

First store a reference to your chart.

<Atheox.ECharts.EChart @ref="chart" Options="@options" />
...
private Atheox.ECharts.EChart? chart;

Next modify the chart options. Modified options have full support for Javascript functions and external data sources.

private async Task UpdateChartAsync()
{
	if (chart == null)
		return;

	// modify chart options

	await chart.UpdateAsync();
}

See full example.

Dark Mode / Theme Support

Atheox.ECharts supports automatic theme switching based on an HTML attribute observer. This is useful when working with CSS frameworks like Bootstrap 5 that use data-bs-theme attributes for dark mode.

Global Configuration (Recommended)

Configure theme observation globally in Program.cs so all charts automatically respond to theme changes:

// In Program.cs
builder.Services.AddAtheoxECharts(options =>
{
    options.ThemeObserverSelector = "html";           // CSS selector for the element to observe
    options.ThemeObserverAttribute = "data-bs-theme"; // Attribute name to watch
    options.ThemeObserverDarkValue = "dark";          // Value that indicates dark mode
});

When the observed attribute changes to the dark value, all charts automatically switch to ECharts' built-in dark theme. When it changes to any other value, charts revert to the default light theme.

Note: Calling AddAtheoxECharts() is optional. If not called, charts work normally without theme observation.

Per-Component Configuration

You can also configure theme observation on individual charts, which overrides global settings:

<EChart Options="@options"
        ThemeObserverSelector="html"
        ThemeObserverAttribute="data-bs-theme"
        ThemeObserverDarkValue="dark" />

Mixed Configuration

Component parameters take precedence over global options:

@* Uses global options *@
<EChart Options="@options1" />

@* Override just the selector, inherit other settings from global *@
<EChart Options="@options2" ThemeObserverSelector="body" />

@* Disable theme observer for this specific chart *@
<EChart Options="@options3" ThemeObserverSelector="" />

How It Works

When theme observation is enabled:

1. On chart initialization, the current theme is detected from the observed element's attribute
2. A MutationObserver watches for attribute changes on the specified element
3. When the attribute changes, the chart is reinitialized with the appropriate theme
4. Explicitly set colors in your ChartOptions are preserved; only theme-provided colors change
5. The observer is cleaned up when the chart is disposed

Design Tokens (Custom Theming)

Atheox.ECharts supports a token-based design system similar to ECharts 6.0. This allows you to customize chart colors and sizes to match your application's design system.

Global Token Configuration

Configure custom tokens globally in Program.cs:

builder.Services.AddAtheoxECharts(options =>
{
    // Theme observer settings (optional)
    options.ThemeObserverSelector = "html";
    options.ThemeObserverAttribute = "data-bs-theme";
    options.ThemeObserverDarkValue = "dark";

    // Custom tokens for light mode
    options.Tokens = new EChartsTokens
    {
        Color = new EChartsColorTokens
        {
            // Override specific colors
            Primary = "#1a73e8",
            Border = "#dadce0",
            Theme = new[] { "#1a73e8", "#34a853", "#fbbc05", "#ea4335", "#673ab7" }
        }
    };

    // Custom tokens for dark mode (optional - uses EChartsTokens.Dark if not set)
    options.DarkTokens = new EChartsTokens
    {
        Color = new EChartsColorTokens
        {
            Primary = "#8ab4f8",
            Border = "#5f6368",
            Theme = new[] { "#8ab4f8", "#81c995", "#fdd663", "#f28b82", "#b39ddb" }
        }
    };
});

Per-Chart Token Configuration

Override tokens for specific charts:

<EChart Options="@options"
        Tokens="@customTokens"
        DarkTokens="@customDarkTokens" />

@code {
    private EChartsTokens customTokens = new()
    {
        Color = new EChartsColorTokens
        {
            Theme = new[] { "#ff6b6b", "#4ecdc4", "#45b7d1", "#96ceb4", "#ffeaa7" }
        }
    };
}

Available Token Properties

Color Tokens (EChartsColorTokens):

• Theme - Array of colors for the chart palette
• Primary, Secondary, Tertiary, Quaternary - Text colors
• Disabled - Disabled/inactive color
• Border, BorderTint, BorderShade - Border colors
• Background, BackgroundTint, BackgroundShade - Background colors
• Shadow, ShadowTint - Shadow colors
• AxisLine, AxisTick, AxisLabel, AxisSplitLine - Axis colors
• Neutral00 through Neutral80 - Neutral color scale

Size Tokens (EChartsSizeTokens):

• Xxs (2), Xs (5), S (10), M (15), L (20), Xl (30), Xxl (40), Xxxl (50)

Using Predefined Token Sets

// Use default light mode tokens
var lightTokens = EChartsTokens.Light;

// Use default dark mode tokens
var darkTokens = EChartsTokens.Dark;

// Clone and modify
var customTokens = EChartsTokens.Light.Clone();
customTokens.Color.Primary = "#custom-color";

Filing Bugs / Future Development

See Issues for a list of open tasks/bugs.

Please provide a runnable sample using the ECharts Online Editor and a description of what is wrong with the C# mapping.