- 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
- Enable Animations
- Smooth Lines
- Scaled Y-Axis
- Single Series Chart
- Empty State
- Sankey Diagram
- 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
- HTML Encoding
- JavaScript API
- Best Practices
- Choosing Chart Types
- Performance Considerations
- Accessibility
- Data Formatting
- Importing
- 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.
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>
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.
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
- 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
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@1.0.112/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@1.0.112/dist/components/chart/chart.js';
To import this component using a bundler:
import '@kubex/zinc/dist/components/chart/chart.js';
Parts
| Name | Description |
|---|---|
base |
The component’s base wrapper. |
Learn more about customizing CSS parts.