st.dataframe

star

Tip

This page only contains information on the st.dataframe API. For a deeper dive into working with dataframes read Dataframes. If you want to let users interactively edit dataframes, check out st.data_editor.

Display a dataframe as an interactive table.

This command works with dataframes from Pandas, PyArrow, Snowpark, and PySpark. It can also display several other types that can be converted to dataframes, e.g. numpy arrays, lists, sets and dictionaries.

Function signature[source]
st.dataframe(data=None, width=None, height=None, *, use_container_width=False, hide_index=None, column_order=None, column_config=None)
Parameters
data (pandas.DataFrame, pandas.Series, pandas.Styler, pandas.Index, pyarrow.Table, numpy.ndarray, pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, snowflake.snowpark.table.Table, Iterable, dict, or None)	The data to display. If 'data' is a pandas.Styler, it will be used to style its underlying DataFrame. Streamlit supports custom cell values and colors. It does not support some of the more exotic pandas styling features, like bar charts, hovering, and captions.
width (int or None)	Desired width of the dataframe expressed in pixels. If None, the width will be automatically calculated based on the column content.
height (int or None)	Desired height of the dataframe expressed in pixels. If None, a default height is used.
use_container_width (bool)	If True, set the dataframe width to the width of the parent container. This takes precedence over the width argument. This argument can only be supplied by keyword.
hide_index (bool or None)	Whether to hide the index column(s). If None (default), the visibility of index columns is automatically determined based on the data.
column_order (iterable of str or None)	Specifies the display order of columns. This also affects which columns are visible. For example, `column_order=("col2", "col1")` will display 'col2' first, followed by 'col1', and will hide all other non-index columns. If None (default), the order is inherited from the original data structure.
column_config (dict or None)	Configures how columns are displayed, e.g. their title, visibility, type, or format. This needs to be a dictionary where each key is a column name and the value is one of: `None` to hide the column. A string to set the display label of the column. One of the column types defined under `st.column_config`, e.g. `st.column_config.NumberColumn("Dollar values”, format=”$ %d")` to show a column as dollar amounts. See more info on the available column types and config options here. To configure the index column(s), use `_index` as the column name.

Examples

import streamlit as st
import pandas as pd
import numpy as np

df = pd.DataFrame(
   np.random.randn(50, 20),
   columns=('col %d' % i for i in range(20)))

st.dataframe(df)  # Same as st.write(df)

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

import streamlit as st
import pandas as pd
import numpy as np

df = pd.DataFrame(
   np.random.randn(10, 20),
   columns=('col %d' % i for i in range(20)))

st.dataframe(df.style.highlight_max(axis=0))

Or you can customize the dataframe via column_config, hide_index, or column_order:

import random
import pandas as pd
import streamlit as st

df = pd.DataFrame(
    {
        "name": ["Roadmap", "Extras", "Issues"],
        "url": ["https://roadmap.streamlit.app", "https://extras.streamlit.app", "https://issues.streamlit.app"],
        "stars": [random.randint(0, 1000) for _ in range(3)],
        "views_history": [[random.randint(0, 5000) for _ in range(30)] for _ in range(3)],
    }
)
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,
)

st.dataframe supports the use_container_width parameter to stretch across the full container width:

import pandas as pd
import streamlit as st

# Cache the dataframe so it's only loaded once
@st.cache_data
def load_data():
    return pd.DataFrame(
        {
            "first column": [1, 2, 3, 4],
            "second column": [10, 20, 30, 40],
        }
    )

# Boolean to resize the dataframe, stored as a session state variable
st.checkbox("Use container width", value=False, key="use_container_width")

df = load_data()

# Display the dataframe and allow the user to stretch the dataframe
# across the full width of the container, based on the checkbox value
st.dataframe(df, use_container_width=st.session_state.use_container_width)

Column configuration

When working with data in Streamlit, the st.column_config class is a powerful tool for configuring data display and interaction. Specifically designed for the column_config parameter in st.dataframe and st.data_editor, it provides a suite of methods to tailor your columns to various data types - from simple text and numbers to lists, URLs, images, and more.

Whether it's translating temporal data into user-friendly formats or utilizing charts and progress bars for clearer data visualization, column configuration not only provides the user with an enriched data viewing experience but also ensures that you're equipped with the tools to present and interact with your data, just the way you want it.

Column

Configure a generic column.

Column("Streamlit Widgets", width="medium", help="Streamlit **widget** commands 🎈")

Text column

Configure a text column.

TextColumn("Widgets", max_chars=50, validate="^st\.[a-z_]+$")

Number column

Configure a number column.

NumberColumn("Price (in USD)", min_value=0, format="$%d")

Checkbox column

Configure a checkbox column.

CheckboxColumn("Your favorite?", help="Select your **favorite** widgets")

Selectbox column

Configure a selectbox column.

SelectboxColumn("App Category", options=["🤖 LLM", "📈 Data Viz"])

Datetime column

Configure a datetime column.

DatetimeColumn("Appointment", min_value=datetime(2023, 6, 1), format="D MMM YYYY, h:mm a")

Date column

Configure a date column.

DateColumn("Birthday", max_value=date(2005, 1, 1), format="DD.MM.YYYY")

Time column

Configure a time column.

TimeColumn("Appointment", min_value=time(8, 0, 0), format="hh:mm a")

List column

Configure a list column.

ListColumn("Sales (last 6 months)", width="medium")

Link column

Configure a link column.

LinkColumn("Trending apps", max_chars=100, validate="^https://.*$")

Image column

Configure an image column.

ImageColumn("Preview Image", help="The preview screenshots")

Line chart column

Configure a line chart column.

LineChartColumn("Sales (last 6 months)" y_min=0, y_max=100)

Bar chart column

Configure a bar chart column.

BarChartColumn("Marketing spend" y_min=0, y_max=100)

Progress column

Configure a progress column.

ProgressColumn("Sales volume", min_value=0, max_value=1000, format="$%f")

Interactivity

Dataframes displayed as interactive tables with st.dataframe have the following interactive features:

Column sorting: sort columns by clicking on their headers.
Column resizing: resize columns by dragging and dropping column header borders.
Table (height, width) resizing: resize tables by dragging and dropping the bottom right corner of tables.
Search: search through data by clicking a table, using hotkeys (⌘ Cmd + F or Ctrl + F) to bring up the search bar, and using the search bar to filter data.
Copy to clipboard: select one or multiple cells, copy them to clipboard, and paste them into your favorite spreadsheet software.

editSuggest edits

Tip