st.column_config.ButtonColumn
Configure a button column in st.dataframe or st.data_editor.
Button columns display clickable buttons in each cell, enabling row-level actions with Python callbacks. The cell values determine the button labels. This command needs to be used in the column_config parameter of st.dataframe or st.data_editor. Button columns are always read-only— in st.data_editor, the underlying cell values cannot be edited, but button clicks still trigger callbacks.
| Function signature[source] | |
|---|---|
st.column_config.ButtonColumn(label=None, *, width=None, help=None, pinned=None, alignment=None, type="secondary", on_click=None, args=None, kwargs=None, key=None) | |
| Parameters | |
label (str or None) | The label shown at the top of the column. If this is None (default), the column name is used. |
width ("small", "medium", "large", int, or None) | The display width of the column. If this is None (default), the column will be sized to fit the cell contents. Otherwise, this can be one of the following:
If the total width of all columns is less than the width of the dataframe, the remaining space will be distributed evenly among all columns. |
help (str or None) | A tooltip that gets displayed when hovering over the column label. If this is None (default), no tooltip is displayed. The tooltip can optionally contain GitHub-flavored Markdown, including the Markdown directives described in the body parameter of st.markdown. |
pinned (bool or None) | Whether the column is pinned. A pinned column will stay visible on the left side no matter where the user scrolls. If this is None (default), Streamlit will decide: index columns are pinned, and data columns are not pinned. |
alignment ("left", "center", "right", or None) | The horizontal alignment of the button within the cell. If this is None (default), buttons are centered. |
type ("primary", "secondary", or "tertiary") | An optional string that specifies the button type. This can be one of the following:
|
on_click (callable or None) | An optional callback invoked when a button is clicked. By default, the callback receives no arguments. Use args and kwargs to pass extra arguments. The click information is also available in st.session_state[key] during the callback. |
args (tuple or None) | An optional tuple of args to pass to the callback. |
kwargs (dict or None) | An optional dict of kwargs to pass to the callback. |
key (str or None) | A session state key for the click trigger value. When a button is clicked, the click information is stored under this key in Session State as a dictionary-like object with row (int) and label (str) entries that support both key and attribute notation. For example, if key="my_click", you can access the clicked row with st.session_state.my_click.row or st.session_state["my_click"]["row"]. The value is only present during the rerun triggered by the click; it resets to None on subsequent reruns. key is required to enable button clicks and callbacks. |
Examples
Example 1: Basic button column with callback
import pandas as pd
import streamlit as st
df = pd.DataFrame(
{
"name": ["Alice", "Bob", "Charlie"],
"view": [":material/visibility: View"] * 3,
}
)
def handle_view():
click = st.session_state.view_click
st.toast(f"Viewing row {click['row']}: {df.iloc[click['row']]['name']}")
st.dataframe(
df,
column_config={
"view": st.column_config.ButtonColumn(
"", type="tertiary", on_click=handle_view, key="view_click"
),
},
hide_index=True,
)
Example 2: Multi-action dropdown
import pandas as pd
import streamlit as st
df = pd.DataFrame(
{
"name": ["Alice", "Bob", "Charlie"],
"actions": [
[":material/edit: Edit", ":material/delete: Delete"],
[":material/edit: Edit", ":material/delete: Delete"],
[":material/edit: Edit"],
],
}
)
def handle_action():
click = st.session_state.action_click
if "Delete" in click["label"]:
st.warning(f"Deleting row {click['row']}")
elif "Edit" in click["label"]:
st.info(f"Editing row {click['row']}")
st.dataframe(
df,
column_config={
"actions": st.column_config.ButtonColumn(
"Actions", on_click=handle_action, key="action_click"
),
},
)
Note
Button columns are always read-only. In st.data_editor, the underlying cell values cannot be edited, but button clicks still trigger callbacks.
Still have questions?
Our forums are full of helpful information and Streamlit experts.