st.pagination
Display a pagination widget for navigating through pages of content.
The widget displays numbered page buttons with previous/next arrows and intelligent truncation for large page counts. One page is always selected, and the widget returns the currently selected page number (1-indexed).
| Function signature[source] | |
|---|---|
st.pagination(num_pages, *, default=1, max_visible_pages=7, width="content", key=None, on_change=None, args=None, kwargs=None, disabled=False, bind=None) | |
| Parameters | |
num_pages (int) | Total number of pages. Must be at least 1. |
default (int) | Initial selected page (1-indexed). Must be between 1 and num_pages. The default is 1. |
max_visible_pages (int or None) | Target number of page buttons to display (excluding prev/next arrows). The actual number may be slightly higher in certain edge cases to ensure the first and last pages are always visible for navigation context. The widget auto-adapts to available width and may show fewer pages to prevent wrapping. The default is 7.
|
width ("content", "stretch", or int) | The width of the pagination widget. This can be one of the following:
|
key (str, int, or None) | An optional string or integer to use as the unique key for the widget. If this is None (default), a key will be generated for the widget based on the values of the other parameters. No two widgets may have the same key. Assigning a key stabilizes the widget's identity and preserves its state across reruns even when other parameters change. A key lets you read or update the widget's value via st.session_state[key]. 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_change (callable) | An optional callback invoked when the selected page changes. |
args (list or tuple) | An optional list or tuple of args to pass to the callback. |
kwargs (dict) | An optional dict of kwargs to pass to the callback. |
disabled (bool) | An optional boolean that disables the pagination widget if set to True. The default is False. |
bind ("query-params" or None) | Bind the widget's value to st.query_params so that the widget's value is synced to the URL query string. If this is "query-params" (default is None), the widget's value will be read from and written to the URL using the key parameter as the query parameter name. This enables shareable URLs that preserve the widget's state. If bind is set, key is required. |
| Returns | |
(int) | The currently selected page (1-indexed). |
Examples
Basic usage with paginated content:
import streamlit as st page = st.pagination(num_pages=10) st.write(f"Showing page {page}")Paginated dataframe:
import streamlit as st import pandas as pd df = pd.DataFrame({"A": range(100), "B": range(100, 200)}) rows_per_page = 10 total_pages = (len(df) + rows_per_page - 1) // rows_per_page # Use placeholders to show dataframe above pagination dataframe_slot = st.empty() with st.container(horizontal_alignment="right"): page = st.pagination(num_pages=total_pages) start_idx = (page - 1) * rows_per_page end_idx = start_idx + rows_per_page dataframe_slot.dataframe(df.iloc[start_idx:end_idx])
Still have questions?
Our forums are full of helpful information and Streamlit experts.