Introduction
Streamlit’s default look is fine for prototypes but feels generic for production. Theming + custom CSS can transform it into something that looks like a real product — without leaving Python.
This post covers config.toml themes, injecting CSS, fonts, dark mode, and the tricks that matter.
Level 1: config.toml theme
Create .streamlit/config.toml:
[theme]
primaryColor = "#3b82f6"
backgroundColor = "#ffffff"
secondaryBackgroundColor = "#f1f5f9"
textColor = "#0f172a"
font = "sans serif"
[server]
headless = true
That’s it — Streamlit reads this on startup and applies the theme globally. No code changes.
Dark mode
[theme]
base = "dark"
primaryColor = "#60a5fa"
backgroundColor = "#0f172a"
secondaryBackgroundColor = "#1e293b"
textColor = "#e2e8f0"
Or let users toggle by setting base = "dark" and providing a light variant. Streamlit doesn’t auto-toggle; you’d swap config files or use CSS.
Level 2: Inject custom CSS
import streamlit as st
st.markdown("""
<style>
/* Hide Streamlit branding */
#MainMenu {visibility: hidden;}
footer {visibility: hidden;}
header {visibility: hidden;}
/* Custom button style */
.stButton > button {
border-radius: 8px;
font-weight: 600;
transition: all 0.2s;
}
.stButton > button:hover {
transform: translateY(-1px);
box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}
</style>
""", unsafe_allow_html=True)
unsafe_allow_html=True is required. Put this at the top of every page (or in a shared utils.py function called on each page).
Level 3: Google Fonts
st.markdown("""
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800&display=swap" rel="stylesheet">
<style>
html, body, [class*="css"] {
font-family: 'Inter', sans-serif;
}
h1, h2, h3 {
font-weight: 800;
letter-spacing: -0.02em;
}
</style>
""", unsafe_allow_html=True)
Fonts load from Google’s CDN. Use font-display: swap (included via display=swap) to avoid FOIT.
Level 4: Custom component styling
Target Streamlit’s CSS classes (they’re stable but undocumented — inspect with DevTools):
/* Sidebar */
section[data-testid="stSidebar"] {
background-color: #f8fafc;
border-right: 1px solid #e2e8f0;
}
/* Metric cards */
[data-testid="stMetric"] {
background: white;
border: 1px solid #e2e8f0;
border-radius: 12px;
padding: 16px;
}
/* Dataframe */
.stDataFrame {
border-radius: 8px;
overflow: hidden;
}
/* Tabs */
.stTabs [data-baseweb="tab-list"] {
gap: 8px;
}
.stTabs [data-baseweb="tab"] {
border-radius: 8px;
padding: 8px 16px;
}
Level 5: Dark mode toggle
Streamlit doesn’t have a built-in dark mode toggle (yet). Build one with CSS variables:
import streamlit as st
if "dark" not in st.session_state:
st.session_state.dark = False
if st.toggle("Dark mode", value=st.session_state.dark):
st.session_state.dark = True
else:
st.session_state.dark = False
theme_css = """
<style>
:root {
--bg: #ffffff;
--text: #0f172a;
--card: #f8fafc;
}
.dark {
--bg: #0f172a;
--text: #e2e8f0;
--card: #1e293b;
}
.stApp { background: var(--bg); color: var(--text); }
</style>
"""
st.markdown(theme_css, unsafe_allow_html=True)
For a full dark mode, pair with a config.toml dark variant and swap via a settings page.
Level 6: Hide Streamlit chrome
For a cleaner, “app-like” feel:
/* Hide the Streamlit header, footer, and menu */
#MainMenu {visibility: hidden;}
footer {visibility: hidden;}
header {visibility: hidden;}
/* Hide the "Made with Streamlit" badge */
.viewerBadge_container__1QSob {display: none;}
/* Hide the deploy button */
.stDeployButton {display: none;}
Level 7: Custom loading spinner
.stSpinner > div {
border-color: #3b82f6 transparent transparent transparent;
}
Or use st.skeleton (see Streamlit 2026 features) for animated placeholders.
A reusable theming helper
# theme.py
import streamlit as st
def apply_theme():
st.markdown("""
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800&display=swap" rel="stylesheet">
<style>
#MainMenu, footer, header {visibility: hidden;}
html, body, [class*="css"] { font-family: 'Inter', sans-serif; }
.stButton > button { border-radius: 8px; font-weight: 600; }
[data-testid="stMetric"] { background: #f8fafc; border: 1px solid #e2e8f0;
border-radius: 12px; padding: 16px; }
</style>
""", unsafe_allow_html=True)
Call apply_theme() at the top of every page. One source of truth.
Common mistakes
- CSS not applying — Streamlit’s classes change between versions. Inspect with DevTools and update selectors.
- Forgetting
unsafe_allow_html=True— without it, the CSS renders as text. - Injecting CSS after content — put
st.markdown(..., unsafe_allow_html=True)at the top of the script. - Over-styling — too much CSS makes the app fragile. Use
config.tomlfor colors, CSS for layout tweaks. - Not testing dark mode — if you support dark mode, test both themes.
Key Concepts
config.toml= theme colors, fonts, server settingsst.markdown(..., unsafe_allow_html=True)= inject CSS/HTML- CSS selectors = target Streamlit’s internal classes
- Google Fonts = custom typography via CDN
- Dark mode = CSS variables + toggle
What to Try Next
- Theme your admin panel to match your brand.
- Add a dark mode toggle to your dashboard.
- Combine with multipage apps — apply theme globally.
- Use Streamlit 2026 features (
st.skeleton) for loading states.
FAQ
Streamlit theming vs custom React frontend?
Theming = quick, stays in Python, limited control. Custom React frontend = full control, more work. Start with theming; migrate to React only when you hit Streamlit’s limits.
Does custom CSS break on Streamlit updates?
Sometimes — Streamlit’s internal class names change. Pin your Streamlit version in requirements.txt and test before upgrading.
Can I use Tailwind in Streamlit?
Not natively. You’d need to inject the Tailwind CDN and use utility classes in st.markdown. It works but is hacky. For serious Tailwind usage, build a React frontend instead.