st-theme

What it is and what it does

st-theme is a Streamlit component that queries the active theme of a running Streamlit app and returns it as a dictionary of style settings. It integrates directly into a Streamlit app's frontend to detect whether the user has selected light or dark mode, and updates the returned value whenever the user manually changes the theme after the app is running.

The package is designed to be lightweight and non-intrusive: by default it applies a CSS adjustment to remove the empty space that Streamlit normally reserves for rendered components, since st-theme only communicates with the frontend and renders nothing visible. This behavior can be disabled via the adjust parameter if it conflicts with your app's layout. The main gotcha is a known browser-dependent timing issue where the theme may not be returned immediately on first load, though it updates normally when the user switches themes afterward.

Use it for:

• Dynamically style a Streamlit app's custom content based on whether the user has selected light or dark mode
• Detect the initial theme setting to apply a fallback configuration when st-theme returns None on first load
• Build theme-aware custom components that respond to the active Streamlit theme without requiring manual user input
• Log or track theme preferences in a Streamlit analytics or monitoring system

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Detects and returns the active theme (light or dark) of a running Streamlit app, updating dynamically when the user changes the theme.

Yes, with conditions. Install if you need to detect and respond to Streamlit's active theme in your app and can work around the known initial-load timing issue by providing a fallback. The low install friction, permissive license, and stable classifier make it straightforward to add. However, the 833-day maintenance gap means no recent bug fixes or Streamlit version updates—verify compatibility with your Streamlit version before relying on it in production.

Install

st-theme on PyPI

pip install st-theme

uv add st-theme

poetry add st-theme

Installing st-theme

Before you install

Low friction: pure Python wheel with only streamlit as a runtime dependency. Maintenance is dormant—last release was 833 days ago and the repository shows no recent activity, though it remains unarchived and marked Production/Stable.

License in practice

MIT License (permissive): you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart

pip install st-theme

import streamlit as st
from st_theme import st_theme

theme = st_theme()
st.write(theme)

Requires Streamlit 1.20+. The CSS adjustment feature depends on browser support for the :has pseudo-class; initial theme detection may return None on first load due to a known browser-dependent timing issue.

Verify before relying

• Whether the known timing bug (theme returning None on initial load) has been resolved in version 1.2.3
• Current compatibility with Streamlit versions beyond 1.20 given 833 days since last release
• Whether the :has pseudo-class browser compatibility limitation affects a significant portion of target users

Package facts

Evidence: st_theme-1.2.3-py3-none-any.whl

Tags

More Application Frameworks packages