Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 38 ยท Text, Data and Charts

DataFrames and Tables

Show pandas data in Streamlit with st.dataframe, st.table and st.data_editor. Learn column_config, hiding the index, styling, row selection and editing data safely.

Tables are the bread and butter of data apps. Streamlit gives you three ways to display a pandas DataFrame: an interactive grid (st.dataframe), a static table (st.table), and an editable grid (st.data_editor). This lesson shows when to use each, how to polish columns with column_config, and how to handle the edits a user makes.

The Streamlit snippets are real and read-only. Pandas logic that prepares the data runs in the browser, so you can check it before you display it.

st.dataframe: the interactive grid

Python
import pandas as pd
import streamlit as st

df = pd.DataFrame({
    "product": ["Tea", "Coffee", "Juice", "Water"],
    "price": [2.5, 3.2, 4.0, 1.5],
    "stock": [120, 80, 45, 300],
})

st.dataframe(df)

The page shows a scrollable grid. Users can click a column header to sort, drag column borders to resize, search with the magnifier icon (or Ctrl+F), hide columns from a menu, and expand the grid to full screen. A download icon exports the visible data as CSV. All this happens in the browser with no rerun, so it is fast even on big tables.

Useful arguments:

Argument Effect
hide_index=True Do not show the DataFrame index column
height=300 Fix the height in pixels; the grid then scrolls
width="stretch" Fill the available width (older versions use use_container_width=True)
column_order=["product", "price"] Show only these columns, in this order
column_config={...} Format and describe individual columns
on_select="rerun" Let the user select rows and rerun the app

column_config: formatting columns

st.column_config has a class for each kind of column. You pass them as a dictionary keyed by column name:

Python
import pandas as pd
import streamlit as st

df = pd.DataFrame({
    "product": ["Tea", "Coffee", "Juice"],
    "price": [2.5, 3.2, 4.0],
    "rating": [0.8, 0.95, 0.6],
    "weekly_sales": [[5, 8, 6, 9], [12, 9, 14, 10], [4, 3, 6, 5]],
    "link": ["https://example.com/tea", "https://example.com/coffee",
             "https://example.com/juice"],
})

st.dataframe(
    df,
    hide_index=True,
    column_config={
        "product": st.column_config.TextColumn("Product", help="Item name"),
        "price": st.column_config.NumberColumn("Price", format="$%.2f"),
        "rating": st.column_config.ProgressColumn("Rating", min_value=0, max_value=1),
        "weekly_sales": st.column_config.LineChartColumn("Last 4 weeks"),
        "link": st.column_config.LinkColumn("Page"),
    },
)

The grid shows prices as $2.50, a progress bar inside the rating cells, a tiny line chart in each "Last 4 weeks" cell, and clickable links. Other column types include CheckboxColumn, SelectboxColumn, DateColumn, DatetimeColumn, ImageColumn, BarChartColumn and ListColumn. A column config only changes how data is displayed; the DataFrame is not modified.

Styling with pandas

st.dataframe also accepts a pandas Styler, so conditional colors and formats carry over:

Python
styled = df.style.format({"price": "${:.2f}"}).highlight_max(subset=["price"], color="#ffd966")
st.dataframe(styled)

Styler support covers colors and number formats. Heavy styling slows large tables, so use column_config when it is enough. See the pandas styling lesson for the Styler itself.

st.table: static and simple

Python
st.table(df.head(3))

st.table draws a plain, non-interactive table that shows every row and cannot be sorted or searched. It is right for tiny summaries that should look like part of the page text. For more than a few dozen rows use st.dataframe.

Row selection

With on_select="rerun" the grid reports which rows (or columns) the user picked, and your script reruns:

Python
event = st.dataframe(
    df,
    on_select="rerun",
    selection_mode="single-row",
    hide_index=True,
)
rows = event.selection.rows        # positions of the selected rows, e.g. [1]
if rows:
    st.write("You picked:", df.iloc[rows[0]]["product"])

Selecting the "Coffee" row makes the page show "You picked: Coffee". The result is a dictionary-like object; rows holds integer positions, so use iloc to look rows up. Modes include "single-row", "multi-row", "single-column" and "multi-column".

st.data_editor: let users edit

st.data_editor is a grid users can type into. It returns the edited DataFrame, and each edit triggers a rerun:

Python
edited = st.data_editor(
    df,
    num_rows="dynamic",          # allow adding and deleting rows
    hide_index=True,
    column_config={
        "price": st.column_config.NumberColumn("Price", min_value=0, step=0.1),
    },
)
st.write("Total stock value:", (edited["price"] * edited["stock"]).sum())

Users can change cells, add rows at the bottom (because of "dynamic"), and delete selected rows. Because every edit reruns the script, the sentence "Total stock value" updates live. min_value=0 stops negative prices at the grid itself.

Remember the rerun rule from the rerun model: edited is a fresh return value on each run. If you need the edits to survive for later use (saving to a file, sharing with another page), copy them into st.session_state or write them to storage when a button is pressed.

Handling edits: logic you can run

What you do with the returned DataFrame is plain pandas: validate, clean, recompute. Practice it here with runnable code. We build an "edited" DataFrame by hand (as if the user had changed a price and added a row), then check it.

Python Validate and recompute edited data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In an app you would show the bad rows with st.warning, display clean with st.dataframe, and show the total with st.metric.

Applying data-editor changes (stand-in)

For large tables Streamlit also exposes the edit log, stored in st.session_state under the editor's key, as a dictionary with edited_rows, added_rows and deleted_rows. The shape looks like this; the block below is a stand-in that applies such a log to a DataFrame so you see how it works.

Python Stand-in: apply an edit log

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Performance tips

  • Display only the rows and columns people need: df.head(1000), or filter first.
  • Very wide or tall tables are fine in st.dataframe (it renders only what is visible), but expensive Stylers are not.
  • Cache loading and cleaning (see the State and Caching chapter) so a table interaction does not reread the CSV.
  • A number like 1234567.891 displays fully; use format in NumberColumn instead of rounding the data.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which function returns the DataFrame after the user edits cells?

    st.data_editor displays an editable grid and returns the edited DataFrame on each run.
  2. 2. You want a tiny read-only summary shown completely, with no sorting. Which is best?

    st.table draws a simple static table with all rows.
  3. 3. What does hide_index=True do?

    It only affects display; the DataFrame is unchanged.
  4. 4. What does column_config.ProgressColumn show?

    ProgressColumn draws a progress bar from the number in the cell, between min_value and max_value.
  5. 5. With on_select='rerun', what does event.selection.rows contain?

    It lists integer positions; use df.iloc[...] to read the selected rows.

Summary

  • st.dataframe is an interactive, sortable, searchable grid; st.table is static; st.data_editor is editable and returns the new DataFrame.
  • column_config formats and types columns for display only.
  • Row selection uses on_select="rerun" and returns integer row positions.
  • Validate and recompute edits with plain pandas, and keep anything that must persist in session state or storage.

Next: Metrics and Status Elements