{"id":16803202,"url":"https://github.com/trungleduc/ipecharts","last_synced_at":"2026-03-15T05:34:53.534Z","repository":{"id":199353640,"uuid":"702701743","full_name":"trungleduc/ipecharts","owner":"trungleduc","description":"Echarts Jupyter Widget","archived":false,"fork":false,"pushed_at":"2025-03-15T11:07:37.000Z","size":9061,"stargazers_count":29,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-11T00:42:20.408Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://trungleduc.github.io/ipecharts/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trungleduc.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":"2023-10-09T20:42:23.000Z","updated_at":"2025-04-09T04:21:33.000Z","dependencies_parsed_at":"2024-05-29T01:36:08.425Z","dependency_job_id":null,"html_url":"https://github.com/trungleduc/ipecharts","commit_stats":null,"previous_names":["trungleduc/ipecharts"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trungleduc%2Fipecharts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trungleduc%2Fipecharts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trungleduc%2Fipecharts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trungleduc%2Fipecharts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trungleduc","download_url":"https://codeload.github.com/trungleduc/ipecharts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322602,"owners_count":21084336,"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":[],"created_at":"2024-10-13T09:41:49.677Z","updated_at":"2026-03-15T05:34:53.529Z","avatar_url":"https://github.com/trungleduc.png","language":"Python","funding_links":[],"categories":["Languages"],"sub_categories":["Python"],"readme":"\u003ch1 align=\"center\"\u003eipecharts\u003c/h1\u003e\n\n[![Github Actions Status](https://github.com/trungleduc/ipecharts/workflows/Build/badge.svg)](https://github.com/trungleduc/ipecharts/actions/workflows/build.yml)\n[![Documentation Status](https://readthedocs.org/projects/ipecharts/badge/?version=latest)](https://ipecharts.readthedocs.io/en/latest/?badge=latest)\n[![Try on lite](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://trungleduc.github.io/ipecharts/)\n\n\u003ch2 align=\"center\"\u003e Apache Echarts Jupyter Widget \u003c/h2\u003e\n\n`ipecharts` brings interactive widgets based on [Apache ECharts](https://echarts.apache.org/en/index.html) charting library to the Jupyter ecosystem. By using the Jupyter Widget protocol, `ipecharts` is fully compatible with other widget libraries and tools in the Jupyter ecosystem.\n\nhttps://github.com/trungleduc/ipecharts/assets/4451292/c6e73b4d-61ef-4098-a274-92233d0801b0\n\n\u003e [!NOTE]  \n\u003e [`pyecharts`](https://pyecharts.org) also supports using Echarts in the notebook, but they are not using Jupyter Widget like `ipecharts`. In this library, HTML code is injected into the notebook to render the chart.\n\n## Try it online!\n\nYou can try it online by clicking on this badge:\n\n[![Try on lite](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://trungleduc.github.io/ipecharts/)\n\n## Documentation\n\nYou can read the documentation following this link: https://ipecharts.readthedocs.io/\n\n## Installation\n\nTo install the extension, execute:\n\n```bash\npip install ipecharts\n```\n\nor with conda:\n\n```bash\nconda install -c conda-forge  ipecharts\n```\n\n## Usage\n\n`ipecharts` widgets are generated automatically from `ECharts 5.5.0`. It provides two high-level widgets to create charts in notebooks: `EChartsRawWidget` and `EChartsWidget`.\n\n### Create charts using `EChartsRawWidget`\n\n`EChartsRawWidget` is a simple widget to render `ECharts` option dictionary. It is fully compatible with the JavaScript version of `ECharts`. Here is an example of converting the [following JS example](https://echarts.apache.org/examples/en/editor.html?c=area-basic):\n\n```javascript\nimport * as echarts from 'echarts';\n\nvar chartDom = document.getElementById('main');\nvar myChart = echarts.init(chartDom);\nvar option;\n\noption = {\n  xAxis: {\n    type: 'category',\n    boundaryGap: false,\n    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']\n  },\n  yAxis: {\n    type: 'value'\n  },\n  series: [\n    {\n      data: [820, 932, 901, 934, 1290, 1330, 1320],\n      type: 'line',\n      areaStyle: {}\n    }\n  ]\n};\n\noption \u0026\u0026 myChart.setOption(option);\n```\n\ninto using `EChartsRawWidget`:\n\n```python\nfrom ipecharts import EChartsRawWidget\n\noption = {\n  'xAxis': {\n    'type': 'category',\n    'boundaryGap': False,\n    'data': ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']\n  },\n  'yAxis': {\n    'type': 'value'\n  },\n  'series': [\n    {\n      'data': [820, 932, 901, 934, 1290, 1330, 1320],\n      'type': 'line',\n      'areaStyle': {}\n    }\n  ]\n}\n\nEChartsRawWidget(option=option)\n```\n\n![EChartsRawWidget](./docs/source/images/EChartsRawWidget.jpg)\n\n### Create charts using `EChartsWidget`\n\nWhile the raw widget can render the charts correctly, it lacks the interactivity of a Jupyter widget. `ipecharts` provides `EChartsWidget` and configuration classes for nearly all available options of ECharts to correct this issue.\n\nHere is the equivalent of the above chart but using `EChartsWidget`:\n\n```python\nfrom ipecharts import EChartsWidget\nfrom ipecharts.option import Option, XAxis, YAxis\nfrom ipecharts.option.series import Line\n\nline = Line(data=[820, 932, 901, 934, 1290, 1330, 1320], areaStyle={})\noption = Option(\n    xAxis=XAxis(\n        type=\"category\",\n        boundaryGap=False,\n        data=[\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\", \"Sun\"],\n    ),\n    yAxis=YAxis(type=\"value\"),\n    series=[line],\n)\nEChartsWidget(option=option)\n```\n\nWhile it looks more verbose, the advantage is the reactivity. We can update the line data and have the chart updated automatically.\n\n![ipechart](./docs/source/images/ipechart.gif)\n\n### Configure `EChartsWidget` with `traitlets`\n\nEach key in the [option dictionary](https://echarts.apache.org/en/option.html#title) of ECharts has an equivalent configuration class with the same name. These classes contain traits with the same name as the corresponding ECharts option. Any change to these traits will be propagated to the top-level widget, and the chart will be updated automatically.\n\nFor instance, you can compare the scatter option of ECharts at https://echarts.apache.org/en/option.html#series-scatter.type and the equivalent Scatter class in the [ipecharts documentation](https://ipecharts.readthedocs.io/en/latest/api/ipecharts.option.seriesitems.html#module-ipecharts.option.seriesitems.scatter). The Python class is generated automatically from the ECharts option.\n\nBy using Traitlets to configure your widget, you can use EChartsWidget with other widgets in the Jupyter ecosystem. Here is an example of controlling the chart with an ipywidgets Button:\n\n```python\nfrom ipecharts.option import Option, XAxis, YAxis\nfrom ipecharts.option.series import Line\nfrom ipywidgets.widgets import Button\n\nline = Line(smooth=True, areaStyle={}, data=numpy.random.rand(10).tolist())\noption = Option(\n    xAxis=XAxis(type=\"category\"),\n    yAxis=YAxis(type=\"value\"),\n    series=[line],\n)\nchart = EChartsWidget(option=option)\n\nbutton = Button(description=\"Generate data\")\ndef on_button_clicked(b):\n    data = numpy.random.rand(10).tolist()\n    line.data = data\n\nbutton.on_click(on_button_clicked)\n\ndisplay(button, chart)\n```\n\n![ipechart2](./docs/source/images/ipechart3.gif)\n\n### Customize the chart initialization\n\nBoth `EChartsWidget` and `EChartsRawWidget` classes can customize the [Echarts init parameters](https://echarts.apache.org/en/api.html#echarts.init), for example:\n\n```python\n\nchart = EChartsWidget(\n    option=option, renderer=\"svg\", width=\"300px\", height=\"300px\", use_dirty_rect=True\n)\n\n```\n\nThe init parameters need to be converted to the snake case format.\n\n### Customize the chart container style\n\nBoth `EChartsWidget` and `EChartsRawWidget` classes allow you to customize the style of the chart container by setting the style attribute. The style attribute accepts a dictionary where keys are CSS property names in camelCase or kebab-case (as strings), and values are the corresponding CSS values.\n\nExample: 'backgroundColor': '#f0f0f0' or 'background-color': '#f0f0f0'\n\n```python\n\nfrom ipecharts import EChartsWidget\nfrom ipecharts.option import Option, XAxis, YAxis\nfrom ipecharts.option.series import Line\n\n# Define the data for the line series\nline = Line(\n    data=[820, 932, 901, 934, 1290, 1330, 1320],\n    areaStyle={}\n)\n\n# Create the option object with xAxis, yAxis, and series\noption = Option(\n    xAxis=XAxis(\n        type=\"category\",\n        boundaryGap=False,\n        data=[\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\", \"Sun\"]\n    ),\n    yAxis=YAxis(type=\"value\"),\n    series=[line]\n)\n\n# Define the style for the widget\nstyle = {\n    'width': '450px',\n    'height': '300px',\n    'border': '5px solid #ccc'\n}\n\n# Create the EChartsWidget with the option and style\nchart = EChartsWidget(option=option, style=style)\n\n# Display the chart\nchart\n```\n\nAfter the widget has been created and displayed, you can update its style by modifying the style attribute.\n\n```python\n\n# Update the style of the chart\nchart.style = {\n    'width': '800px',\n    'height': '600px',\n    'border': '2px solid #000'\n}\n\n# The widget will automatically update to reflect the new styles.\n\n```\n\nhttps://github.com/user-attachments/assets/e4245101-8dff-40a9-a4d4-1f75a06b88c4\n\n### Event handling\n\nEvent-handling functions can be added to `EChartsWidget` and `EChartsRawWidget` using the same syntax as [in the Javascript version](https://echarts.apache.org/handbook/en/concepts/event/):\n\n```python\nchart = EChartsWidget(option=option)\n\ndef callback(params):\n    print(params)\n\n# Add event handlers\nchart.on('click', None, callback) # Listen to all click event\nchart.on('click', 'series.line', callback) # Using string query\nchart.on('mouseover', {'seriesIndex': 1, 'name': 'xx'}, callback) # Using object query\n\n# Remove event handlers\nchart.off('click') # Remove all handler on click event\nchart.off('mouseover', callback) # Remove selected handler.\n```\n\n### Chart actions\n\nChart actions supported by ECharts can by triggered by the `EChartsWidget.dispatchAction` or `EChartsRawWidget.dispatchAction` method. This method takes the same payload as [in the Javascript version](https://echarts.apache.org/en/api.html#action):\n\n```python\nchart = EChartsWidget(option=option)\nchart.dispatchAction({\n    'type': 'highlight',\n    'seriesIndex': 0,\n    'dataIndex': 1\n  })\n```\n\n![ipechart](./docs/source/images/ipecharts_action.gif)\n\n### Using JS function in chart options\n\n`EChartsWidget` and `EChartsRawWidget` support passing JS functions to the chart options via the helper `ipecharts.tools.encode_js_fn`. For example, to use a JS function as the tooltip formatter, you can do the following:\n\n```python\nfrom ipecharts.tools import encode_js_fn\nfrom ipecharts.option import Tooltip\n\nformatter = encode_js_fn(['params'], \"return params.value[3] + ': ' + params.value[0];\")\ntooltip = Tooltip(trigger='item', formatter=formatter)\n```\n\nThe `encode_js_fn` function takes a list of parameter names and a string containing the JS function body. `ipecharts` will automatically generate the JS function for the chart options in the front-end.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrungleduc%2Fipecharts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrungleduc%2Fipecharts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrungleduc%2Fipecharts/lists"}