Streamlit ECharts

0.6.0 · active · verified Thu Apr 16

Streamlit ECharts is a Streamlit component that enables the display of highly interactive ECharts visualizations directly within Streamlit applications. The library is actively maintained, with its latest version being 0.6.0, and has a cadence of several major releases per year, often introducing significant updates and breaking changes.

Common errors

```
Your app is having trouble loading Streamlit_echarts.st_echarts component (This app is attempting to load the component from , and hasn't received its “Streamlit:componentReady” message)
```
cause This error typically indicates an issue with the Streamlit custom component's frontend loading, possibly due to an incompatible Streamlit version, environment issues, or an older version of `streamlit-echarts`.

fix Ensure your Streamlit installation is up-to-date (`pip install --upgrade streamlit`). Verify `streamlit-echarts` is installed correctly. Try restarting your Streamlit app. For older versions, compatibility with the Streamlit Components API might be an issue.
```
NameError: name 'st_pyecharts' is not defined
```
cause The `st_pyecharts` function is not imported or the optional `pyecharts` extra for `streamlit-echarts` is not installed.

fix Import `st_pyecharts` with `from streamlit_echarts import st_pyecharts`. If still undefined, install the extra: `pip install streamlit-echarts[pyecharts]`. If you don't want the extra, convert your `pyecharts` chart to a dictionary using `json.loads(chart.dump_options())` and pass it to `st_echarts`.
```
Charts inside st.tabs are not displayed or appear blank after switching tabs.
```
cause Streamlit components within `st.tabs` can sometimes fail to render or update correctly if they lack a persistent identity or encounter rendering issues specific to tab switching.

fix Assign a unique `key` parameter to each `st_echarts` instance within your tabs (e.g., `st_echarts(options=..., key='chart_tab1')`). This helps Streamlit maintain the component's state across reruns and tab switches.
```
ECharts plot flickers or reruns animations when data or options change.
```
cause Without a stable key, Streamlit might treat the chart as a new component on each rerun, causing it to re-initialize and replay animations.

fix Provide a persistent and unique `key` argument to `st_echarts` (e.g., `st_echarts(options=..., key='my_unique_chart_id')`). This tells Streamlit to update the existing component rather than recreating it. The `replace_merge` parameter introduced in v0.6.0 can also help with smoother transitions for dynamic data.

Warnings

breaking Version 0.5.0 migrated to Streamlit Components v2 API, which might require adjustments in advanced component interactions or custom event handling.
Fix: Review your component interactions and event callbacks against the latest `streamlit-echarts` and Streamlit component documentation. The `key` parameter is now crucial for animations and stable component identity.
breaking The `st_pyecharts` wrapper was initially removed in v0.5.0, advising users to manually convert PyECharts options to JSON (`json.loads(chart.dump_options())`) and pass them to `st_echarts`. It was later reintroduced as part of an optional extra.
Fix: To use `st_pyecharts`, install with `pip install streamlit-echarts[pyecharts]`. Alternatively, use `import json` and `json.loads(chart.dump_options())` when passing PyEcharts chart instances to `st_echarts`.
breaking `pyecharts` and `simplejson` are no longer direct package dependencies of `streamlit-echarts` as of v0.5.0. Users need to install them explicitly if they intend to use `st_pyecharts` or other functionalities relying on these packages.
Fix: If you rely on `pyecharts` or `simplejson`, install them explicitly: `pip install pyecharts simplejson` (or `pip install streamlit-echarts[pyecharts]` for the wrapper).
breaking The structure of event return values changed in v0.5.0. Instead of direct return, events now populate `result.chart_event` or `result['selection']` for `on_select`.
Fix: Access event data via `result.chart_event` for general events or `result['selection']` when `on_select` is used, as demonstrated in the quickstart example and official documentation.
breaking ECharts was upgraded from v5 to v6 in v0.5.0. This might introduce subtle changes in default themes, component positions, or rendering behavior due to ECharts' own breaking changes.
Fix: Review your charts for unexpected visual changes. Consult the ECharts v6 changelog for details. You might need to adjust specific ECharts options or provide a custom theme to restore previous appearances.
gotcha ECharts plots might not display correctly or update when placed inside `st.tabs` components, with only the first tab's chart rendering reliably. This can lead to blank charts on other tabs.
Fix: Explicitly assign a unique `key` parameter to each `st_echarts` call within tabs. Sometimes recreating charts outside tabs or using `st.expander` can serve as a workaround, though recent versions with stable `key`s should mitigate this.
gotcha Charts may exhibit flickering or unexpected re-rendering behavior when their options or data are dynamically updated without a stable component identity.
Fix: Always provide a unique `key` parameter to `st_echarts` (e.g., `key='my_chart'`). This ensures Streamlit can correctly identify and update the component rather than re-mounting it, preserving animations and state.

Install

pip install streamlit-echarts Core library
pip install streamlit-echarts[pyecharts] With PyECharts support

Imports

st_echarts

from streamlit_echarts import st_echarts

st_pyecharts
wrong:
```
from streamlit_echarts import st_pyecharts # without [pyecharts] extra
```
correct:
```
from streamlit_echarts import st_pyecharts
```
Requires `streamlit-echarts[pyecharts]` to be installed. Otherwise, convert PyECharts options to a dictionary using `json.loads(chart.dump_options())` and pass to `st_echarts`.
JsCode
```
from streamlit_echarts import JsCode
```

Quickstart

This quickstart demonstrates how to render a basic ECharts bar chart using `st_echarts`. It also shows how to use the `key` parameter for stable component identity and `on_select='rerun'` for basic interactivity, capturing selection events in the Streamlit app state. An optional commented section illustrates usage with PyEcharts, which requires an extra installation.

import streamlit as st
from streamlit_echarts import st_echarts
import json # For PyEcharts conversion
# import pyecharts.options as opts # Optional: if using pyecharts
# from pyecharts.charts import Bar # Optional: if using pyecharts

st.set_page_config(layout='wide')
st.title('Streamlit ECharts Basic Bar Chart')

# ECharts option as a Python dictionary
options = {
    'xAxis': {
        'type': 'category',
        'data': ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
    },
    'yAxis': {
        'type': 'value'
    },
    'series': [{
        'data': [820, 932, 901, 934, 1290, 1330, 1320],
        'type': 'bar'
    }]
}

st.header('Basic ECharts Bar Chart')
result = st_echarts(
    options=options,
    height='400px',
    key='basic_bar_chart', # Essential for stable animations/interactions
    on_select='rerun' # Example: trigger rerun on selection
)

if result and result.get('selection'):
    st.write(f"Selected data point: {result['selection']}")

# Example with PyEcharts (requires `pip install streamlit-echarts[pyecharts]`)
# if st.checkbox("Show PyEcharts Example (requires pyecharts extra)"):
#     b = (
#         Bar()
#         .add_xaxis(["Microsoft", "Amazon", "IBM", "Oracle", "Google"])
#         .add_yaxis("2018 Revenue (billion $)", [21.2, 20.4, 10.3, 6.08, 4])
#         .set_global_opts(
#             title_opts=opts.TitleOpts(title="Top Cloud Providers", subtitle="2018 Revenue")
#         )
#     )
#     st.header('PyEcharts Bar Chart (via st_pyecharts)')
#     st_pyecharts(b, height="400px", key='pyecharts_chart')

view raw JSON →