--- meta: title: Data Chart description: Charts visualize data using various chart types powered by Apache ECharts. Display line charts, bar charts, area charts, sankey diagrams, and more with full customization options. layout: component --- ```html:preview ``` :::tip The chart component is built on Apache ECharts, providing a powerful and flexible charting library with extensive customisation options. Visit the [Apache ECharts documentation](https://echarts.apache.org/en/option.html) 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. ```html:preview ``` ### Bar Chart Use `type="bar"` to create a vertical bar chart. Perfect for comparing values across categories. ```html:preview ``` ### Area Chart Use `type="area"` to create an area chart with filled regions under the line. ```html:preview ``` ### Multiple Series Charts support multiple data series. Each series appears with its own color and legend entry. ```html:preview ``` ### Stacked Bar Chart Use the `stacked` attribute to create stacked bar charts where series are stacked on top of each other. ```html:preview ``` ### Stacked Area Chart Stacked area charts work similarly to stacked bar charts but with area fills. ```html:preview ``` ### Chart Heights Use the `height` attribute to control the chart's height in pixels. The default height is 300px. ```html:preview
``` ### 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. ```html:preview
``` ### 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. ```html:preview
``` ### Time Series with X-Axis Type Use the `xaxis` attribute to specify the x-axis type. Common values include `datetime`, `category`, and `numeric`. ```html:preview ``` :::tip 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`. ```html:preview ``` ### 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. ```html:preview ``` ### 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. ```html:preview ``` 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. ```html:preview ``` ### Single Series Chart For simple visualizations, use a single data series without multiple comparisons. ```html:preview ``` ### Empty State When no data is available, the chart will display an empty state. Consider adding custom messaging around the chart component. ```html:preview ``` ### 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. ```html:preview ``` ### Cross-Chart Tooltip Sync Use `sync-group=""` on two or more charts to synchronise hover tooltips, zoom, and legend selection across them. ```html:preview
``` ### Custom Colors Use the `colors` attribute to set the palette that cycles across series. ```html:preview ``` For a specific series colour, add a `color` property to the series object in the `data` array: ```html:preview ``` ### 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. ```html:preview ``` ### Responsive Charts Charts automatically resize to fit their container. The width adapts to the parent element while height is controlled by the `height` attribute. ```html:preview

``` ### Combining Different Configurations You can combine various attributes to create rich, informative charts. ```html:preview ``` ## 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 ```json [ { "name": "Series Name", "data": [10, 20, 30, 40, 50] } ] ``` ### Multiple Series Format ```json [ { "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: ```json [ { "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: ```json [{ "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: ```html ``` ## JavaScript API You can also interact with the chart component using JavaScript: ```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 `live` mode 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-append` to add units or symbols to values - Format dates consistently when using time series data