# st.plotly_chart

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

* Function signature:

   ```python
   st.plotly_chart(figure_or_data, use_container_width=None, *, width="stretch", height="content", theme="streamlit", key=None, on_select="ignore", selection_mode=('points', 'box', 'lasso'), config=None, alt=None)
   ```

* Parameters:

   | name | type | default | description |
   |---|---|---|---|
   | figure_or_data | plotly.graph_objs.Figure, plotly.graph_objs.Data,            or dict/list of plotly.graph_objs.Figure/Data |  | The Plotly Figure or Data object to render. See https://plot.ly/python/ for examples of graph descriptions.  Note Plotly Express line and scatter charts with more than 1,000 data points use a WebGL renderer by default (render_mode="auto"). Other figures render to SVG unless they use a WebGL trace type such as go.Scattergl. SVG creates one page element per point, so use WebGL for line and scatter charts with many thousands of points. Different browsers have different limits on the number of WebGL contexts per page. If you have many WebGL charts on a page, you may need to switch some of them to SVG. You can do this by setting render_mode="svg" within the figure. For example, the following code defines a Plotly Express line chart that will render in SVG mode when passed to st.plotly_chart: px.line(df, x="x", y="y", render_mode="svg"). |
   | width | "stretch", "content", or int |  | 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. 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 |  | 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. "stretch": The height of the element expands to fill the available vertical space in its parent container. When multiple elements with stretch height are in the same vertical container, they share the available vertical space evenly. Inside a container that already has a fixed height, the chart keeps no minimum height and can shrink to zero when the other elements fill the container. Use an integer height to keep the chart visible there. Otherwise, the chart uses its figure's layout.height, or 450 pixels when the figure does not set one, and still grows to match a taller sibling. An integer specifying the height in pixels: The element has a fixed height. If the content is larger than the specified height, scrolling is enabled. |
   | use_container_width | bool or None |  | Whether to override the figure's native width with the width of the parent container. This can be one of the following:  None (default): Streamlit will use the value of width. True: Streamlit sets the width of the figure to match the width of the parent container. False: Streamlit sets the width of the figure to fit its contents according to the plotting library, up to the width of the parent container. |
   | theme | "streamlit" or None | behavior | The theme of the chart. If theme is "streamlit" (default), Streamlit uses its own design default. If theme is None, Streamlit falls back to the default behavior of the library. The "streamlit" theme can be partially customized through the configuration options theme.chartCategoricalColors and theme.chartSequentialColors. Font configuration options are also applied. |
   | key | str, int, or None |  | An optional string to use for giving this element a stable identity. If this is None (default), the element's identity will be determined based on the values of the other parameters. If selections are activated and key is provided, Streamlit will register the key in Session State to store the selection state. The selection state is read-only. For more details, see Widget behavior. Additionally, if key is provided, it will be used as a CSS class name prefixed with st-key-. |
   | on_select | "ignore" or "rerun" or callable |  | How the figure should respond to user selection events. This controls whether or not the figure 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 figure 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.plotly_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.plotly_chart will return the selection data as a dictionary. |
   | selection_mode | "points", "box", "lasso" or an Iterable of these |  | The selection mode of the chart. This can be one of the following:  "points": The chart will allow selections based on individual data points. "box": The chart will allow selections based on rectangular areas. "lasso": The chart will allow selections based on freeform areas. An Iterable of the above options: The chart will allow selections based on the modes specified.  All selections modes are activated by default. |
   | config | dict or None |  | A dictionary of Plotly configuration options. This is passed to Plotly's show() function. For more information about Plotly configuration options, see Plotly's documentation on Configuration in Python. |
   | alt | str or None |  | A description of the chart for screen readers and other assistive technologies. If this is None (default), Streamlit does not provide an accessible name for the chart. 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). 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 PlotlyState

    If on_select is "ignore" (default), this command returns an
internal placeholder for the chart element. Otherwise, this command
returns a PlotlyState 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
   PlotlyState
   ```

* 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 PlotlySelectionState. |

* Function signature:

   ```python
   PlotlySelectionState
   ```

* Parameters:

   | name | type | default | description |
   |---|---|---|---|
   | points | list[dict[str, Any]] |  | The selected data points in the chart, including the data points selected by the box and lasso mode. The data includes the values associated to each point and a point index used to populate point_indices. If additional information has been assigned to your points, such as size or legend group, this is also included. |
   | point_indices | list[int] |  | The numerical indices of all selected data points in the chart. The details of each identified point are included in points. |
   | box | list[dict[str, Any]] |  | The metadata related to the box selection. This includes the coordinates of the selected area. |
   | lasso | list[dict[str, Any]] |  | The metadata related to the lasso selection. This includes the coordinates of the selected area. |

## Theming

Plotly charts are displayed using the Streamlit theme by default. This theme is sleek, user-friendly, and incorporates Streamlit's color palette. The added benefit is that your charts better integrate with the rest of your app's design.

The Streamlit theme is available from Streamlit 1.16.0 through the `theme="streamlit"` keyword argument. To disable it, and use Plotly's native theme, use `theme=None` instead.

Let's look at an example of charts with the Streamlit theme and the native Plotly theme:

```python
import plotly.express as px
import streamlit as st

df = px.data.gapminder()

fig = px.scatter(
    df.query("year==2007"),
    x="gdpPercap",
    y="lifeExp",
    size="pop",
    color="continent",
    hover_name="country",
    log_x=True,
    size_max=60,
)

tab1, tab2 = st.tabs(["Streamlit theme (default)", "Plotly native theme"])
with tab1:
    # Use the Streamlit theme.
    # This is the default. So you can also omit the theme argument.
    st.plotly_chart(fig, theme="streamlit", width="stretch")
with tab2:
    # Use the native Plotly theme.
    st.plotly_chart(fig, theme=None, width="stretch")
```

Click the tabs in the interactive app below to see the charts with the Streamlit theme enabled and disabled.

[Example app: doc-plotly-chart-theme](https://doc-plotly-chart-theme.streamlit.app/)

If you're wondering if your own customizations will still be taken into account, don't worry! You can still make changes to your chart configurations. In other words, although we now enable the Streamlit theme by default, you can overwrite it with custom colors or fonts. For example, if you want a chart line to be green instead of the default red, you can do it!

Here's an example of an Plotly chart where a custom color scale is defined and reflected:

```python
import plotly.express as px
import streamlit as st

st.subheader("Define a custom colorscale")
df = px.data.iris()
fig = px.scatter(
    df,
    x="sepal_width",
    y="sepal_length",
    color="sepal_length",
    color_continuous_scale="reds",
)

tab1, tab2 = st.tabs(["Streamlit theme (default)", "Plotly native theme"])
with tab1:
    st.plotly_chart(fig, theme="streamlit", width="stretch")
with tab2:
    st.plotly_chart(fig, theme=None, width="stretch")
```

Notice how the custom color scale is still reflected in the chart, even when the Streamlit theme is enabled 👇

[Example app: doc-plotly-custom-colors](https://doc-plotly-custom-colors.streamlit.app/)

For many more examples of Plotly charts with and without the Streamlit theme, check out the [plotly.streamlit.app](https://plotly.streamlit.app).
