1. streamlit‑flexnav

streamlit-flexnav is a modular, folder‑driven navigation framework for Streamlit applications.
It automatically builds menus from your project structure and lets you extend them with metadata, icons, colors, RBAC, and custom behavior.

The project is actively evolving.
The first stable release will be v2.0.0.

• 1. streamlit‑flexnav
• 1.1. ✨ Features
• 1.2. 📦 Installation
• 1.3. 🚀 Quick Start
• 1.4. 🧭 Navigation Behavior
• 1.5. ⚙️ Configuration
• 1.6. 🧭 Example: __menu__.py (Menu Settings)
• 1.7. 📄 Example: Page Settings (inside a page module)
  • 1.7.1. Example 1
  • 1.7.2. Example 2
• 1.8. 🧩 Page Template Generator (FlexNav 2.0)
• 1.9. 🛠 CLI Tools
• 1.10. 📁 Project Structure
• 1.11. 🧪 Development
• 1.12. 📄 License
• 1.13. ⭐ Acknowledgements

---

1.1. ✨ Features

• Folder‑driven navigation — menus are generated from your directory structure
• Schema‑driven metadata — configure menus and pages using __menu__.py and PageStruct
• Automatic UI rendering — FlexNav handles menu rendering, active state, and routing
• Role‑based access control (RBAC) — restrict menus and pages by user roles
• Icons, colors, ordering, and collapsible groups
• CLI tools for inspection, linting, debugging, and scaffolding
• Plugin‑friendly architecture
• Fast, reproducible builds using uv

---

1.2. 📦 Installation

Install from PyPI:

pip install streamlit-flexnav

Or using uv:

uv add streamlit-flexnav

---

1.3. 🚀 Quick Start

See the full quickstart guide:

QUICKSTART.md

---

1.4. 🧭 Navigation Behavior

FlexNav automatically:

• Builds menu groups and pages from your folder structure
• Applies RBAC rules
• Highlights the active page
• Supports icons, dividers, and collapsible groups
• Integrates with Streamlit session state
• Orders menus and pages using order metadata

---

1.5. ⚙️ Configuration

FlexNav uses a unified configuration file:

See (QUICKSTART.md) for more information.

configs/admin/flexnav_config.yaml

Example:

flexnav:
  menupages: "demo_pages"
  env: "dev"

  authentication:
    mode: "none"
    local:
      users_file: "configs/users.yaml"

oauth:
  enabled: false
  provider: "google"
  client_id: ""
  client_secret: ""
  redirect_uri: "http://localhost:8501"
  scopes:
    - "openid"
    - "email"
    - "profile"

logging:
  to_file: false
  file_path: "logs"
  level: "INFO"

---

1.6. 🧭 Example: __menu__.py (Menu Settings)

Place this file inside any folder that represents a menu group.
FlexNav loads it automatically.

# __menu__.py
from streamlit_flexnav import MenuStruct

menu = MenuStruct(
    label="Sales Dashboard",
    order=20,
    icon="📊",
    color="#1E88E5",
    required_roles=["sales"],
    collapsed=True,
    description="KPIs, reports, and analytics for the sales team.",
)

This produces:

• A menu group labeled Sales Dashboard
• Sorted after groups with lower order
• Visible only to users with the sales role
• Styled with icon + color
• Collapsed by default
• All pages inside the folder inherit this group

---

1.7. 📄 Example: Page Settings (inside a page module)

Each page is a Python file.
FlexNav reads the metadata from a page() function and uses render() to draw the UI.

1.7.1. Example 1

import streamlit as st
from streamlit_flexnav.core.models.pagestruct import PageStruct

def page():
    return PageStruct(
        label="Finance",
        icon="🎨",
        order=2,
        required_roles=[],
        is_default=False,
        path=__file__,
    )

def render():
    st.title("Finance")
    st.write("You are on: finance")

1.7.2. Example 2

import streamlit as st
from streamlit_flexnav.core.models.pagestruct import PageStruct

def page():
    return PageStruct(
        label="Customer Overview",
        icon="📊",
        order=5,
        required_roles=["sales"],
        is_default=True,
        description="Overview of customer KPIs and segmentation.",
        path=__file__,
    )

def render():
    st.title("Customer Overview")
    st.write("This page shows customer KPIs and segmentation charts.")

---

1.8. 🧩 Page Template Generator (FlexNav 2.0)

A helper function for generating new pages:

def generate_page_template(path: str, label: str, icon: str = "📄", order: int | None = None):
    import os
    from textwrap import dedent

    os.makedirs(os.path.dirname(path), exist_ok=True)

    template = dedent(f"""
        import streamlit as st
        from streamlit_flexnav.core.models.pagestruct import PageStruct

        def page():
            return PageStruct(
                label="{label}",
                icon="{icon}",
                order={order if order is not None else "None"},
                path=__file__,
            )

        def render():
            st.title("{label}")
            st.write("This is the {label} page.")

        if __name__ == "__main__":
            render()
    """).strip() + "\n"

    with open(path, "w", encoding="utf-8") as f:
        f.write(template)

    return path

---

1.9. 🛠 CLI Tools

After installation, the CLI becomes available:

flexnav

Commands:

config   FlexNav configuration tools
menu     Menu inspection tools
menuviz  Visualize and inspect FlexNav menu structure
pages    Page inspection tools
lint     FlexNav linter
doctor   FlexNav health checks
setup    Create a new FlexNav application structure
debug    Debugging tools

Each command provides its own help:

flexnav doctor --help

---

1.10. 📁 Project Structure

src/streamlit_flexnav/
  core/          # Loaders, runtime models, RBAC, ordering logic
  ui/            # Streamlit UI components
  tools/         # CLI tools

See API_REFERENCE.md for full details.

---

1.11. 🧪 Development

Clone the repository:

git clone https://github.com/informatie/streamlit-flexnav
cd streamlit-flexnav

Set up the environment:

uv venv
uv sync
source .venv/bin/activate

---

1.12. 📄 License

MIT License — see LICENSE for details.

---

1.13. ⭐ Acknowledgements

FlexNav is actively evolving.
Upcoming enhancements include:

• RBAC improvements
• Folder and page validation
• Drag‑and‑drop menu/page ordering
• Admin UI for editing menu and page settings
• File system watcher for live reload
• SSO and OAuth integrations
• User‑defined menu settings

---