{"id":14959565,"url":"https://github.com/andfanilo/streamlit-echarts","last_synced_at":"2025-04-08T09:12:36.132Z","repository":{"id":40671588,"uuid":"261247404","full_name":"andfanilo/streamlit-echarts","owner":"andfanilo","description":"A Streamlit component to render ECharts.","archived":false,"fork":false,"pushed_at":"2023-03-07T06:25:08.000Z","size":5405,"stargazers_count":569,"open_issues_count":32,"forks_count":66,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2025-04-01T08:34:11.433Z","etag":null,"topics":["echarts","pyecharts","streamlit"],"latest_commit_sha":null,"homepage":"https://share.streamlit.io/andfanilo/streamlit-echarts-demo/master/app.py","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andfanilo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-04T17:10:16.000Z","updated_at":"2025-03-30T18:54:51.000Z","dependencies_parsed_at":"2024-06-18T15:33:24.648Z","dependency_job_id":"83fdd1c1-a8aa-4052-bc41-a853dcc5bb8d","html_url":"https://github.com/andfanilo/streamlit-echarts","commit_stats":{"total_commits":72,"total_committers":8,"mean_commits":9.0,"dds":0.25,"last_synced_commit":"a9410f38e013569c639b9e5f1d444769fd3b7de2"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andfanilo%2Fstreamlit-echarts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andfanilo%2Fstreamlit-echarts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andfanilo%2Fstreamlit-echarts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andfanilo%2Fstreamlit-echarts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andfanilo","download_url":"https://codeload.github.com/andfanilo/streamlit-echarts/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809964,"owners_count":20999816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["echarts","pyecharts","streamlit"],"created_at":"2024-09-24T13:20:01.025Z","updated_at":"2025-04-08T09:12:36.098Z","avatar_url":"https://github.com/andfanilo.png","language":"Python","funding_links":["https://www.buymeacoffee.com/andfanilo"],"categories":[],"sub_categories":[],"readme":"# Streamlit - ECharts\n\n[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://share.streamlit.io/andfanilo/streamlit-echarts-demo/master/app.py)\n\nA Streamlit component to display [ECharts](https://echarts.apache.org/en/index.html).\n\n![](./img/demo.gif)\n\n## Install\n\n```shell script\npip install streamlit-echarts\n```\n\n## Usage\n\nThis library provides 2 functions to display echarts :\n\n- `st_echarts` to display charts from ECharts json options as Python dicts\n- `st_pyecharts` to display charts from Pyecharts instances\n\nCheck out the [demo](https://share.streamlit.io/andfanilo/streamlit-echarts-demo/master/app.py) and [source code](https://github.com/andfanilo/streamlit-echarts-demo) for more examples.\n\n**st_echarts example**\n\n```python\nfrom streamlit_echarts import st_echarts\n\noptions = {\n    \"xAxis\": {\n        \"type\": \"category\",\n        \"data\": [\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\", \"Sun\"],\n    },\n    \"yAxis\": {\"type\": \"value\"},\n    \"series\": [\n        {\"data\": [820, 932, 901, 934, 1290, 1330, 1320], \"type\": \"line\"}\n    ],\n}\nst_echarts(options=options)\n```\n\n**st_pyecharts example**\n\n```python\nfrom pyecharts import options as opts\nfrom pyecharts.charts import Bar\nfrom streamlit_echarts import st_pyecharts\n\nb = (\n    Bar()\n    .add_xaxis([\"Microsoft\", \"Amazon\", \"IBM\", \"Oracle\", \"Google\", \"Alibaba\"])\n    .add_yaxis(\n        \"2017-2018 Revenue in (billion $)\", [21.2, 20.4, 10.3, 6.08, 4, 2.2]\n    )\n    .set_global_opts(\n        title_opts=opts.TitleOpts(\n            title=\"Top cloud providers 2018\", subtitle=\"2017-2018 Revenue\"\n        ),\n        toolbox_opts=opts.ToolboxOpts(),\n    )\n)\nst_pyecharts(b)\n```\n\n## API\n\n### st_echarts API\n\n```\nst_echarts(\n    options: Dict\n    theme: Union[str, Dict]\n    events: Dict[str, str]\n    height: str\n    width: str\n    renderer: str\n    map: Map\n    key: str\n)\n```\n\n- **options** : Python dictionary that resembles the JSON counterpart of\n  [echarts options](https://echarts.apache.org/en/tutorial.html#ECharts%20Basic%20Concepts%20Overview).\n  For example the basic line chart in JS :\n\n```javascript\n// JS code\noption = {\n  xAxis: {\n    type: \"category\",\n    data: [\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\", \"Sun\"],\n  },\n  yAxis: { type: \"value\" },\n  series: [{ data: [820, 932, 901, 934, 1290, 1330, 1320], type: \"line\" }],\n};\n```\n\nis represented in Python :\n\n```python\n# Python code\noption = {\n    \"xAxis\": {\n        \"type\": \"category\",\n        \"data\": [\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\", \"Sun\"],\n    },\n    \"yAxis\": { \"type\": \"value\" },\n    \"series\": [\n        {\"data\": [820, 932, 901, 934, 1290, 1330, 1320], \"type\": \"line\" }\n    ],\n}\n```\n\n- **theme** : [echarts theme](https://echarts.apache.org/en/tutorial.html#Overview%20of%20Style%20Customization).\n  You can specify built-int themes or pass over style configuration as a Python dict.\n- **events** : Python dictionary which maps an [event](https://echarts.apache.org/en/tutorial.html#Events%20and%20Actions%20in%20ECharts) to a Js function as string.\n  For example :\n\n```python\n{\n    \"click\": \"function(params) { console.log(params.name) }\"\n}\n```\n\nwill get mapped to :\n\n```javascript\nmyChart.on(\"click\", function (params) {\n  console.log(params.name);\n});\n```\n\nReturn values from events are sent back to Python, for example:\n\n```python\noption = {\n    \"xAxis\": {\n        \"type\": \"category\",\n        \"data\": [\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\", \"Sun\"],\n    },\n    \"yAxis\": { \"type\": \"value\" },\n    \"series\": [\n        {\"data\": [820, 932, 901, 934, 1290, 1330, 1320], \"type\": \"line\" }\n    ],\n}\nevents = {\n    \"click\": \"function(params) { console.log(params.name); return params.name }\",\n    \"dblclick\":\"function(params) { return [params.type, params.name, params.value] }\"\n}\nvalue = st_echarts(option, events=events)\nst.write(value)  # shows name on bar click and type+name+value on bar double click\n```\n\nThe JS code needs to be a one-liner. You can use Javascript minifiers like https://javascript-minifier.com/ or https://www.minifier.org/ to transform your Javascript code to a one-liner.\n\n- **height** / **width** : size of the div wrapper\n- **map** : register a map using the dedicated `Map` class\n\n```python\nfrom streamlit_echarts import Map\nwith open(\"USA.json\", \"r\") as f:\n    map = Map(\n        \"USA\",\n        json.loads(f.read()),\n        {\n            \"Alaska\": {\"left\": -131, \"top\": 25, \"width\": 15},\n            \"Hawaii\": {\"left\": -110, \"top\": 28, \"width\": 5},\n            \"Puerto Rico\": {\"left\": -76, \"top\": 26, \"width\": 2},\n        },\n    )\noptions = {...}\nst_echarts(options, map=map)\n```\n\nYou'll find a lot of GeoJSON data inside the [source code of echarts-countries-js](https://github.com/echarts-maps/echarts-countries-js/tree/master/echarts-countries-js).\n\n- **renderer** : SVG or canvas\n- **key** : assign a fixed identity if you want to change its arguments over time and not have it be re-created.\n\n### st_pyecharts API\n\n```python\ndef st_pyecharts(\n    chart: Base\n    theme: Union[str, Dict]\n    events: Dict[str, str]\n    height: str\n    width: str\n    renderer: str\n    map: Map\n    key: str\n)\n```\n\n- **chart** : Pyecharts instance\n\nThe docs for the remaining inputs are the same as its `st_echarts` counterpart.\n\n## Development\n\n### Install\n\n- JS side\n\n```shell script\ncd frontend\nnpm install\n```\n\n- Python side\n\n```shell script\nconda create -n streamlit-echarts python=3.7\nconda activate streamlit-echarts\npip install -e .\n```\n\n### Run\n\nBoth webpack dev server and Streamlit need to run for development mode.\n\n- JS side\n\n```shell script\ncd frontend\nnpm run start\n```\n\n- Python side\n\nDemo example is on https://github.com/andfanilo/streamlit-echarts-demo.\n\n```shell script\ngit clone https://github.com/andfanilo/streamlit-echarts-demo\ncd streamlit-echarts-demo/\nstreamlit run app.py\n```\n\n## Caveats\n\n### Theme definition\n\n- Defining the theme in Pyecharts when instantiating chart like `Bar(init_opts=opts.InitOpts(theme=ThemeType.LIGHT))`\n  does not work, you need to call theme in `st_pyecharts(c, theme=ThemeType.LIGHT)`.\n\n### On Javascript functions\n\nThis library also provides the `JsCode` util class directly from `pyecharts`.\n\nThis class is used to indicate javascript code by wrapping it with a specific placeholder.\nOn the custom component side, we parse every value in options looking for this specific placeholder\nto determine whether a value is a JS function.\n\nAs such, if you want to pass JS functions as strings in your options,\nyou should use the corresponding `JsCode` module to wrap code with this placeholder :\n\n- In Python dicts representing the JSON option counterpart,\n  wrap any JS string function with `streamlit_echarts.JsCode` by calling `JsCode(function).js_code`.\n  It's a smaller version of `pyecharts.commons.utils.JsCode` so you don't need to install `pyecharts` to use it.\n\n```\nseries: [\n    {\n        type: 'scatter', // this is scatter chart\n        itemStyle: {\n            opacity: 0.8\n        },\n        symbolSize: JsCode(\"function (val) { return val[2] * 40;}\").js_code,\n        data: [[\"14.616\",\"7.241\",\"0.896\"],[\"3.958\",\"5.701\",\"0.955\"],[\"2.768\",\"8.971\",\"0.669\"],[\"9.051\",\"9.710\",\"0.171\"],[\"14.046\",\"4.182\",\"0.536\"],[\"12.295\",\"1.429\",\"0.962\"],[\"4.417\",\"8.167\",\"0.113\"],[\"0.492\",\"4.771\",\"0.785\"],[\"7.632\",\"2.605\",\"0.645\"],[\"14.242\",\"5.042\",\"0.368\"]]\n    }\n]\n```\n\n- In Pyecharts, use `pyecharts.commons.utils.JsCode` directly, JsCode automatically calls `.js_code` when dumping options.\n\n```\n.set_series_opts(\n        label_opts=opts.LabelOpts(\n            position=\"right\",\n            formatter=JsCode(\n                \"function(x){return Number(x.data.percent * 100).toFixed() + '%';}\"\n            ),\n        )\n    )\n```\n\n**Note**: you need the JS string to be on one-line. You can use Javascript minifiers like https://javascript-minifier.com/ or https://www.minifier.org/ to transform your Javascript code to a one-liner.\n\n### st_pyecharts VS using pyecharts with components.html\n\nWhile this package provides a `st_pyecharts` method, if you're using `pyecharts` you can directly embed your pyecharts visualization inside `st.html`\nby passing the output of the chart's `.render_embed()`.\n\n```python\nfrom pyecharts.charts import Bar\nfrom pyecharts import options as opts\nimport streamlit.components.v1 as components\n\nc = (Bar()\n    .add_xaxis([\"Microsoft\", \"Amazon\", \"IBM\", \"Oracle\", \"Google\", \"Alibaba\"])\n    .add_yaxis('2017-2018 Revenue in (billion $)', [21.2, 20.4, 10.3, 6.08, 4, 2.2])\n    .set_global_opts(title_opts=opts.TitleOpts(title=\"Top cloud providers 2018\", subtitle=\"2017-2018 Revenue\"),\n                     toolbox_opts=opts.ToolboxOpts())\n    .render_embed() # generate a local HTML file\n)\ncomponents.html(c, width=1000, height=1000)\n```\n\nUsing `st_pyecharts` is still something you would want if you need to change data regularly\nwithout remounting the component, check for examples `examples/app_pyecharts.py` for `Chart with randomization` example.\n\n![](./img/randomize.gif)\n\n## Credits\n\n- It's really a wrapper around [echarts-for-react](https://github.com/hustcc/echarts-for-react).\n\n# Support me\n\n\u003ca href=\"https://www.buymeacoffee.com/andfanilo\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"41\" width=\"174\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandfanilo%2Fstreamlit-echarts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandfanilo%2Fstreamlit-echarts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandfanilo%2Fstreamlit-echarts/lists"}