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.
• Never loop the app script with while True or with time.sleep() followed by st.rerun(). For live-updating dashboards, use @st.fragment(run_every=...) so only that section reruns on a timer.
• Use st.form to batch related inputs and rerun only on submit, especially when intermediate widget changes would trigger expensive work. If some inputs must rerun to update others (for example, dependent options), use on_change="ignore" on the remaining inputs instead of a form (advanced; see "Skip reruns on individual widgets" in references/performance.md).
• Do not put expensive work unguarded inside st.tabs, st.expander, or st.popover: hidden, collapsed, or closed content still computes on every rerun, and caching doesn't change that. Pass on_change="rerun" and render each body only when the container's .open is True, or switch to st.segmented_control or st.toggle with an if.
• Use st.secrets for credentials. Never hard-code secrets in app code, never commit .streamlit/secrets.toml, and use parameterized queries for user-provided values.
• Prefer Vega-based charts (st.altair_chart, st.line_chart, st.area_chart, st.scatter_chart, st.bar_chart, st.vega_lite_chart) over st.pyplot and Plotly. Use st.echarts_chart when you already have an Apache ECharts option or a pyecharts chart.
• Prefer st.segmented_control over st.radio(..., horizontal=True).
• For about 2–5 options, keep them visible instead of in a dropdown: st.segmented_control for a single choice and st.pills(..., selection_mode="multi") for several. Use st.selectbox or st.multiselect for longer lists.
• Use st.menu_button for a button that opens a short list of one-shot actions. Do not build one from st.popover with buttons or from st.selectbox.
• Initialize st.session_state in one clear place, avoid module-level mutable state for per-user data, and set widget key values when widgets repeat, parameters change dynamically, or code needs programmatic access.
• Element keys must be unique across a run, which in a multipage app spans the entrypoint and the current page. In loops, derive keys from a stable item ID (for example, key=f"done_{item.id}"); duplicates raise StreamlitDuplicateElementKey.
• Keep page files as direct scripts; do not wrap page bodies in functions. Move shared business logic into modules.
• Type-check edited Python files with ty (recommended) or mypy, using the project's configured checker if it has one.

Proactively Look Up API Details

When selecting a Streamlit command, discovering functionality that may be newer than the agent's knowledge cutoff, validating available functionality, or using unfamiliar parameters, proactively look up the relevant local docs before coding:

streamlit docs st.<command>

Run this with the Streamlit installation relevant to the app being edited. Use references/api-reference.md to discover available public st commands and namespaces, then use streamlit docs st.<command> for exact signatures, parameters, and docstrings.

When annotating Streamlit-owned values returned by commands or stored in Session State, import the curated public types from streamlit.typing (also available as st.typing) instead of their internal implementation modules. See references/api-reference.md for the available types.

Workflow

Step 1: Locate the Streamlit source code
    ↓
Step 2: Identify task type and load appropriate reference(s)
    ↓
Step 3: Apply guidance from reference to edit code
    ↓
Step 4: Check if app is running and offer to run it

Step 1: Locate the Streamlit Source Code (if needed)

Goal: Identify the app file(s) to edit. Skip this step if already clear from context.

When to skip:

• User mentioned a specific file path (e.g., "edit src/app.py")
• User has file(s) already in conversation context
• Working directory has an obvious single entry point (app.py, streamlit_app.py)

When to search:

• User says "my streamlit app" without specifying which file
• Multiple Python files exist and it's unclear which is the entry point

If searching is needed:

1. Quick scan for Streamlit files:

   grep -rl 'import streamlit\|from streamlit' --include='*.py' . 2>/dev/null | head -10
   

2. Apply entry point heuristics (in priority order):

   • streamlit_app.py at root → this is the entry point (canonical name)
   • app.py at root → likely entry point
   • File using st.navigation → entry point for multi-page apps
   • Single .py file at root with streamlit import → entry point
   • Files in pages/ or app_pages/ subdirectory → NOT entry points (these are sub-pages)

3. If entry point is obvious → use it, no confirmation needed

   Example: Found streamlit_app.py and pages/metrics.py → use streamlit_app.py

4. Only ask if genuinely ambiguous (e.g., multiple root-level candidates, none named streamlit_app.py):

   Found multiple potential entry points:
   - dashboard.py
   - main.py
   
   Which is your main app?
   

Output: Path to the main Streamlit source file(s)

Step 2: Identify Task Type and Route to Reference

Goal: Determine what the user needs and load the appropriate guidance.

Reference routing table

Use this routing table to select reference(s). Always read the reference file before making changes.

All file paths below are relative to this skill's directory (streamlit/.agents/skills/developing-with-streamlit/).

