customizing-streamlit-theme

name	customizing-streamlit-theme
description	Customizing Streamlit styling. Use for: theme colors, button styling, widget backgrounds, CSS customization. Covers config.toml, key= for CSS targeting, st.html(), .st-key-X selectors.
license	Apache-2.0

Streamlit theming

Custom colors and styling. Stick to config.toml—avoid CSS.

Basic theme

Configure your app's colors in .streamlit/config.toml:

[theme]
base = "light"  # or "dark"
primaryColor = "#FF4B4B"
backgroundColor = "#FFFFFF"
secondaryBackgroundColor = "#F0F2F6"
textColor = "#262730"
font = "sans serif"

Core options:

• base → Start from "light" or "dark" theme
• primaryColor → Interactive elements (buttons, links, sliders)
• backgroundColor → Main content area
• secondaryBackgroundColor → Sidebar and widget backgrounds
• textColor → All text
• font → "sans serif", "serif", or "monospace"

Separate light and dark themes

Define both themes and let users choose:

[theme.light]
primaryColor = "#FF4B4B"
backgroundColor = "#FFFFFF"
secondaryBackgroundColor = "#F0F2F6"
textColor = "#262730"

[theme.dark]
primaryColor = "#FF6B6B"
backgroundColor = "#0E1117"
secondaryBackgroundColor = "#262730"
textColor = "#FAFAFA"

When both are defined, users can switch between them in the settings menu.

Sidebar styling

Style the sidebar separately:

[theme]
base = "light"
primaryColor = "slateBlue"
backgroundColor = "mintCream"

[theme.sidebar]
backgroundColor = "aliceBlue"
secondaryBackgroundColor = "skyBlue"

Detect current theme

if st.context.theme.base == "dark":
    # Dark mode specific logic
    chart_color = "#FF6B6B"
else:
    chart_color = "#FF4B4B"

Use st.context.theme.base to detect if the user is in light or dark mode.

Avoid custom CSS/HTML

Custom CSS makes apps hard to maintain and breaks with Streamlit updates.

# BAD: Will break with updates
st.markdown("""
<style>
.stButton button {
    background-color: #FF4B4B;
    border-radius: 20px;
}
</style>
""", unsafe_allow_html=True)

# GOOD: Use config.toml
# [theme]
# primaryColor = "#FF4B4B"

When you must use CSS

If you absolutely need custom styling, use the key= parameter to create targetable CSS classes.

st.text_input("Username", key="username")
st.button("Submit", key="submit")

Generated CSS classes:

.st-key-username { ... }
.st-key-submit { ... }

Apply styles:

st.html("""
<style>
.st-key-submit button {
    width: 100%;
}
</style>
""")

Only use this as a last resort.

References

• Theming
• st.context