- Data Chart
- Examples
- Basic Line Chart
- Bar Chart
- Area Chart
- Multiple Series
- Stacked Bar Chart
- Stacked Area Chart
- Chart Heights
- Data Point Markers
- Y-Axis Formatting
- Time Series with X-Axis Type
- Expected Range Bands
- Enable Animations
- Smooth Lines
- Scaled Y-Axis
- Single Series Chart
- Empty State
- Sankey Diagram
- Pie Chart
- Donut Chart
- Scatter Chart
- Radar Chart
- Gauge Chart
- Funnel Chart
- Heatmap Chart
- Treemap Chart
- Sunburst Chart
- Cross-Chart Tooltip Sync
- Custom Colors
- Dark Mode Support
- Responsive Charts
- Combining Different Configurations
- Data Format
- Basic Series Format
- Multiple Series Format
- Time Series Format
- Sankey Edge Format
- Pie and Donut Data
- Specialized Data Formats
- HTML Encoding
- JavaScript API
- Best Practices
- Choosing Chart Types
- Performance Considerations
- Accessibility
- Data Formatting
- Signed SSE charts
- Importing
- Properties
- Events
- Parts
Chart
<zn-chart> | ZnChart
Chart component powered by Apache ECharts.
<zn-chart type="area" smooth categories="["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep"]" data="[{"name":"Series 1","data":[30,40,45,50,49,60,70,91,125]}]" height="300"> </zn-chart>
The chart component is built on Apache ECharts, providing a powerful and flexible charting library with extensive customisation options. Visit the Apache ECharts documentation for advanced configuration reference.
Examples
Basic Line Chart
Use type="line" to create a line chart. The data attribute accepts an array of
series objects, and categories defines the x-axis labels.
<zn-chart type="line" scale categories="["Jan","Feb","Mar","Apr","May","Jun"]" data="[{"name":"Revenue","data":[30,40,35,50,49,60]},{"name":"Expenses","data":[20,29,25,35,39,45]}]" height="300"> </zn-chart>
Bar Chart
Use type="bar" to create a vertical bar chart. Perfect for comparing values across categories.
<zn-chart type="bar" categories="["Q1","Q2","Q3","Q4"]" data="[{"name":"Sales","data":[44,55,57,56]},{"name":"Returns","data":[13,23,20,8]}]" height="300"> </zn-chart>
Area Chart
Use type="area" to create an area chart with filled regions under the line.
<zn-chart type="area" categories="["Mon","Tue","Wed","Thu","Fri","Sat","Sun"]" data="[{"name":"Active Users","data":[150,200,180,220,240,280,260]}]" height="300"> </zn-chart>
Multiple Series
Charts support multiple data series. Each series appears with its own color and legend entry.
<zn-chart type="line" categories="["Week 1","Week 2","Week 3","Week 4"]" data="[{"name":"Product A","data":[45,52,48,61]},{"name":"Product B","data":[35,41,36,46]},{"name":"Product C","data":[25,28,32,38]}]" height="350"> </zn-chart>
Stacked Bar Chart
Use the stacked attribute to create stacked bar charts where series are stacked on top of each
other.
<zn-chart type="bar" stacked categories="["Jan","Feb","Mar","Apr","May"]" data="[{"name":"Direct","data":[44,55,41,37,22]},{"name":"Referral","data":[53,32,33,52,13]},{"name":"Organic","data":[12,17,11,9,15]}]" height="300"> </zn-chart>
Stacked Area Chart
Stacked area charts work similarly to stacked bar charts but with area fills.
<zn-chart type="area" stacked smooth categories="["Jan","Feb","Mar","Apr","May","Jun"]" data="[{"name":"Desktop","data":[300,400,350,500,490,600]},{"name":"Mobile","data":[200,290,250,350,390,450]},{"name":"Tablet","data":[100,150,120,180,170,200]}]" height="300"> </zn-chart>
Chart Heights
Use the height attribute to control the chart’s height in pixels. The default height is 300px.
<zn-chart type="bar" categories="["Small","Medium","Large"]" data="[{"name":"Orders","data":[12,19,15]}]" height="200"> </zn-chart> <br /> <zn-chart type="line" scale categories="["Jan","Feb","Mar","Apr"]" data="[{"name":"Sales","data":[40,55,45,60]}]" height="400"> </zn-chart>
Data Point Markers
Use the d-size attribute to control the size of data point markers on line and area charts.
Default size is 1.
<zn-chart type="line" scale categories="["Jan","Feb","Mar","Apr","May"]" data="[{"name":"Small Markers","data":[30,40,35,50,49]}]" d-size="1" height="250"> </zn-chart> <br /> <zn-chart type="line" scale categories="["Jan","Feb","Mar","Apr","May"]" data="[{"name":"Large Markers","data":[30,40,35,50,49]}]" d-size="6" height="250"> </zn-chart>
Y-Axis Formatting
Use y-axis-append to add a suffix to y-axis labels and tooltip values. Common uses include
units like %, $, K, M, etc.
<zn-chart type="bar" categories="["Product A","Product B","Product C"]" data="[{"name":"Market Share","data":[25,35,40]}]" y-axis-append="%" height="300"> </zn-chart> <br /> <zn-chart type="line" categories="["Jan","Feb","Mar","Apr"]" data="[{"name":"Revenue","data":[100,120,115,140]}]" y-axis-append="K" height="300"> </zn-chart>
Time Series with X-Axis Type
Use the xaxis attribute to specify the x-axis type. Common values include
datetime, category, and numeric.
<zn-chart type="line" xaxis="datetime" data="[{"name":"Traffic","data":[{"x":1609459200000,"y":30},{"x":1612137600000,"y":40},{"x":1614556800000,"y":35},{"x":1617235200000,"y":50},{"x":1619827200000,"y":49},{"x":1622505600000,"y":60}]}]" height="300"> </zn-chart>
When using xaxis="datetime", provide data in the format
[{x: timestamp, y: value}] where x is a Unix timestamp in milliseconds. The
chart will automatically format the dates on the x-axis.
Expected Range Bands
Each series accepts optional stack, areaStyle, lineStyle,
symbol, silent and z settings, which apply to that series only. Draw
a shaded band with two series sharing a stack: an invisible base holding the lower bound, then
a filled series holding the band’s height. Giving both the same name lets the legend toggle the
band as one. silent series ignore the mouse and stay out of tooltips.
<zn-chart type="line" xaxis="datetime" data="[{"name":"Expected range","data":[[1609459200000,20],[1609462800000,25],[1609466400000,28],[1609470000000,30],[1609473600000,26],[1609477200000,22]],"stack":"band","areaStyle":{"opacity":0},"lineStyle":{"opacity":0},"symbol":"none","silent":true,"color":"#93c5fd"},{"name":"Expected range","data":[[1609459200000,20],[1609462800000,20],[1609466400000,22],[1609470000000,24],[1609473600000,22],[1609477200000,20]],"stack":"band","areaStyle":{"opacity":0.25},"lineStyle":{"opacity":0},"symbol":"none","silent":true,"color":"#93c5fd"},{"name":"Traffic","data":[[1609459200000,30],[1609462800000,38],[1609466400000,70],[1609470000000,44],[1609473600000,40],[1609477200000,33]],"color":"#2563eb"}]" height="300"> </zn-chart>
Enable Animations
By default, animations are disabled for better performance. Add the enable-animations attribute
to animate on first render — bars grow from the baseline and lines draw in. Pass a number (milliseconds) to
control the duration; bare enable-animations defaults to 1500.
<zn-chart type="bar" categories="["A","B","C","D","E"]" data="[{"name":"Values","data":[44,55,41,37,52]}]" enable-animations="2500" height="300"> </zn-chart>
Smooth Lines
Add the smooth attribute to render line and area charts with curved segments instead of
straight ones. Ignored for bar and sankey charts.
<zn-chart type="line" smooth categories="["Jan","Feb","Mar","Apr","May","Jun"]" data="[{"name":"Revenue","data":[30,40,35,50,49,60]}]" height="300"> </zn-chart>
Scaled Y-Axis
By default the y-axis starts at 0. Add the scale attribute to adapt the y-axis to
the data range — useful when values are clustered far from zero and you want to emphasise variation.
<zn-chart type="line" scale categories="["Mon","Tue","Wed","Thu","Fri"]" data="[{"name":"Temperature","data":[18,19,17,20,22]}]" y-axis-append="°C" height="300"> </zn-chart>
Pass a number to scale to add that percentage of padding on top and bottom of the data range
(e.g. scale="10" adds 10% padding). Larger values make the axis “breathe” more around the data.
<zn-chart type="line" scale="10" categories="["Mon","Tue","Wed","Thu","Fri"]" data="[{"name":"Temperature","data":[18,19,17,20,22]}]" y-axis-append="°C" height="300"> </zn-chart>
Single Series Chart
For simple visualizations, use a single data series without multiple comparisons.
<zn-chart type="area" categories="["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug"]" data="[{"name":"Page Views","data":[1200,1900,1500,2200,2400,2800,2600,3100]}]" height="300"> </zn-chart>
Empty State
When no data is available, the chart will display an empty state. Consider adding custom messaging around the chart component.
<zn-chart type="line" categories="[]" data="[]" height="300"> </zn-chart>
Sankey Diagram
Use type="sankey" to render a Sankey flow diagram. Each item in the series
data array is an edge with source, target, and value.
Nodes are auto-derived from unique source/target values.
<zn-chart type="sankey" height="400" data="[{"name":"Payment Flow","data":[{"source":"Stripe","target":"USD","value":1200},{"source":"Stripe","target":"EUR","value":430},{"source":"USD","target":"Captured","value":900},{"source":"USD","target":"Declined","value":300},{"source":"EUR","target":"Captured","value":380},{"source":"EUR","target":"Declined","value":50}]}]"> </zn-chart>
Pie Chart
Use type="pie" for part-to-whole data. The first series supplies the slice values and
categories supplies their names.
<zn-chart type="pie" categories="["Configuration suggestion","Insecure configuration"]" data="[{"name":"Insights","data":[8,1]}]" height="300"> </zn-chart>
Donut Chart
Use type="donut" for a pie chart with a hollow centre. Adjust the ring with
inner-radius and outer-radius; both accept an ECharts pixel value or percentage.
Add show-labels to render labels beside the slices.
<zn-chart type="donut" inner-radius="45%" outer-radius="75%" colors="["#ffe29a","#f78ab3"]" categories="["Configuration suggestion","Insecure configuration"]" data="[{"name":"Insights","data":[8,1]}]" height="300"> </zn-chart>
Scatter Chart
Use type="scatter" with [x, y] coordinate pairs. d-size controls
point size, and xaxis="datetime" can be used for time-based scatter plots.
<zn-chart type="scatter" d-size="14" data="[{"name":"Latency","data":[[12,110],[24,180],[38,140],[52,260],[70,220]]}]" height="300"> </zn-chart>
Radar Chart
Use type="radar" with an indicators array describing each axis. Each normal series
becomes one radar shape.
<zn-chart type="radar" indicators="[{"name":"Security","max":100},{"name":"Performance","max":100},{"name":"Reliability","max":100},{"name":"Usability","max":100}]" data="[{"name":"Current","data":[82,71,94,76]},{"name":"Target","data":[95,90,98,90]}]" height="320"> </zn-chart>
Gauge Chart
Use type="gauge" for a single current value. min-value, max-value,
and y-axis-append configure its range and displayed unit.
<zn-chart type="gauge" min-value="0" max-value="100" y-axis-append="%" data="[{"name":"Security score","data":[82]}]" height="300"> </zn-chart>
Funnel Chart
Use type="funnel" for ordered stages. Numeric values pair with categories, using
the same compact format as pie charts.
<zn-chart type="funnel" categories="["Visitors","Trials","Customers"]" data="[{"name":"Conversion","data":[1000,320,85]}]" height="320"> </zn-chart>
Heatmap Chart
Use type="heatmap" with x-axis categories, y-categories, and
[xIndex, yIndex, value] data points. The visual range is derived from the values unless
min-value or max-value is provided.
<zn-chart type="heatmap" show-labels categories="["Mon","Tue","Wed","Thu","Fri"]" y-categories="["API","Web","Worker"]" data="[{"name":"Requests","data":[[0,0,5],[1,0,12],[2,0,8],[3,0,16],[4,0,11],[0,1,9],[1,1,15],[2,1,12],[3,1,20],[4,1,14],[0,2,3],[1,2,7],[2,2,5],[3,2,10],[4,2,8]]}]" height="320"> </zn-chart>
Treemap Chart
Use type="treemap" with hierarchical children data to compare nested values by
area.
<zn-chart type="treemap" data="[{"name":"Insights","data":[{"name":"Security","children":[{"name":"Configuration","value":8},{"name":"Insecure","value":1}]},{"name":"Performance","value":4}]}]" height="320"> </zn-chart>
Sunburst Chart
Use type="sunburst" for radial hierarchical data. inner-radius and
outer-radius adjust the occupied area.
<zn-chart type="sunburst" outer-radius="90%" data="[{"name":"Insights","data":[{"name":"Security","children":[{"name":"Configuration","value":8},{"name":"Insecure","value":1}]},{"name":"Performance","children":[{"name":"Latency","value":4}]}]}]" height="340"> </zn-chart>
Cross-Chart Tooltip Sync
Use sync-group="<id>" on two or more charts to synchronise hover tooltips, zoom, and
legend selection across them.
<zn-chart sync-group="demo-group" type="line" categories="["Mon","Tue","Wed","Thu","Fri"]" data="[{"name":"Visits","data":[120,180,150,220,190]}]" height="250"> </zn-chart> <br /> <zn-chart sync-group="demo-group" type="bar" categories="["Mon","Tue","Wed","Thu","Fri"]" data="[{"name":"Signups","data":[12,18,15,22,19]}]" height="250"> </zn-chart>
Custom Colors
Use the colors attribute to set the palette that cycles across series.
<zn-chart type="bar" colors="["#ff6c9c","#6483F2","#29bab5"]" categories="["Q1","Q2","Q3"]" data="[{"name":"A","data":[10,20,30]},{"name":"B","data":[15,25,35]},{"name":"C","data":[20,30,40]}]" height="300"> </zn-chart>
For a specific series colour, add a color property to the series object in the
data array:
<zn-chart type="line" categories="["Jan","Feb","Mar"]" data="[{"name":"Revenue","color":"hsl(210,70%,50%)","data":[10,20,30]}]" height="300"> </zn-chart>
Dark Mode Support
The chart component automatically adapts to dark mode using the t attribute. The theme adjusts
colors, gridlines, and text to match the current theme.
<zn-chart t="dark" type="area" scale smooth categories="["Mon","Tue","Wed","Thu","Fri"]" data="[{"name":"Series 1","data":[30,40,35,50,49]},{"name":"Series 2","data":[25,35,30,45,42]}]" height="300"> </zn-chart>
Responsive Charts
Charts automatically resize to fit their container. The width adapts to the parent element while height is
controlled by the height attribute.
<div style="width: 100%; max-width: 600px;"> <zn-chart type="bar" categories="["Mobile","Desktop","Tablet"]" data="[{"name":"Sessions","data":[450,680,320]}]" height="300"> </zn-chart> </div>
Combining Different Configurations
You can combine various attributes to create rich, informative charts.
<zn-chart type="line" scale categories="["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug"]" data="[{"name":"Target","data":[80,85,82,90,88,95,92,98]},{"name":"Actual","data":[75,82,78,88,91,97,94,102]}]" d-size="4" y-axis-append="%" height="350" enable-animations> </zn-chart>
Data Format
The chart component accepts data in JSON format through the data attribute. The data should be
an array of series objects.
Basic Series Format
[ { "name": "Series Name", "data": [10, 20, 30, 40, 50] } ]
Multiple Series Format
[ { "name": "Series 1", "data": [10, 20, 30, 40, 50] }, { "name": "Series 2", "data": [15, 25, 35, 45, 55] } ]
Time Series Format
When using xaxis="datetime", use the coordinate format:
[ { "name": "Time Series", "data": [ {"x": 1609459200000, "y": 30}, {"x": 1612137600000, "y": 40}, {"x": 1614556800000, "y": 35} ] } ]
Sankey Edge Format
When type="sankey", each item in the series data array is an edge:
[{ "name": "Flow", "data": [ {"source": "A", "target": "B", "value": 100}, {"source": "A", "target": "C", "value": 50} ] }]
Nodes are auto-derived from unique source/target values. To customise node appearance or ordering, include
an explicit nodes key on the series object.
Pie and Donut Data
Pie and donut charts use the first series. The standard numeric format pairs each value with the category at the same index. You can alternatively pass ECharts-style named slices when each slice needs its own metadata or colour:
[{ "name": "Insights", "data": [ {"name": "Configuration suggestion", "value": 8, "color": "#ffe29a"}, {"name": "Insecure configuration", "value": 1, "color": "#f78ab3"} ] }]
Specialized Data Formats
- Scatter points use
[x, y]or{ "x": value, "y": value }. -
Radar charts accept an
indicatorsarray of{ "name": string, "min"?: number, "max"?: number }; each series contains one value per indicator. - Gauge charts use the first value in the first series.
- Funnel charts accept the same numeric/category or named-value formats as pie charts.
-
Heatmaps use
[xIndex, yIndex, value]points withcategoriesandy-categories. -
Treemaps and sunbursts accept hierarchical nodes containing
name, optionalvalue, and optional recursivechildren.
HTML Encoding
When using the data attribute in HTML, JSON must be properly encoded. Use " for
quotes:
<zn-chart data="[{"name":"Sales","data":[10,20,30]}]" categories="["A","B","C"]"> </zn-chart>
JavaScript API
You can also interact with the chart component using JavaScript:
// Get chart element const chart = document.querySelector('zn-chart'); // Set data programmatically chart.data = [ { name: 'Series 1', data: [10, 20, 30, 40] } ]; // Set categories chart.categories = ['Q1', 'Q2', 'Q3', 'Q4']; // Change chart type chart.type = 'bar'; // Update height chart.height = 400; // Enable animations chart.enableAnimations = true;
Best Practices
Choosing Chart Types
- Line Charts: Best for showing trends over time or continuous data
- Bar Charts: Ideal for comparing discrete categories or values
- Area Charts: Good for showing cumulative totals or part-to-whole relationships over time
- Pie Charts: Useful for compact part-to-whole comparisons with a small number of slices
- Donut Charts: Useful when a pie chart needs a lighter visual weight or centred annotation space
- Scatter Charts: Show relationships, distributions, and clusters between two numeric dimensions
- Radar Charts: Compare a small number of entities across a shared set of metrics
- Gauge Charts: Display one value against a meaningful bounded range
- Funnel Charts: Show progressive reduction through ordered stages
- Heatmaps: Reveal density and patterns across two categorical dimensions
- Treemaps: Compare hierarchical values by area
- Sunburst Charts: Explore hierarchical proportions across radial levels
- Stacked Charts: Use when showing how categories contribute to a total
Performance Considerations
- Keep the number of data points reasonable (under 1000 points for optimal performance)
- Disable animations by default for better initial render performance
- Use appropriate chart heights based on the amount of data being displayed
- Consider using the
livemode only when necessary, as it can impact performance
Accessibility
- Ensure chart data is also available in an accessible format (table, list, etc.)
- Use descriptive series names that clearly identify the data
- Choose appropriate colors that provide sufficient contrast
- Consider adding supplementary text descriptions for complex charts
Data Formatting
- Use consistent units across related charts
- Round values appropriately for readability
- Use
y-axis-appendto add units or symbols to values - Format dates consistently when using time series data
Signed SSE charts
Use SSE for a moving time window with authoritative bucket updates:
<zn-chart type="line" xaxis="datetime" live live-renew-url="/sensors/live-grant?sensor=cpu&window=3600&interval=1&metric=hits" enable-animations="200"></zn-chart>
Rubix rewrites live-renew-url through the app’s authenticated route. The GET endpoint must
return JSON {stream_url, expires_at, server_time} with UTC millisecond times,
Cache-Control: no-store, and recheck login and permissions. Renewal accepts only same-origin
URLs, sends the login cookie only to that route, and rejects redirects. Return 401/403 to stop streaming
after logout or loss of access. Grants must also expire on the streaming server; the client is not an
authorization boundary.
For a grant obtained elsewhere, supply stream-url directly. Without a renewal route it stops at
the first frame’s expiry. Stream requests use EventSource with no cross-origin credentials. Existing
live data-url polling remains supported; SSE takes precedence when stream-url or
live-renew-url is present.
The stream uses snapshot, delta, and heartbeat events. Snapshots and
deltas contain {from, until, server_time, expires_at, resolution_seconds, metric, points}.
Times are UTC milliseconds; each point is {at, value}. Snapshots replace the window, deltas
replace buckets by timestamp, and heartbeats contain {server_time, expires_at}. Reconnect must
start with a snapshot. Buffers are limited to 10,000 points. A resolution or metric change requires a
snapshot.
Optional prediction contains status, average_rates, and
points with {at, lower, upper, expected, available}. Available ranges are drawn
behind actual values and labelled as average rates when necessary. Ordinary deltas preserve the range;
snapshots replace it. hide-zero hides actual zeros only.
The chart emits zn-live-status with detail.status (connecting,
connected, reconnecting, expired, denied,
invalid, or unavailable) and shows status below the plot. It closes its transport
on removal or when live mode is disabled.
Live charts honour enable-animations: a numeric value sets the update transition in
milliseconds (capped at 1,000ms). Use 350 for gentle live transitions. Initial reveal
animations remain disabled; existing points and the moving window interpolate without resetting the chart.
The expected range moves with the same transition. Animation remains enabled up to the 10,000-point live
buffer limit. Reduced-motion preferences and disabled animations produce instant updates. Recorded values
and peaks are unchanged.
Importing
If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.
To import this component from the CDN using a script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@2.0.0/dist/components/chart/chart.js"></script>
To import this component from the CDN using a JavaScript import:
import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@2.0.0/dist/components/chart/chart.js';
To import this component using a bundler:
import '@kubex/zinc/dist/components/chart/chart.js';
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
dataUrl
data-url
|
JSON series polled with live; otherwise fetched once, as a series array or
{categories, data}.
|
string
|
''
|
|
markLatest
mark-latest
|
On line and area charts, marks each series’ latest point and hides the rest. |
boolean
|
false
|
|
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
zn-chart-click |
|
Emitted when a data point, bar or slice is clicked. | - |
Learn more about events.
Parts
| Name | Description |
|---|---|
base |
The component’s base wrapper. |
Learn more about customizing CSS parts.