{"id":8688,"library":"streamlit-echarts","title":"Streamlit ECharts","description":"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.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/andfanilo/streamlit-echarts","tags":["streamlit","echarts","data visualization","component","charts"],"install":[{"cmd":"pip install streamlit-echarts","lang":"bash","label":"Core library"},{"cmd":"pip install streamlit-echarts[pyecharts]","lang":"bash","label":"With PyECharts support"}],"dependencies":[{"reason":"Core dependency for Streamlit components.","package":"streamlit"},{"reason":"Optional dependency for using st_pyecharts wrapper. Must be installed separately after v0.5.0.","package":"pyecharts","optional":true},{"reason":"Optional dependency, no longer directly required by the package after v0.5.0. PyECharts might still use it.","package":"simplejson","optional":true}],"imports":[{"symbol":"st_echarts","correct":"from streamlit_echarts import st_echarts"},{"note":"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`.","wrong":"from streamlit_echarts import st_pyecharts # without [pyecharts] extra","symbol":"st_pyecharts","correct":"from streamlit_echarts import st_pyecharts"},{"symbol":"JsCode","correct":"from streamlit_echarts import JsCode"}],"quickstart":{"code":"import streamlit as st\nfrom streamlit_echarts import st_echarts\nimport json # For PyEcharts conversion\n# import pyecharts.options as opts # Optional: if using pyecharts\n# from pyecharts.charts import Bar # Optional: if using pyecharts\n\nst.set_page_config(layout='wide')\nst.title('Streamlit ECharts Basic Bar Chart')\n\n# ECharts option as a Python dictionary\noptions = {\n    'xAxis': {\n        'type': 'category',\n        'data': ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']\n    },\n    'yAxis': {\n        'type': 'value'\n    },\n    'series': [{\n        'data': [820, 932, 901, 934, 1290, 1330, 1320],\n        'type': 'bar'\n    }]\n}\n\nst.header('Basic ECharts Bar Chart')\nresult = st_echarts(\n    options=options,\n    height='400px',\n    key='basic_bar_chart', # Essential for stable animations/interactions\n    on_select='rerun' # Example: trigger rerun on selection\n)\n\nif result and result.get('selection'):\n    st.write(f\"Selected data point: {result['selection']}\")\n\n# Example with PyEcharts (requires `pip install streamlit-echarts[pyecharts]`)\n# if st.checkbox(\"Show PyEcharts Example (requires pyecharts extra)\"):\n#     b = (\n#         Bar()\n#         .add_xaxis([\"Microsoft\", \"Amazon\", \"IBM\", \"Oracle\", \"Google\"])\n#         .add_yaxis(\"2018 Revenue (billion $)\", [21.2, 20.4, 10.3, 6.08, 4])\n#         .set_global_opts(\n#             title_opts=opts.TitleOpts(title=\"Top Cloud Providers\", subtitle=\"2018 Revenue\")\n#         )\n#     )\n#     st.header('PyEcharts Bar Chart (via st_pyecharts)')\n#     st_pyecharts(b, height=\"400px\", key='pyecharts_chart')\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 0.5.0 migrated to Streamlit Components v2 API, which might require adjustments in advanced component interactions or custom event handling.","severity":"breaking","affected_versions":">=0.5.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"If you rely on `pyecharts` or `simplejson`, install them explicitly: `pip install pyecharts simplejson` (or `pip install streamlit-echarts[pyecharts]` for the wrapper).","message":"`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.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"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`.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"Charts may exhibit flickering or unexpected re-rendering behavior when their options or data are dynamically updated without a stable component identity.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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`.","error":"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)"},{"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`.","cause":"The `st_pyecharts` function is not imported or the optional `pyecharts` extra for `streamlit-echarts` is not installed.","error":"NameError: name 'st_pyecharts' is not defined"},{"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.","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.","error":"Charts inside st.tabs are not displayed or appear blank after switching tabs."},{"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.","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.","error":"ECharts plot flickers or reruns animations when data or options change."}]}