Fallback — "this widget doesn't exist in Streamlit":

If the user asks for a UI element or interaction that has never been part of Streamlit's API and cannot be built with any combination of native widgets (e.g., drag-and-drop, canvas drawing, custom interactive visualizations), route to the CCv2 reference (references/custom-components-v2.md). Do not route to CCv2 for UI that Streamlit already provides (e.g., st.segmented_control, st.menu_button, st.echarts_chart); check references/api-reference.md first. If the native command is newer than the app's installed Streamlit, suggest upgrading.

Common combinations:

For beautifying/improving an app, read in order:

1. references/theme.md — brand colors, light/dark, sidebar, padding (prefer config over CSS)
2. references/design.md — icons, hierarchy, micro-polish
3. references/layouts.md
4. references/selection-widgets.md

Configure themes via .streamlit/config.toml (not CSS unless the user asks). In theme.md, read Choose a config shape, Where to put keys, and Cheat sheet first; open deeper sections only when the ask needs them.

For building a dashboard, read:

1. references/dashboards.md
2. references/data-display.md
3. references/theme.md — when the user wants a branded or polished look, pair with a theme (theme.base for a shared brand file/URL; dense-dashboard when the app should keep the appearance toggle and use compact padding)

IMPORTANT - Use templates:

When creating a new dashboard app, prefer starting from a template in assets/templates/apps/:

• If a template closely matches the request, copy it and adapt:
  • dashboard-metrics — KPI cards with time-series charts
  • dashboard-companies — company/entity comparison
  • dashboard-compute — resource/credit monitoring
  • dashboard-feature-usage — API endpoint usage analytics
  • dashboard-seattle-weather — public dataset exploration
  • dashboard-stock-peers — financial peer analysis
  • dashboard-background-report — responsive page while a slow query loads in the background
• If no template is a close match, start from scratch but borrow relevant patterns from the templates (e.g., caching with @st.cache_data, filter_by_time_range(), st.set_page_config(), chart utilities, layout structure)
• When the user wants a branded or polished look, pair the dashboard with a theme from assets/templates/themes/configs/ (dense-dashboard only if the app should keep the appearance toggle and use compact padding), or point theme.base at an existing shared brand file or URL
• See assets/templates/apps/README.md for template descriptions

When editing an existing app, use templates as reference for best practices:

• Check assets/templates/apps/ for caching patterns, layout structure, and data-loading patterns
• Apply consistent patterns from templates to improve the existing code

When applying a custom theme, use a config from assets/templates/themes/configs/:

• Prefer theme.base (shared corporate/brand TOML or URL) when several apps should inherit the same brand tokens, then override per app for layout-specific tweaks
• Defaults: shadcn-dual for a general brand with the appearance toggle, dense-dashboard for KPI layouts with compact padding and the toggle, or locked shadcn (light) / vscode (dark). Other single-mode themes are aesthetic variants
• Copy the chosen file to the app's .streamlit/config.toml (or point theme.base at a shared file)
• Themes include custom fonts via Google Fonts
• See assets/templates/themes/README.md for picker defaults and the full theme list

For performance optimization, read:

1. references/performance.md

Step 3: Apply Guidance to Edit Code

Goal: Make changes to the Streamlit app following reference best practices.

Actions:

1. Apply the patterns and recommendations from the loaded reference(s)
2. Make edits to the source file(s) identified in Step 1
3. Preserve existing functionality while adding improvements
4. Type check the edited Python files with ty (recommended) or mypy, using the project's configured checker if it has one. Streamlit's public API is typed and tested with both, so wrong API use is reported before the app runs. Install and run notes are in references/environment-setup.md; an example is in references/best-practices.md.

Step 4: Check Running Apps and Offer to Run

Goal: Help the user see their changes by checking if their app is running.

Actions:

1. Check for running Streamlit apps on ports 850*:

   lsof -nP -iTCP -sTCP:LISTEN 2>/dev/null | grep -i python | awk '{print $2, $9}' | grep ':85' || echo "No Streamlit apps detected on ports 850*"
   

2. Present findings to user:

   If app is running:

   Found Streamlit app running:
   - PID: [pid] at http://localhost:[port]
   
   Your changes should be visible after a page refresh (Streamlit hot-reloads on file save).
   

   If no app is running:

   No Streamlit app detected on ports 850*.
   
   Would you like me to run the app? I can start it with:
     streamlit run [app_file.py]
   

3. If user wants to run the app, start it:

   streamlit run [path/to/app.py] --server.port 8501
   

Stopping Points

• Step 4: Ask before starting the Streamlit app

Resources

• Streamlit API Reference
• Streamlit Gallery