Playground
Draws an Apache ECharts chart from an option your server sends as JSON. The element does the part every page would otherwise write again: it colours the chart from the page's --sb-* tokens and follows theme changes, writes numbers, months and weekdays in the reader's language, keeps the legend (wrapped onto as many rows as it needs) and a zoom slider clear of the axes, and animates each new option into place. ECharts itself is vendored with the component and loaded only when a chart comes near the screen.
Size it with CSS (block-size, height); it defaults to 18rem.
Examples
From the server
Send any ECharts option. A string that is exactly var(--token) becomes that colour, so the server can colour a series with the page's own palette.
<sb-echarts option='{
"tooltip": {"trigger": "axis"},
"legend": {"data": ["Launches", "Landings"], "top": 0},
"xAxis": {"type": "category", "data": ["2022", "2023", "2024", "2025", "2026"]},
"yAxis": {"type": "value"},
"series": [
{"name": "Launches", "type": "bar", "data": [61, 96, 134, 165, 190]},
{"name": "Landings", "type": "line", "smooth": true, "data": [55, 90, 127, 159, 186], "itemStyle": {"color": "var(--sb-ok)"}}
]
}'></sb-echarts>
Live
When the option attribute changes (a server morph, or a signal as here), the chart moves to the new state instead of redrawing.
<div data-signals="{_fuel: [82, 64, 91, 48, 73]}">
<sb-echarts style="block-size: 14rem" data-preserve-attr="option"
data-attr:option="JSON.stringify({xAxis: {type: 'category', data: ['Tank A', 'Tank B', 'Tank C', 'Tank D', 'Tank E']}, yAxis: {type: 'value', max: 100, name: '%'}, series: [{type: 'bar', data: $_fuel}]})"></sb-echarts>
<sb-button data-on:click="$_fuel = $_fuel.map(() => Math.round(20 + Math.random() * 80))">Refuel</sb-button>
</div>
Beyond axes
Axes and a grid come only with an option that has axes, so pies, gauges, and polar or calendar charts get no phantom grid.
<sb-echarts style="block-size: 16rem" option='{
"tooltip": {"trigger": "item"},
"series": [{"type": "pie", "radius": ["45%", "70%"], "data": [
{"name": "Hydrogen", "value": 74}, {"name": "Helium", "value": 24}, {"name": "Everything else", "value": 2}
]}]
}'></sb-echarts>
A fallback table
Put the same data inside the element. It shows until the chart has drawn (and without JavaScript), and afterwards it stays for screen readers, who get the numbers rather than a picture of them.
| Q1 | Q2 | Q3 | Q4 |
|---|---|---|---|
| 12 | 19 | 15 | 23 |
<sb-echarts style="block-size: 12rem" option='{"xAxis":{"type":"category","data":["Q1","Q2","Q3","Q4"]},"yAxis":{"type":"value"},"series":[{"type":"line","data":[12,19,15,23]}]}'>
<table>
<caption>Signals received per quarter</caption>
<tr><th>Q1</th><th>Q2</th><th>Q3</th><th>Q4</th></tr>
<tr><td>12</td><td>19</td><td>15</td><td>23</td></tr>
</table>
</sb-echarts>
Clicks
A click on a data item fires sb-chart-click.
<div data-signals="{_picked: ''}">
<sb-echarts style="block-size: 12rem" data-on:sb-chart-click="$_picked = evt.detail.name + ': ' + evt.detail.value"
option='{"xAxis":{"type":"category","data":["Io","Europa","Ganymede","Callisto"]},"yAxis":{"type":"value","name":"km"},"series":[{"type":"bar","data":[3643,3122,5268,4821]}]}'></sb-echarts>
<p data-text="$_picked || 'Click a bar.'"></p>
</div>
Charts whose shape is code
A custom series draws through a renderItem function, which no server can send as JSON. Define the chart once in the page's JavaScript and have the server name it:
import { defineChartKind } from '/c/echarts/echarts.js'
defineChartKind('timeline', (option, { echarts, color, css, formatNumber, lang }) => ({
xAxis: { type: 'time' },
yAxis: { type: 'category', data: option.rows },
series: [{ type: 'custom', data: option.bars, renderItem: (params, api) => { /* … */ } }],
}))
<sb-echarts option='{"kind": "timeline", "rows": ["Apollo 11"], "bars": [[0, -14182940000, -13402140000]]}'></sb-echarts>
The builder gets the ECharts module (for echarts.graphic and friends), color() to resolve a token or CSS colour, css() to read a token such as a font, the element's number format and language, and its size as width and height: a builder that reads them runs again when the element changes size. What it returns is themed like any other option. A chart whose kind the page hasn't defined yet shows its fallback, and draws as soon as the kind is defined.
Every copy of the module shares the kinds and the number format a page sets, so import it from whichever URL suits the page: the one your <script> already loads (no second download), or /c/echarts/echarts.js next to the autoloader.
Numbers
Value axes and axis tooltips format numbers with Intl.NumberFormat in the element's language, unless the option sets a formatter of its own. If your server formats numbers differently (another separator, say), set the same rule for every chart on the page so the two never disagree:
import { setNumberFormat } from '/c/echarts/echarts.js'
setNumberFormat((n, lang) => myFormat(n, lang))
Styling
Style it from your page's CSS, without changing the component or importing anything into it. Custom properties, inherited properties and ::part() all reach into its shadow root.
- Size: set
block-size(orheight) on the element; it defaults to18remand fills the width it is given. - Fonts: labels and the legend use
--sb-font-bodywhen a site sets one, numbers (the value axis, the tooltip)--sb-font-ui. Without them the chart draws in the element's own font, inherited from your page, sofont-familyon the element is enough. - Colours: series take
--sb-chart-1to--sb-chart-8, falling back to--sb-brand-light,--sb-accent,--sb-ok,--sb-warn,--sb-danger,--sb-info,--sb-text-2and--sb-brand. Text is--sb-text-2, axis labels--sb-text-muted, axis lines--sb-border, grid lines--sb-border-subtle, and the tooltip--sb-surface-overlaywith--sb-text-1values. Set any of them on the element or an ancestor to give charts their own palette. A pick onsb-theme-switch, or the system flipping under "auto", redraws the chart in the new colours without starting it again. - Parts:
plot, the box ECharts draws in (and, without a fallback, the one that takes keyboard focus:::part(plot):focus-visiblestyles its ring). Your page's::part()rules win over the component's own, without!important.
<style>
.my-chart {
block-size: 12rem;
--sb-chart-1: #F97316;
font-family: Georgia, serif;
--sb-font-body: Georgia, serif; /* only needed where a body font token is set, like here */
}
</style>
<sb-echarts class="my-chart" option='{"grid":{"top":8,"bottom":24,"left":36,"right":8},"xAxis":{"type":"category","data":["Mon","Tue","Wed","Thu","Fri"]},"yAxis":{"type":"value"},"series":[{"type":"bar","data":[120,200,150,80,70]}]}'></sb-echarts>
A font you load yourself works inside the component too: load it in the page (a <link>, or an @import at the very top of your main stylesheet). A component's own styles are a constructed stylesheet, which can't @import.
Accessibility
With a fallback table in the element, screen readers get the table and the drawing is hidden from them; if a click on the chart drills down, offer the same links outside it too. Without one, ECharts' own description is switched on, which names the chart type and series, and the chart takes keyboard focus: ←/→ step through a series' items and ↑/↓ from one series to the next, each shown with its tooltip, and Enter fires sb-chart-click for the item. With prefers-reduced-motion: reduce nothing animates.
Licence
ECharts is © The Apache Software Foundation, under the Apache License 2.0; it is vendored unmodified from the echarts@6.1.0 npm release (vendor.json), with its licence and notice in vendor/.
Installation
Add Datastar with Rocket and the Starbase autoloader once per page, then use the tag: the autoloader imports each component the first time its tag appears, including tags a Datastar morph adds later. The Datastar here is v1.0.5 with Starbase's patches. The components also run on the official v1.0.4 and v1.0.5.
<script type="importmap">
{ "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" } }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/autoloader.js"></script>
<sb-echarts option='{"xAxis":{"type":"category","data":["Mon","Tue","Wed","Thu","Fri"]},"yAxis":{"type":"value"},"series":[{"type":"bar","data":[120,200,150,80,70]}]}'></sb-echarts>No flash of undefined elements: put class="sb-cloak" on <html> and add .sb-cloak :not(:defined) { visibility: hidden } to your CSS. The autoloader removes the class once the page's components are defined.
Load just this component, pinned to this version: all its modules in one minified file with its integrity hash, so the browser refuses it if a single byte changes.
<script type="importmap">
{
"imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
"integrity": {
"https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
"https://starbase.zweiundeins.gmbh/c/echarts@e03ec27ba062/vendor/echarts.esm.min.js": "sha384-2svH5QplTeBKhRXWxXOJE2P6pRpgnqVq8l8U1dYXUBXvc2zJ/FMMardtnPnnCXnt"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/echarts@e03ec27ba062/echarts.bundle.min.js" integrity="sha384-949bsEJUYxWrfSFkozmdNcC8/OQ8eByNsxxbCgnNavsFXEtEo5f0iguV39LD+Jij"></script>
<sb-echarts option='{"xAxis":{"type":"category","data":["Mon","Tue","Wed","Thu","Fri"]},"yAxis":{"type":"value"},"series":[{"type":"bar","data":[120,200,150,80,70]}]}'></sb-echarts>Or the minified module files (2 files, which the browser requests as it finds their imports), each pinned in the import map:
<script type="importmap">
{
"imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
"integrity": {
"https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
"https://starbase.zweiundeins.gmbh/c/echarts@e03ec27ba062/echarts.min.js": "sha384-EseJTAK45ZFxamSvvgv8qq4cD4T33B0qE5VYzoZDInT43ubkv7/ka1ccOQJEMgz+",
"https://starbase.zweiundeins.gmbh/c/echarts@e03ec27ba062/vendor/echarts.esm.min.js": "sha384-2svH5QplTeBKhRXWxXOJE2P6pRpgnqVq8l8U1dYXUBXvc2zJ/FMMardtnPnnCXnt"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/echarts@e03ec27ba062/echarts.min.js" integrity="sha384-EseJTAK45ZFxamSvvgv8qq4cD4T33B0qE5VYzoZDInT43ubkv7/ka1ccOQJEMgz+"></script>
<sb-echarts option='{"xAxis":{"type":"category","data":["Mon","Tue","Wed","Thu","Fri"]},"yAxis":{"type":"value"},"series":[{"type":"bar","data":[120,200,150,80,70]}]}'></sb-echarts>In production, pin today's whole catalog: its autoloader and an import map with integrity hashes, so the browser refuses any file that changed. This map covers Datastar and this component; importmap.json has the hashes of every component, to merge into yours.
<script type="importmap">
{
"imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
"integrity": {
"https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
"https://starbase.zweiundeins.gmbh/c/echarts@e03ec27ba062/vendor/echarts.esm.min.js": "sha384-2svH5QplTeBKhRXWxXOJE2P6pRpgnqVq8l8U1dYXUBXvc2zJ/FMMardtnPnnCXnt",
"https://starbase.zweiundeins.gmbh/c/echarts@e03ec27ba062/echarts.bundle.min.js": "sha384-949bsEJUYxWrfSFkozmdNcC8/OQ8eByNsxxbCgnNavsFXEtEo5f0iguV39LD+Jij"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/@81f24b268adb/autoloader.js" integrity="sha384-bWIhsIq9SpNUiIZyG/lv190MgHA05m8BVYA3LyIoE/pgOF3NUt0437e++4Ht1NcS"></script>
<sb-echarts option='{"xAxis":{"type":"category","data":["Mon","Tue","Wed","Thu","Fri"]},"yAxis":{"type":"value"},"series":[{"type":"bar","data":[120,200,150,80,70]}]}'></sb-echarts>Components import only datastar and their own files, so copying is enough: save each component's one file (and a file it loads on first use, keeping its folder), and point the import map at your own copy of datastar-rocket.js (the /js/ paths stand for yours).
<sb-echarts>
<script type="importmap">
{ "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/echarts/echarts.bundle.min.js"></script>
<sb-echarts option='{"xAxis":{"type":"category","data":["Mon","Tue","Wed","Thu","Fri"]},"yAxis":{"type":"value"},"series":[{"type":"bar","data":[120,200,150,80,70]}]}'></sb-echarts>Or copy the module files, keeping each component's folder, and load each component's module:
<sb-echarts>
<script type="importmap">
{ "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/echarts/echarts.min.js"></script>
<sb-echarts option='{"xAxis":{"type":"category","data":["Mon","Tue","Wed","Thu","Fri"]},"yAxis":{"type":"value"},"series":[{"type":"bar","data":[120,200,150,80,70]}]}'></sb-echarts>In Go, render it with its typed templ wrapper: one field per prop, generated from the component's manifest (the module's README has the type rules). Add the module:
go get github.com/zweiundeins/starbase/templ@latestThen load it, pinned with integrity hashes to the versions the module was generated with, and use it:
// In <head>: the components you list, pinned,
@sb.Imports(sb.ImportsProps{Components: []sb.Tag{sb.TagECharts}})
// or the autoloader, which also loads tags a morph adds later: @sb.Imports(sb.ImportsProps{})
// or, around the content of <body>, the components it renders: @sb.Tracked(sb.ImportsProps{}) { … }
@sb.ECharts(sb.EChartsProps{Option: map[string]any{"series": []any{map[string]any{"data": []any{120, 200, 150, 80, 70}, "type": "bar"}}, "xAxis": map[string]any{"data": []any{"Mon", "Tue", "Wed", "Thu", "Fri"}, "type": "category"}, "yAxis": map[string]any{"type": "value"}}})Size
A page loads this component as one file, its bundle, with what it loads on first use, each compressed on its own the way it is served (gzip -9, brotli -11): brotli is what it downloads. Datastar and Rocket are shared by every component and not counted.
| File | Original | gzip | brotli |
|---|---|---|---|
echarts.bundle.min.js | 9.5 kB | 4.7 kB | 4.2 kB |
vendor/echarts.esm.min.js on first use | 1121.7 kB | 367.3 kB | 298.8 kB |
| Total | 1131.1 kB | 372.0 kB | 303.0 kB |
Of the total, 298.8 kB brotli is loaded on first use, as soon as the component needs it.
As module files: 2 requests, 302.9 kB minified with brotli
For a page that loads the module files as they are, requesting each one as it finds its import, or bundles them itself. Each file compressed on its own; the minified one is what the page downloads, and the readable source is always there too.
| File | Original | gzip | brotli | minified |
|---|---|---|---|---|
echarts.js | 23.9 kB | 9.6 kB | 8.3 kB | 4.1 kB |
vendor/echarts.esm.min.js on first use | 1121.7 kB | 367.3 kB | 298.8 kB | 298.8 kB |
| Total | 1145.5 kB | 376.9 kB | 307.1 kB | 302.9 kB |
API reference
Props
| Attribute | Type | Default | Description |
|---|---|---|---|
option | custom | — | The ECharts option, as JSON. Strings that are exactly var(--token) become that colour. { "kind": "name", ... } is expanded by a builder the page defined with defineChartKind(). |
renderer | "canvas" | "svg" | "canvas" | Draw on a canvas, or as SVG (sharper when printed, slower with many points). |
lang | string | "" | Locale for numbers, months and weekdays (default: the page's lang, then the browser's). |
Slots
| Name | Description |
|---|---|
| A fallback for readers without the chart: shown until ECharts has drawn, kept for screen readers after that. A table of the same data is ideal. |
Events
| Name | Description |
|---|---|
sb-chart-click | A click on a data item. detail: { seriesName, seriesIndex, name, value, dataIndex }. |