streamlit-rail-nav

A collapsible icon-rail sidebar navigation for Streamlit that expands on hover — pure Python, no frontend build.

Live demo →

Inspired by the archived Socvest/streamlit-on-Hover-tabs project, but implemented differently under the hood: instead of rendering tabs inside an iframe component, streamlit-rail-nav renders native Streamlit sidebar widgets (st.page_link, st.button, st.text_input) and restyles the native stSidebar into a rail via injected CSS. That keeps navigation client-side, preserves session state, and needs no JS toolchain.

Features

• Sidebar collapses to an icon rail, expands smoothly on hover
• Fully themeable: colors, sizes, widths, gaps, transitions
• Brand block: logo on expand, icon on rail, automatic light/dark variant pick
• Item kinds: link, badge_link, separator, spacer, header, theme_toggle, search, upgrade_card, user_profile
• Per-item access levels (normalized for you; filtered caller-side)
• Eight built-in theme presets
• Plain-dict config — round-trips cleanly with JSON persistence

Install

pip install streamlit-rail-nav

Quickstart

import streamlit as st
from streamlit_rail_nav import render

st.set_page_config(layout="wide", initial_sidebar_state="expanded")

render({
    "items": [
        {"kind": "link", "label": "Home", "icon": "home", "page": "app.py"},
        {"kind": "badge_link", "label": "Data", "icon": "table",
         "page": "pages/Data.py", "badge": "New"},
        {"kind": "separator"},
        {"kind": "header", "label": "Workspace"},
        {"kind": "search", "label": "Quick search", "icon": "search"},
        {"kind": "theme_toggle", "label": "Dark mode", "icon": "dark_mode"},
        {"kind": "user_profile", "name": "Ada Lovelace",
         "subtitle": "Pro trial"},
    ],
    "footer": None,
}, footer="2026 | My App")

Icons use Google Material Icons names (:material/<name>: shortcodes work too).

API

render(
    config=None,                # dict matching the settings schema
    *,
    base_path=None,             # dir for resolving relative logo/icon paths
    on_theme_toggle=None,       # Callable[[], None]
    on_search=None,             # Callable[[str], None]
    on_upgrade_click=None,      # Callable[[], None]
    footer=None,                # caption text at the bottom of the sidebar
)

config is normalized over DEFAULT_RAIL_SETTINGS — pass only the keys you want to override. For local logo_src/icon_src files, pass base_path=Path(__file__).parent; http(s):// URLs work without it.

Style keys

Light/dark brand variants are picked automatically from the sidebar background luminance.

Item kinds

access accepts public / logged_in / admin and is preserved by normalization, but the package never filters on it — filter caller-side:

items = [i for i in cfg["items"]
         if can_access(i.get("access", "public"), current_user)]
render({**cfg, "items": items})

Theme presets

from streamlit_rail_nav import THEME_PRESETS — eight palettes: Anthropic Style, Ocean Palette, Corpus Analytica, Navy Gold Aqua, Cadet Yam, Matcha Almond, Black & White (Light), Black & White (Dark).

Every preset passes WCAG AA contrast (>= 4.5:1) for both the resting state (sidebar_bg/sidebar_text_color) and the hover state (sidebar_hover_bg/sidebar_hover_text_color). sidebar_active_bg is a subtle tint close to sidebar_bg rather than a loud accent color, so the persistent "selected page" background never fights with the label text; sidebar_focus_outline carries the accent color for the selected item's icon instead.

render({**THEME_PRESETS["Ocean Palette"], "items": [...]})

Caveats

• Selectors rely on Streamlit data-testid attributes (not a stable public API). Verified on Streamlit 1.57; pinned streamlit>=1.57,<2.
• Badges are positioned via nth-of-type on sidebar element containers. Call render() before emitting other widgets into st.sidebar, or badge positions shift.
• The rail effect needs initial_sidebar_state="expanded" in st.set_page_config.

Demo

Try it live: st-rail-nav.streamlit.app

Or run it locally:

pip install -e .
streamlit run examples/demo/demo_app.py

Development

pip install -e ".[dev]"
pytest
black . && ruff check .
python -m build

Author

Built by Bernhard Zechmann (@aizech) at Corpus Analytica.

License

MIT — see LICENSE. Derived conceptually from Socvest/streamlit-on-Hover-tabs (MIT)