Developing with Streamlit

Developing with Streamlit

This is a routing skill that directs you to specialized references for Streamlit development.

When to Use

Invoke this skill when the user's request involves:

• Creating a new Streamlit app
• Editing or modifying an existing Streamlit app
• Debugging Streamlit issues (errors, session state bugs, performance problems)
• Beautifying or improving the visual design of a Streamlit app
• Optimizing Streamlit performance (caching, fragments, reruns)
• Building and running Streamlit apps
• Building chat, conversational, or agentic UIs (AI assistants, thinking expanders, chain-of-thought, tool-call timelines)
• Styling widgets (button colors, backgrounds, CSS customization)
• Advanced server configuration with st.App, ASGI, Starlette, FastAPI integration, custom routes, middleware, or lifespan hooks
• Any question about Streamlit widgets, layouts, or components

Trigger phrases: "streamlit", "st.", "st.App", "dashboard", "app.py", "beautify app", "make it look better", "style", "CSS", "color", "background", "theme", "button", "slow rerun", "session state", "performance", "faster", "cache", "chat", "agentic", "chain of thought"

Best practices quick reference

IMPORTANT — use_container_width is deprecated. Never add use_container_width to new code. Use width="stretch" or width="content" instead. Dataframes and most charts stretch to fill their container by default, but buttons, including st.button, st.download_button, st.form_submit_button, st.link_button, and st.page_link, default to width="content"; pass width="stretch" to make one fill its container. Remove use_container_width when you encounter it.

Apply these defaults unless the user's app or request clearly needs a different approach. For examples, read references/best-practices.md.

• Do not use use_container_width; use width="stretch" or width="content" instead.
• Prefer native Streamlit elements over recreating UI with custom HTML. This includes UI created with st.html, st.markdown(..., unsafe_allow_html=True), or deprecated st.components.v1.html. Use custom HTML only when no native element provides the required UI or behavior.
• Do not use the deprecated st.components.v1.html or st.components.v1.iframe commands. Use st.iframe for iframe-based rendering of URLs or HTML, and use st.html for HTML/CSS that should render directly in the app; st.html ignores JavaScript by default unless unsafe_allow_javascript=True.
• Do not apply CSS to style the app unless the user actively requests it. Use native Streamlit features and .streamlit/config.toml to customize the appearance; see the theming reference.
• Prefer Material Symbols icons (:material/icon_name:) over emojis for navigation, buttons, and labels. Use emojis sparingly, only when they add a special touch.
• Prefer sentence casing over title casing, including titles and widget labels.
• Do not use empty widget labels; use label_visibility="collapsed" or label_visibility="hidden" when a visible label is not desired.
• When an alert (st.info, st.success, st.warning, or st.error) needs a headline, pass keyword-only title= instead of bolding the first line of the body or adding a heading above it.
• Pass keyword-only alt= on images, charts, maps, media, iframes, PDFs, tables, dataframes, and data editors so assistive technologies can name them. Keep it short; decorative alt="" is only for st.image / st.pyplot. See references/media-display.md and references/data-display.md.
• Use st.container(border=True) for simple visual grouping. Prefer st.container(horizontal=True) over st.columns for responsive row layouts; use st.columns for fixed grids, precise width ratios, or side-by-side cards that must share a width.
• Align elements placed side by side: use vertical_alignment="bottom" for rows that mix labeled inputs with buttons, checkboxes, or toggles, and give sibling cards consistent content (for example, all metrics with or all without delta) or height="stretch". See "Aligning elements side by side" in references/layouts.md.
• Prefer st.navigation and st.Page with an app_pages/ folder over the legacy pages/ directory, st.page_link, or other multipage-app v1 patterns.
• Always cache compute-intensive or expensive data-loading code. Use st.cache_data for serializable data and st.cache_resource for shared resources like API clients, raw connectors, and models; do not wrap st.connection, which is already cached. Include appropriate ttl and/or max_entries limits to prevent unbounded growth. Cache the expensive source data, then apply cheap interactive filters outside the cached function.
• Order scripts so fast UI (titles, layout, widgets) renders before slow computation. Streamlit streams elements top to bottom and temporarily greys out (marks stale) not-yet-redrawn elements from the previous run while a slow step is in progress, clearing each as the new run recreates it; put slow work last, reserve output slots with st.container(), or isolate slow sections in fragments.
• Use st.fragment for independent sections that should rerun separately from the rest of the app, such as auto-refreshing charts or controls that do not need to rerun the full page.