--- meta: title: Data Chart description: Charts visualize data using line, bar, area, circular, statistical, hierarchical, and flow layouts powered by Apache ECharts. 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. ::: ### 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. ```html:preview ``` ### 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 ``` ### Pie Chart Use `type="pie"` for part-to-whole data. The first series supplies the slice values and `categories` supplies their names. ```html:preview ``` ### 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. ```html:preview ``` ### 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. ```html:preview ``` ### Radar Chart Use `type="radar"` with an `indicators` array describing each axis. Each normal series becomes one radar shape. ```html:preview ``` ### Gauge Chart Use `type="gauge"` for a single current value. `min-value`, `max-value`, and `y-axis-append` configure its range and displayed unit. ```html:preview ``` ### Funnel Chart Use `type="funnel"` for ordered stages. Numeric values pair with `categories`, using the same compact format as pie charts. ```html:preview ``` ### 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. ```html:preview ``` ### Treemap Chart Use `type="treemap"` with hierarchical `children` data to compare nested values by area. ```html:preview ``` ### Sunburst Chart Use `type="sunburst"` for radial hierarchical data. `inner-radius` and `outer-radius` adjust the occupied area. ```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. ### 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: ```json [{ "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 `indicators` array 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 with `categories` and `y-categories`. - Treemaps and sunbursts accept hierarchical nodes containing `name`, optional `value`, and optional recursive `children`. ### 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 - **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 `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 ## Signed SSE charts Use SSE for a moving time window with authoritative bucket updates: ```html ``` 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.