st.dataframe - Streamlit Docs
Show API reference for
star

Tip

Learn more in our Dataframes guide and check out our tutorial, Get dataframe row-selections from users.

st.dataframe

Display a dataframe as an interactive table.

This command works with a wide variety of collection-like and dataframe-like object types.

Examples

Example 1: Display a dataframe

import pandas as pd
import streamlit as st
from numpy.random import default_rng as rng

df = pd.DataFrame(
    rng(0).standard_normal((50, 20)), columns=("col %d" % i for i in range(20))
)

st.dataframe(df)
Built with Streamlit 🎈

Example 2: Use Pandas Styler

You can also pass a Pandas Styler object to change the style of the rendered DataFrame:

import pandas as pd
import streamlit as st
from numpy.random import default_rng as rng

df = pd.DataFrame(
    rng(0).standard_normal((10, 20)), columns=("col %d" % i for i in range(20))
)

st.dataframe(df.style.highlight_max(axis=0))
Built with Streamlit 🎈

Example 3: Use column configuration

You can customize a dataframe via column_config, hide_index, or column_order.

import pandas as pd
import streamlit as st
from numpy.random import default_rng as rng

df = pd.DataFrame(
    {
        "name": ["Roadmap", "Extras", "Issues"],
        "url": [
            "https://roadmap.streamlit.app",
            "https://extras.streamlit.app",
            "https://issues.streamlit.app",
        ],
        "stars": rng(0).integers(0, 1000, size=3),
        "views_history": rng(0).integers(0, 5000, size=(3, 30)).tolist(),
    }
)

st.dataframe(
    df,
    column_config={
        "name": "App name",
        "stars": st.column_config.NumberColumn(
            "Github Stars",
            help="Number of stars on GitHub",
            format="%d ⭐",
        ),
        "url": st.column_config.LinkColumn("App URL"),
        "views_history": st.column_config.LineChartColumn(
            "Views (past 30 days)", y_min=0, y_max=5000
        ),
    },
    hide_index=True,
)
Built with Streamlit 🎈

Example 4: Customize your index

You can use column configuration to format your index.

from datetime import datetime, date
import numpy as np
import pandas as pd
import streamlit as st

@st.cache_data
def load_data():
    year = datetime.now().year
    df = pd.DataFrame(
        {
            "Date": [date(year, month, 1) for month in range(1, 4)],
            "Total": np.random.randint(1000, 5000, size=3),
        }
    )
    df.set_index("Date", inplace=True)
    return df

df = load_data()
config = {
    "_index": st.column_config.DateColumn("Month", format="MMM YYYY"),
    "Total": st.column_config.NumberColumn("Total ($)"),
}

st.dataframe(df, column_config=config)
Built with Streamlit 🎈

Dataframe selections

DataframeState

The schema for the dataframe event state.

The event state is stored in a dictionary-like object that supports both key and attribute notation. Event states can be programmatically set through session state by assigning a dictionary with the same schema to the widget's key, e.g., st.session_state["my_key"] = {"selection": {"rows": [0, 2]}}.

Only selection events are supported at this time.

Attributes

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 DataframeSelectionState dictionary schema.

DataframeSelectionState

The schema for the dataframe selection state.

The selection state is stored in a dictionary-like object that supports both key and attribute notation. Selection states can be programmatically set through Session State by assigning a DataframeSelectionState dictionary to the "selection" key of a DataframeState dictionary.

Programmatic selection is supported for all selection modes except "multi-cell". If "single-cell" isn't included in the selection modes of the dataframe, programmatic cell selections are ignored.

Warning

If a user sorts a dataframe, row selections will be reset. If your users need to sort and filter the dataframe to make selections, direct them to use the search function in the dataframe toolbar instead.

Examples

Example 1: Enable dataframe selections

The following example has multi-row and multi-column selections enabled. Try selecting some rows. To select multiple columns, hold CMD (macOS) or Ctrl (Windows) while selecting columns. Hold Shift to select a range of columns.

import pandas as pd
import streamlit as st
from numpy.random import default_rng as rng

df = pd.DataFrame(
    rng(0).standard_normal((12, 5)), columns=["a", "b", "c", "d", "e"]
)

event = st.dataframe(
    df,
    key="data",
    on_select="rerun",
    selection_mode=["multi-row", "multi-column", "multi-cell"],
)

event.selection
Built with Streamlit 🎈

Example 2: Programmatically set selections

To programmatically set dataframe selections, assign a key to your dataframe and set the selection through Session State.

import pandas as pd
import streamlit as st
from numpy.random import default_rng as rng

df = pd.DataFrame(
    rng(0).standard_normal((12, 5)), columns=["a", "b", "c", "d", "e"]
)

if st.button("Select the first row"):
    st.session_state.data = {"selection": {"rows": [0]}}
if st.button("Select column a"):
    st.session_state.data = {"selection": {"columns": ["a"]}}
if st.button("Select the first cell of column a"):
    st.session_state.data = {"selection": {"cells": [[0, "a"]]}}

event = st.dataframe(
    df,
    key="data",
    on_select="rerun",
    selection_mode=["single-cell", "single-row", "single-column"],
)

event.selection
Built with Streamlit 🎈

DeltaGenerator.add_rows

priority_high

Warning

This method does not exist in version 1.58.0 of Streamlit.

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

Built with Streamlit 🎈
arrow_backPrevious: Data elementsarrow_forwardNext: st.data_editor
forum

Still have questions?

Our forums are full of helpful information and Streamlit experts.