st.echarts_chart
Display an interactive Apache ECharts chart.
Apache ECharts is a powerful, open-source charting library with a large catalog of chart types (including gauges, sunbursts, sankey, graph/network, candlestick, radar, and more).
To show an ECharts chart in Streamlit, pass an ECharts option object as a Python dictionary (the same JSON you would pass to setOption in JavaScript), a JSON string, or a pyecharts chart instance.
Note
st.echarts_chart supports only JSON-compatible option objects. Embedding JavaScript callbacks (e.g. formatter functions or renderItem) is not supported. Most formatting needs are covered by ECharts' string-template formatters (e.g. "formatter": "{b}: {c}").
Consequently, three families of ECharts charts are unavailable and raise an error: custom series (which require a renderItem callback), map and geo charts (which require registering GeoJSON map data), and 3D or WebGL charts from the ECharts GL extension (bar3D, scatter3D, globe, and similar).
Note
Strings in the option object (title.text, legend names, labels) are rendered by ECharts as plain text. Streamlit markdown does not apply inside spec. Put formatted copy in st.markdown next to the chart instead.
| Function signature[source] | |
|---|---|
st.echarts_chart(spec, *, width="stretch", height="content", theme="streamlit", key=None, renderer="canvas", alt=None) | |
| Parameters | |
spec (dict, str, or pyecharts chart) | The ECharts option object to render. This can be one of the following:
If your option object includes a dataset with a dataframe-like source (pandas, Polars, PyArrow, and others), Streamlit converts it to JSON records and preserves the column order through dataset.dimensions when you haven't set it. |
width ("stretch", "content", or int) | The width of the chart element. This can be one of the following:
|
height ("content", "stretch", or int) | The height of the chart element. This can be one of the following:
|
theme ("streamlit" or None) | The theme of the chart. If theme is "streamlit" (default), Streamlit applies its own colors, fonts, and plot layout. If theme is None, Streamlit leaves your spec's styling untouched and uses ECharts' built-in default theme. Two defaults still apply when theme is None:
The "streamlit" theme can be partially customized through the configuration options theme.chartCategoricalColors and theme.chartSequentialColors. Font configuration options are also applied. |
key (str, int, or None) | An optional key that gives this element a stable identity. If this is None (default), the chart's identity is determined by its position in the app, so moving it can reset the chart and replay its entry animation. If key is provided, it will be used as a CSS class name prefixed with st-key-, and the chart keeps its identity across reruns even when the spec, theme, or renderer changes. |
renderer ("canvas" or "svg") | The renderer passed to ECharts. This can be one of the following:
|
alt (str or None) | A description of the chart for screen readers and other assistive technologies. Streamlit maps this to ECharts' aria.label.description, which becomes the chart's accessible name. If this is None (default), ECharts keeps its generated data-derived name when aria.enabled is on. An empty or whitespace-only string is treated the same as None and is logged so authors notice the dual meaning of alt="" across commands (decorative only on st.image / st.pyplot). When both alt and an author aria.label.description are set, alt overrides that description for the accessible name. A non-empty alt also keeps the chart named even if the option sets aria.enabled to False. Because ECharts already generates a data-derived name, prefer a short, specific description; a vague one can be worse than none. This is a short description of the chart, not a full text alternative for dense graphics. |
Examples
Example 1: Basic bar chart
import streamlit as st st.echarts_chart( { "xAxis": {"type": "category", "data": ["A", "B", "C", "D", "E"]}, "yAxis": {"type": "value"}, "series": [{"type": "bar", "data": [5, 20, 36, 10, 10]}], }, alt="Bar chart of categories A through E", )
Example 2: Chart from a dataframe
Pass a dataframe as dataset.source. Streamlit converts it to JSON records and preserves column order through dataset.dimensions.
import pandas as pd import streamlit as st df = pd.DataFrame( { "product": ["Matcha", "Milk Tea", "Cocoa"], "2015": [43.3, 83.1, 86.4], "2016": [85.8, 73.4, 65.2], } ) st.echarts_chart( { "legend": {}, "tooltip": {}, "dataset": {"source": df}, "xAxis": {"type": "category"}, "yAxis": {}, "series": [{"type": "bar"}, {"type": "bar"}], } )
Example 3: Zoom slider, toolbox, and legend
In-chart controls such as dataZoom and toolbox are configured in the spec. Streamlit's hover toolbar (download, fullscreen) is separate from ECharts' toolbox: omit saveAsImage if you only want Streamlit's download, or set toolbox.left so the two don't stack in the top-right corner. Place legend at the top so it doesn't share the footer with a bottom dataZoom slider.
import streamlit as st st.echarts_chart( { "legend": {"data": ["Revenue", "Cost"], "top": 28}, "tooltip": {"trigger": "axis"}, "toolbox": { "left": 0, "feature": { "magicType": {"type": ["line", "bar"]}, "restore": {}, }, }, "dataZoom": [ {"type": "inside"}, {"type": "slider"}, ], "xAxis": { "type": "category", "data": ["Q1", "Q2", "Q3", "Q4"], }, "yAxis": {"type": "value"}, "series": [ { "name": "Revenue", "type": "line", "data": [820, 932, 901, 934], }, { "name": "Cost", "type": "bar", "data": [500, 610, 550, 700], }, ], } )
Tip
Want a new st.echarts_chart feature or found a bug? Browse open issues and react with a 👍 on the initial post of the ones that matter to you. Your votes help us prioritize what to work on next.
Still have questions?
Our forums are full of helpful information and Streamlit experts.