# st.echarts_chart

Source: https://docs.streamlit.io/develop/api-reference/charts/st.echarts_chart

* Function signature:

   ```python
   st.echarts_chart(spec, *, width="stretch", height="content", theme="streamlit", key=None, on_select="ignore", renderer="canvas", alt=None)
   ```

* Parameters:

   | name | type | default | description |
   |---|---|---|---|
   | spec | dict, str, or pyecharts chart |  | The ECharts option object to render. This can be one of the following:  A Python dict matching the ECharts option object structure. A JSON str (handy for copy-pasting an option from the ECharts examples gallery). A pyecharts chart instance, which is detected through duck typing (the presence of a dump_options method) and converted automatically. pyecharts is not a Streamlit dependency.  Put chart data in dataset.source as a dataframe-like object (pandas, Polars, PyArrow, and others) rather than as lists in series.data or xAxis.data. Always do this for more than about 1,000 rows. Graph, sankey, tree, treemap, sunburst, and other series that don't read dataset take their data in series.data instead. A dataframe source has these advantages:  Performance: Streamlit sends the dataframe to the browser as Arrow, which is smaller and faster than inline values. Value types: Datetimes become ISO-8601 strings (in UTC if timezone-aware), durations become milliseconds, and missing values become null. Other non-numeric values use the text st.dataframe shows. Values elsewhere in the option, such as series.data, must already be JSON-compatible, so datetimes, NumPy integers, and NaN in them raise an error. Show data: The chart's hover toolbar has a Show data button that displays the dataframe as a table.  Streamlit keeps the dataframe's column order through dataset.dimensions when you haven't set it. The dataframe index isn't included, so use df.reset_index() to plot it. On a category axis, ECharts reads numbers as 0-based category positions, so a marker at {"xAxis": 2023} doesn't mark the 2023 category. Pass the label as a string, and cast numeric category columns, such as years, with .astype(str). |
   | width | "stretch", "content", or int | of | The width of the chart element. This can be one of the following:  "stretch" (default): The width of the element matches the width of the parent container. "content": The width of the element matches the width of its content, but doesn't exceed the width of the parent container. Because an ECharts spec has no intrinsic width, this is a fixed default of 700 pixels, unless a pyecharts chart sets its own width through InitOpts (pyecharts' library default is ignored, and "100%" is treated as "stretch"). An integer specifying the width in pixels: The element has a fixed width. If the specified width is greater than the width of the parent container, the width of the element matches the width of the parent container. |
   | height | "content", "stretch", or int | of | The height of the chart element. This can be one of the following:  "content" (default): The height of the element matches the height of its content. Because an ECharts spec has no intrinsic height, this is a fixed default of 350 pixels — matching st.line_chart and the other Vega-based charts — unless a pyecharts chart sets its own height through InitOpts (pyecharts' library default is ignored, and "100%" is treated as "stretch"). "stretch": The height of the element matches the height of its content or the height of the parent container, whichever is larger. If the element is not in a parent container, the height of the element matches the height of its content. An integer specifying the height in pixels: The element has a fixed height. |
   | theme | "streamlit" or None | theme | The theme of the chart. If theme is "streamlit" (default), Streamlit applies its own colors, fonts, and plot layout. If theme is None, Streamlit leaves your spec's styling untouched and uses ECharts' built-in default theme. Two defaults still apply: aria.enabled stays on unless you set aria, so the chart keeps a screen-reader description, and a display-only chart (on_select="ignore") with no series.cursor gets the "default" cursor so it doesn't look clickable. The "streamlit" theme can be partially customized through the configuration options theme.chartCategoricalColors and theme.chartSequentialColors. Font configuration options are also applied, and long tooltip numbers are shortened unless you set tooltip.valueFormatter or tooltip.formatter (see the tooltip note above). Time, value, and log axes hide tick labels that would overlap. To show every label on an axis, add "hideOverlap": False to its axisLabel. On a time xAxis or yAxis, the axis tooltip header and axis pointer label show a midnight value as a date (for example 2026-08-18) and any other value as a date and time to the second, so an hourly point at midnight shows only its date. An axisPointer.label.formatter replaces this, whether it's set on the axis, tooltip, grid.tooltip, the top-level axisPointer, a timeline tick, or a media override. "{value}" restores ECharts' default label. Tooltip values show the datetimes of a dataframe source the same way, in the browser's local time even with "useUTC": True, so a tooltip datetime can differ from its axis label. |
   | key | str, int, or None |  | An optional key that gives this element a stable identity. If this is None (default) and the chart is display-only, identity follows its position in the app, so moving it can reset the chart and replay its entry animation. If this is None and selections are activated, identity also includes the chart's parameters, so a change to the spec, theme, renderer, size, or alt resets the selection. If selections are activated and key is provided, Streamlit will register the key in Session State to store the selection state, and the selection survives changes to your spec, theme, and renderer. Indices are not revalidated against the new data, so check them before indexing. The selection state is read-only. For more details, see Widget behavior. If key is provided, it will be used as a CSS class name prefixed with st-key-, and the chart keeps its identity across reruns even when the spec, theme, or renderer changes. |
   | on_select | "ignore", "rerun", or callable |  | How the chart should respond to user selection events. This controls whether or not the chart behaves like an input widget. on_select can be one of the following:  "ignore" (default): Streamlit will not react to any selection events in the chart. The chart will not behave like an input widget. "rerun": Streamlit will rerun the app when the user selects data in the chart. In this case, st.echarts_chart will return the selection data as a dictionary. A callable: Streamlit will rerun the app and execute the callable as a callback function before the rest of the app. In this case, st.echarts_chart will return the selection data as a dictionary.  When on_select is not "ignore", Streamlit returns whatever selections you enable in your spec. Enable point selection by setting selectedMode on a series (for example, {"type": "bar", "selectedMode": "multiple", "data": [...]}), and enable region selection by adding a brush component or toolbox.feature.brush. Target an axis on the brush (for example, "brush": {"xAxisIndex": "all"}) so its regions are reported in areas and survive resizes. A brush without an axis, grid, or geo target only has pixel geometry, so its regions are omitted from areas and dropped when the chart resizes. Selected data is grouped by series in EChartsState.selection.selected, and brush geometry is returned in EChartsState.selection.areas. Selections are re-applied visually after reruns. Double-click the chart to clear both point and brush selections. If your spec enables neither, the chart still renders but never returns a selection, and Streamlit logs a warning. |
   | renderer | "canvas" or "svg" |  | The renderer passed to ECharts. This can be one of the following:  "canvas" (default): Best for large datasets. "svg": Produces real DOM nodes that are better for printing, sharp scaling, and accessibility. |
   | alt | str or None |  | A description of the chart for screen readers and other assistive technologies. Streamlit maps this to ECharts' aria.label.description, which becomes the chart's accessible name. If this is None (default), ECharts keeps its generated data-derived name when aria.enabled is on. An empty or whitespace-only string is treated the same as None and is logged so authors notice the dual meaning of alt="" across commands (decorative only on st.image / st.pyplot). When both alt and an author aria.label.description are set, alt overrides that description for the accessible name. A non-empty alt also keeps the chart named even if the option sets aria.enabled to False. Because ECharts already generates a data-derived name, prefer a short, specific description; a vague one can be worse than none. This is a short description of the chart, not a full text alternative for dense graphics. |

* Returns: element or EChartsState

    If on_select is "ignore" (default), this command returns an
internal placeholder for the chart element. Otherwise, this command
returns an EChartsState object. This object is dictionary-like
and supports both key and attribute notation. To use this type in
an annotation, import it from streamlit.typing.

## Chart selections

* Function signature:

   ```python
   EChartsState
   ```

* Parameters:

   | name | type | default | description |
   |---|---|---|---|
   | selection | dict |  | The state of the on_select event. This attribute returns a dictionary-like object that supports both key and attribute notation. The attributes are described by the EChartsSelectionState dictionary schema. |

* Function signature:

   ```python
   EChartsSelectionState
   ```

* Parameters:

   | name | type | default | description |
   |---|---|---|---|
   | selected | list[dict[str, Any]] |  | The union of native and brushed selections, grouped by ECharts series and data type. Each entry contains series_index, series_id, series_name, data_type, and data_indices. Series IDs and names are None when they weren't explicitly configured. data_type is "main" (used when ECharts omits dataType), "node", or "edge". data_indices is sorted and series-local. For a dataset without transforms, it addresses dataset.source rows. For inline series, it addresses series.data. For graph series, data_type="node" addresses data and data_type="edge" addresses links. |
   | areas | list[dict[str, Any]] |  | The active brush regions. Each entry contains brush_index, brush_type, and coord_range. brush_type is ECharts' "rect", "lineX", "lineY", or "polygon". The shape of coord_range depends on that type: "rect" uses [[x0, x1], [y0, y1]]; "lineX" and "lineY" use [start, end]; "polygon" uses [[x, y], ...]. Category-axis coordinates are ordinal positions and can include half-indices such as [0.5, 3.5]. Regions that ECharts only describes in pixel space are omitted, since their geometry can't be mapped back to your data. |
