# st.dataframe

Source: https://docs.streamlit.io/develop/api-reference/data/st.dataframe

> **Tip**
>
> Learn more in our [Dataframes](https://docs.streamlit.io/develop/concepts/design/dataframes) guide and check out our tutorial, [Get dataframe row-selections from users](https://docs.streamlit.io/develop/tutorials/elements/dataframe-row-selections). For lazy loading, cross-filtering, and drill-down in dashboards, see [Build advanced dashboards](https://docs.streamlit.io/develop/concepts/design/dashboards).

* Function signature:

   ```python
   st.dataframe(data=None, width="stretch", height="auto", *, use_container_width=None, hide_index=None, column_order=None, column_config=None, key=None, on_select="ignore", selection_mode="multi-row", selection_default=None, row_height=None, placeholder=None, lazy=None, alt=None)
   ```

* Parameters:

   | name | type | default | description |
   |---|---|---|---|
   | data | dataframe-like, collection-like, or None |  | The data to display. Dataframe-like objects include dataframe and series objects from popular libraries like Dask, Modin, Numpy, pandas, Polars, PyArrow, Snowpark, Xarray, and more. You can use database cursors and clients that comply with the Python Database API Specification v2.0 (PEP 249). Additionally, you can use anything that supports the Python dataframe interchange protocol. For example, you can use the following:  pandas.DataFrame, pandas.Series, pandas.Index, pandas.Styler, and pandas.Array polars.DataFrame, polars.LazyFrame, and polars.Series snowflake.snowpark.dataframe.DataFrame, snowflake.snowpark.table.Table  If a data type is not recognized, Streamlit will convert the object to a pandas.DataFrame or pyarrow.Table using a .to_pandas() or .to_arrow() method, respectively, if available. If data is a pandas.Styler, it will be used to style its underlying pandas.DataFrame. Streamlit supports custom cell values, colors, and font weights. It does not support some of the more exotic styling options, like bar charts, hovering, and captions. For these options, use column configuration where an equivalent exists (for example, BarChartColumn or ProgressColumn instead of Styler bars), or use st.table for small, static tables that need fuller Pandas Styler support. Text and number formatting from column_config always takes precedence over text and number formatting from pandas.Styler. Collection-like objects include all Python-native Collection types, such as dict, list, and set. If data is None, Streamlit renders an empty table. |
   | width | "stretch", "content", or int |  | The width of the dataframe 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 | "auto", "content", "stretch", or int | height | The height of the dataframe element. This can be one of the following:  "auto" (default): Streamlit sets the height to show at most ten rows. "content": The height of the element matches the height of its content. The height is capped at 10,000 pixels to prevent performance issues with very large dataframes. "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. In a fixed-height container, or a stretch container that fills one, the dataframe keeps a minimum height that displays up to three rows and shrinks to the remaining space when that minimum fits. Otherwise, the dataframe uses its default height (at most ten rows) and still grows to match a taller sibling. An integer specifying the height in pixels: The element has a fixed height.  Vertical scrolling within the dataframe element is enabled when the height does not accommodate all rows. |
   | use_container_width | bool |  | Whether to override width with the width of the parent container. If this is True (default), Streamlit sets the width of the dataframe to match the width of the parent container. If this is False, Streamlit sets the dataframe's width according to width. |
   | hide_index | bool or None |  | Whether to hide the index column(s). If hide_index is None (default), the visibility of index columns is automatically determined based on the data and other configurations. |
   | column_order | Iterable[str] or None | but | The ordered list of columns to display. If this is None (default), Streamlit displays all columns in the order inherited from the underlying data structure. If this is a list, the indicated columns will display in the order they appear within the list. Columns may be omitted or repeated within the list. For example, column_order=("col2", "col1") will display "col2" first, followed by "col1", and will hide all other non-index columns. column_order does not accept positional column indices and can't move the index column(s).  Note Columns omitted from column_order are hidden by default but can still be shown by the user via the column visibility menu in the table toolbar. If a column contains sensitive data that should not be exposed to the user, remove it from the data before passing it to the function. |
   | column_config | dict or None |  | Configuration to customize how columns are displayed. If this is None (default), columns are styled based on the underlying data type of each column. Column configuration can modify column names, visibility, type, width, format, and more. If this is a dictionary, the keys are column names (strings) and/or positional column indices (integers), and the values are one of the following:  None to hide the column. Hidden columns can still be shown by the user via the table toolbar. A string to set the display label of the column. One of the column types defined under st.column_config. For example, to show a column as dollar amounts, use st.column_config.NumberColumn("Dollar values", format="$ %d"). See more info on the available column types and config options here.  To configure the index column(s), use "_index" as the column name, or use a positional column index where 0 refers to the first index column. |
   | 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, a key lets you read or update the selection state via st.session_state[key]. The value in Session State must be a dictionary consistent with the DataframeState schema. 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 dataframe should respond to user selection events. This controls whether or not the dataframe 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 dataframe. The dataframe will not behave like an input widget. "rerun": Streamlit will rerun the app when the user selects rows, columns, or cells in the dataframe. In this case, st.dataframe 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.dataframe will return the selection data as a dictionary. |
   | selection_mode | "single-row", "single-row-required", "multi-row",             "single-column", "multi-column", "single-cell", "multi-cell",             or Iterable of these | given | The types of selections Streamlit should allow when selections are enabled with on_select. This can be one of the following:  "multi-row" (default): Multiple rows can be selected at a time. "single-row": Only one row can be selected at a time. "single-row-required": Exactly one row must always be selected (radio-like behavior). Auto-selects the first row if no default is given. "multi-column": Multiple columns can be selected at a time. "single-column": Only one column can be selected at a time. "multi-cell": A rectangular range of cells can be selected. "single-cell": Only one cell can be selected at a time. An Iterable of the above options: The table will allow selection based on the modes specified. For example, to allow the user to select multiple rows and multiple cells, use ["multi-row", "multi-cell"].  When column selections are enabled, column sorting is disabled. |
   | selection_default | dict or None | selection | The default selection state to apply on first render when selections are activated and no prior selection is stored. This uses the same schema as st.session_state[key] for selections, for example: {"selection": {"rows": [0, 2]}}. selection_default is only applied when on_select is not "ignore". It does not override user selections on subsequent runs, and multi-cell selections cannot be set programmatically. |
   | row_height | int or None | row | The height of each row in the dataframe in pixels. If row_height is None (default), Streamlit will use a default row height, which fits one line of text. |
   | placeholder | str or None |  | The text that should be shown for missing values. If this is None (default), missing values are displayed as "None". To leave a cell empty, use an empty string (""). Other common values are "null", "NaN" and "-". |
   | lazy | bool or None |  | Whether to load rows lazily from the app server instead of sending the full dataset to the browser. When rows are loaded lazily, Streamlit sends only the rows the user is viewing and fetches more as they scroll or sort. This is useful for datasets that are too large to send to the browser all at once. It can also make your app faster on reruns, since far less data needs to be transferred from the app server to the client (browser). This can be one of the following:  None (default): Streamlit chooses automatically. In-memory pandas and polars dataframes and pyarrow.Table objects are loaded lazily when they have more than 150,000 rows. Unevaluated objects, such as a Polars LazyFrame, are loaded lazily when they have more than 10,000 rows. Everything else is loaded eagerly, including the capped preview for unsupported unevaluated objects. True: Always load rows lazily. For inputs that support lazy access natively (for example, a Polars LazyFrame), Streamlit reads rows directly from the source. Other supported inputs are held in the app server's memory and served in chunks. Small datasets (1,000 rows or fewer) are still loaded eagerly as an optimization. If lazy loading is incompatible with the data or the other parameters (for example, dataframes with multi-level, MultiIndex, column headers), Streamlit raises a StreamlitAPIException. False: Never load rows lazily. Streamlit loads data eagerly and uses the capped preview for unevaluated data objects.   Note When rows are loaded lazily, search, CSV download, selections (on_select), and pandas.Styler styling are not supported. Server-side sorting is supported. To use these features, set lazy=False. |
   | alt | str or None |  | A short, plain-text accessible name for the dataframe. If this is None (default), the grid has no element-level accessible name. Cell values remain available through the grid's own accessibility tree. An empty or whitespace-only string is treated the same as None. Prefer naming what the data is (for example, "Top 20 customers by revenue") rather than pasting cell contents. This is a short name for findability, not a full text alternative for the table. |

* Returns: element or DataframeState

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

## Dataframe selections

* Function signature:

   ```python
   DataframeState
   ```

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

* Function signature:

   ```python
   DataframeSelectionState
   ```

* Parameters:

   | name | type | default | description |
   |---|---|---|---|
   | rows | list[int] |  | The selected rows, identified by their integer position. The integer positions match the original dataframe, even if the user sorts the dataframe in their browser. For a pandas.DataFrame, you can retrieve data from its integer position using methods like .iloc[] or .iat[]. |
   | columns | list[str] |  | The selected columns, identified by their names. |
   | cells | list[tuple[int, str]] |  | The selected cells, provided as a tuple of row integer position and column name. For example, the first cell in a column named "col 1" is represented as (0, "col 1"). Cells within index columns are not returned. |

## Interactivity

Dataframes displayed with `st.dataframe` are interactive. End users can sort, resize, search, and copy data to their clipboard. For on overview of features, read our [Dataframes](https://docs.streamlit.io/develop/concepts/design/dataframes#additional-ui-features) guide.

## Configuring columns

You can configure the display and editing behavior of columns in `st.dataframe` and `st.data_editor` via the [Column configuration API](https://docs.streamlit.io/develop/api-reference/data/st.column_config). We have developed the API to let you add images, charts, and clickable URLs in dataframe and data editor columns. Additionally, you can make individual columns editable, set columns as categorical and specify which options they can take, hide the index of the dataframe, and much more.

[Example app: doc-column-config-overview](https://doc-column-config-overview.streamlit.app/)
