ContextQMD
Back to Streamlit

Streamlit visual design

lib/streamlit/.agents/skills/developing-with-streamlit/references/design.md

1.62.1.dev202608256.3 KB
Original Source

Streamlit visual design

Small touches that make apps feel polished.

Visual design works hand-in-hand with other references:

  • selection-widgets.md — Choosing the right widget (segmented control, pills, toggle)
  • data-display.md — Column config, sparklines, bordered metrics
  • layouts.md — Containers, alignment, dashboard cards
  • theme.md — Colors, fonts, and borders via config.toml

Colors and theming

Do not use custom CSS to polish an app unless the user explicitly asks for it. Set colors, fonts, and borders in .streamlit/config.toml instead. Native theming applies consistently across every element and survives Streamlit upgrades; CSS selectors target internal class names that can change.

python
# BAD: Injected CSS for a brand color
st.html("<style>.stButton button { background: #0969da; }</style>")
toml
# GOOD: Configure theme tokens in .streamlit/config.toml
[theme]
primaryColor = "#0969da"

Read theme.md for the full option set, ready-made theme configs, and the narrow escape hatch for when the user explicitly asks for CSS.

Page config

Set browser tab title, icon, and layout. Place this at the top of your script to avoid visual blinking:

python
st.set_page_config(
    page_title="My Dashboard",
    page_icon=":material/analytics:",
    layout="wide",  # Use "wide" for dashboards with lots of data
)

Layout options:

  • layout="centered" (default) → Best for most apps, content is constrained to a readable width
  • layout="wide" → Full-width, good for dashboards and data-heavy apps

Add a logo to the sidebar/header:

python
st.logo("logo.png")

Icons over emojis

Use Material Symbols for a cleaner, more professional look. Streamlit uses the Material Symbols icon set (not the older Material Icons).

python
# GOOD: Material Symbols
st.markdown(":material/settings:")
st.markdown(":material/calendar_today:")
st.markdown(":material/dashboard:")
st.markdown(":material/person:")

# SPARINGLY: Emojis for special occasions
st.markdown("Celebration! 🎉")

Format: :material/icon_name:

Find icons: https://fonts.google.com/icons

Full list of icons available in Streamlit: material_icon_names.py

Popular icons by category:

CategoryIcons
Navigationhome, arrow_back, menu, settings, search
Actionssend, play_arrow, refresh, download, upload, save, delete, edit
Statuscheck_circle, error, warning, info, pending
Datatable_chart, bar_chart, analytics, query_stats, database
Contentchat, code, description, article, folder
UIvisibility, build, tune, filter_list

Badges for status

For standalone badges:

python
st.badge("Active", icon=":material/check:", color="green")
st.badge("Pending", icon=":material/schedule:", color="orange")
st.badge("Deprecated", color="red")

For inline badges in text:

python
st.markdown("""
:green-badge[Active] :orange-badge[Pending] :red-badge[Deprecated] :blue-badge[New]
""")

Avoid the old verbose syntax:

python
# OLD (still works but cluttered)
st.markdown(":orange-background[:orange[Pending]]")

Spacing: remove dividers

Dividers (st.divider() or ---) look heavy. Just remove them—Streamlit's default spacing is usually enough.

python
# BAD
st.header("Section 1")
st.write("Content")
st.divider()  # Too heavy
st.header("Section 2")

# GOOD
st.header("Section 1")
st.write("Content")
st.header("Section 2")

If you genuinely need spacing:

python
st.space("small")  # Small gap
st.space("medium")  # Medium gap
st.space("large")  # Large gap
st.space(50)  # Custom pixels for fine-tuning

Don't systematically replace dividers with st.space()—it can look weird too.

Sentence casing

Use sentence casing for titles and labels. Title Case Feels Shouty.

python
# GOOD
st.title("Upload your data")
st.selectbox("Select a region", options)
st.button("Save changes")

# BAD
st.title("Upload Your Data")
st.selectbox("Select A Region", options)

Caption over info

st.info() is too heavy for simple informational text.

python
# GOOD: Lighter
st.caption("Data last updated 5 minutes ago")

# BAD: Too heavy
st.info("Data last updated 5 minutes ago")

When to use what:

  • st.caption → Simple info, metadata, timestamps
  • st.info → Important instructions
  • st.warning → Caution, potential issues
  • st.error → Errors that block progress
  • st.success → Confirmation of action
  • st.toast → Lightweight confirmation that auto-dismisses

Text alignment

Use text_alignment for text elements:

python
st.title("Centered title", text_alignment="center")
st.write("Right aligned", text_alignment="right")
st.caption("Justified text", text_alignment="justify")

Options: "left" (default), "center", "right", "justify"

Note: horizontal_alignment on containers positions elements but also sets their text_alignment. If you need different text alignment within a horizontally-aligned container, override text_alignment on the text element itself.

Icons in callouts and expanders

Material Symbols can make callouts and expanders look nicer:

python
st.info("Processing complete", icon=":material/check_circle:")
st.warning("Rate limit approaching", icon=":material/warning:")
st.error("Connection failed", icon=":material/error:")
st.success("Saved!", icon=":material/thumb_up:")

with st.expander("Settings", icon=":material/settings:"):
    st.write("Configure your preferences")

Other elements like st.button and st.tabs also support icons—worth considering when it adds clarity.

References