Show API reference for

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")

Parameters

spec (dict, str, or pyecharts chart)

The ECharts option object to render. This can be one of the following:

  • A Python dict matching the ECharts option object structure.
  • A JSON str (handy for copy-pasting an option from the ECharts examples gallery).
  • A pyecharts chart instance, which is detected through duck typing (the presence of a dump_options method) and converted automatically. pyecharts is not a Streamlit dependency.

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:

  • "stretch" (default): The width of the element matches the width of the parent container.
  • "content": The width of the element matches the width of its content, but doesn't exceed the width of the parent container. Because an ECharts spec has no intrinsic width, this is a fixed default of 700 pixels, unless a pyecharts chart sets its own width through InitOpts (pyecharts' library default is ignored, and "100%" is treated as "stretch").
  • An integer specifying the width in pixels: The element has a fixed width. If the specified width is greater than the width of the parent container, the width of the element matches the width of the parent container.

height ("content", "stretch", or int)

The height of the chart element. This can be one of the following:

  • "content" (default): The height of the element matches the height of its content. Because an ECharts spec has no intrinsic height, this is a fixed default of 350 pixels — matching st.line_chart and the other Vega-based charts — unless a pyecharts chart sets its own height through InitOpts (pyecharts' library default is ignored, and "100%" is treated as "stretch").
  • "stretch": The height of the element matches the height of its content or the height of the parent container, whichever is larger. If the element is not in a parent container, the height of the element matches the height of its content.
  • An integer specifying the height in pixels: The element has a fixed height.

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:

  • Accessibility: aria.enabled stays on so the chart keeps a screen-reader description unless you set aria yourself.
  • Display-only cursor: a missing series.cursor is set to "default" so the chart does not look clickable. Set series.cursor yourself to override it.

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:

  • "canvas" (default): Best for large datasets.
  • "svg": Produces real DOM nodes that are better for printing, sharp scaling, and accessibility.

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]}],
    }
)
Built with Streamlit 🎈

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],
            },
        ],
    }
)
Built with Streamlit 🎈
star

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.

arrow_backPrevious: st.bokeh_chartarrow_forwardNext: st.graphviz_chart
forum

Still have questions?

Our forums are full of helpful information and Streamlit experts.