streamlit-echarts 0.7.0

A Streamlit component to display ECharts.

Streamlit - ECharts

A Streamlit component to display ECharts.

---

Requirements

• Python >= 3.10

Installation instructions

uv pip install streamlit-echarts

To also use PyECharts charts with st_pyecharts:

uv pip install streamlit-echarts[pyecharts]

Usage instructions

import streamlit as st
from streamlit_echarts import st_echarts

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_echarts(options=options, height="400px")

API Reference

st_echarts(options, ...)

Parameter	Type	Default	Description
options	dict	required	ECharts option object
theme	str | dict	""	"streamlit", "dark", or a custom theme dict
events	dict[str, str | Path]	None	Map of ECharts event names to JS handler strings (or paths to a .js file). Handlers run with chart and echarts in scope; prefix a name with zr: to listen across the whole canvas, including blank areas. A handler's return value surfaces in Python as result.chart_event; returning undefined skips the rerun.
height	str	"300px"	Any valid CSS height (e.g. "500px", "50vh")
width	str	"100%"	Any valid CSS width (e.g. "100%", "600px")
renderer	"canvas" | "svg"	"canvas"	ECharts renderer; "svg" is better for print/accessibility
map	Map | None	None	GeoJSON map to register, created via Map(map_name=..., geo_json=...)
key	str | None	None	Stable widget key; prevents remount and animation replay on rerun
on_change	callable | None	None	Python callback invoked when the component fires a chart event
on_select	"ignore" | "rerun" | callable	"ignore"	Selection behavior: "rerun" triggers a Streamlit rerun; a callable is invoked on selection change
selection_mode	str | tuple[str]	("points","box","lasso")	Which interactions to enable: "points" (click), "box" (rect brush), "lasso" (polygon brush)

For advanced events and JsCode handler examples — chart-scope helpers, the zr: prefix, and loading handlers from a file — see the live demo app.

st_pyecharts(chart, ...)

Convenience wrapper that converts a PyECharts chart instance to a dict and calls st_echarts. Requires pip install streamlit-echarts[pyecharts]. Accepts the same parameters as st_echarts (replacing options with chart).

JsCode(js_string_or_path)

Wraps a JavaScript string so the frontend evaluates it as a live function rather than a plain string. Use wherever ECharts expects a callback (formatters, symbol sizes, color functions, …). Also accepts a pathlib.Path (or a single-line .js/.mjs path string) to load the function from a local file — handy for longer callbacks you want to lint, format, and test as real JavaScript.

from pathlib import Path

JsCode("function(params){ return params.value * 2 }")
JsCode(Path("callbacks/label_formatter.js"))  # file holds one function expression

Map(map_name, geo_json, special_areas=None)

Registers a GeoJSON map with ECharts. Pass the returned object to st_echarts(map=...) and reference map_name in a geo or map series.

---

Selection / Interactions

Use on_select to enable structured selection events, similar to st.plotly_chart:

result = st_echarts(options=options, on_select="rerun", selection_mode="points", key="my_chart")

selected = result["selection"]
if selected["point_indices"]:
    st.write("Selected indices:", selected["point_indices"])

selection_mode accepts "points" (click), "box" (rect brush), "lasso" (polygon brush), or a tuple of multiple modes. See the demo app for more examples.

Using with PyECharts

Install the optional pyecharts extra:

uv pip install streamlit-echarts[pyecharts]

Then use st_pyecharts to render PyECharts chart instances directly:

import streamlit as st
from pyecharts import options as opts
from pyecharts.charts import Bar
from streamlit_echarts import st_pyecharts

b = (
    Bar()
    .add_xaxis(["Microsoft", "Amazon", "IBM", "Oracle", "Google", "Alibaba"])
    .add_yaxis(
        "2017-2018 Revenue in (billion $)", [21.2, 20.4, 10.3, 6.08, 4, 2.2]
    )
    .set_global_opts(
        title_opts=opts.TitleOpts(
            title="Top cloud providers 2018", subtitle="2017-2018 Revenue"
        )
    )
)

st_pyecharts(b, height="500px")

st_pyecharts accepts the same parameters as st_echarts (theme, events, on_select, etc.). Under the hood it calls chart.dump_options() and passes the result to st_echarts.

Alternatively, you can convert PyECharts options manually without installing the extra:

import json
from streamlit_echarts import st_echarts

st_echarts(options=json.loads(b.dump_options()), height="500px")

Demo Application

A comprehensive demo application containing dozens of ECharts and PyECharts examples is available in the root of the repository. You can use it as an integration test to verify the component's functionality:

Note: You will need extra dependencies installed to run all examples in the demo:

uv pip install pyecharts pandas faker
uv run streamlit run demo_app.py

---

Project status

This project is in best-effort status — I occasionally add features I personally need through agentic coding, but I'm not actively reviewing larger issues or pull requests from the community. If you're looking to add a bigger feature, you're welcome to fork it!

Please add a thumbs up HERE if you wish to see a native implementation maintained by the Streamlit team.

Contributing

See CONTRIBUTING.md for development setup, testing, building, and publishing.