Grouped sidebar

Authored pages chunked into labeled sections — the Settings window. The pages work exactly like a single-tier app; section labels and dividers add visual structure when the destinations fall into categories.

How it works

add_header(text) adds a quiet, non-interactive section label; add_separator() adds a divider. The pages added after a header read as belonging to it — the label’s color and the extra top margin carry the grouping, so the items stay flush (no indentation).

shell.add_header("Account")
with shell.add_page("profile", text="Profile", icon="person"):
    ...
shell.add_header("Notifications")
with shell.add_page("email", text="Email", icon="envelope"):
    ...

Group consistently — put everything under headers, rather than sprinkling loose top-level items among sections. A pinned footer item is the conventional exception.

Example

"""Grouped sidebar — pages chunked into labeled sections (a Settings window).

``add_header`` adds a quiet section label and ``add_separator`` a divider; the
pages between read as a group. Settings screens are the canonical case — related
panes gathered under Account, Notifications, Advanced. Group *consistently*:
everything under a header, not loose items sprinkled among sections.
"""
import bootstack as bs

with bs.AppShell(title="Settings", size=(860, 580)) as shell:
    shell.commandbar.add_label("Settings", font="heading-md")
    shell.commandbar.add_spacer()
    shell.commandbar.add_button(icon="circle-half", on_click=bs.toggle_theme)

    shell.add_header("Account")
    with shell.add_page("profile", text="Profile", icon="person"):
        with bs.VStack(fill="both", expand=True, anchor_items="w", gap=8, padding=20):
            bs.Label("Profile", font="heading-lg")
            bs.Label("Your name, avatar, and bio.")
    with shell.add_page("security", text="Security", icon="shield-lock"):
        with bs.VStack(fill="both", expand=True, anchor_items="w", gap=8, padding=20):
            bs.Label("Security", font="heading-lg")
            bs.Label("Password and two-factor authentication.")

    shell.add_header("Notifications")
    with shell.add_page("email", text="Email", icon="envelope"):
        with bs.VStack(fill="both", expand=True, anchor_items="w", gap=8, padding=20):
            bs.Label("Email notifications", font="heading-lg")
    with shell.add_page("push", text="Push", icon="bell"):
        with bs.VStack(fill="both", expand=True, anchor_items="w", gap=8, padding=20):
            bs.Label("Push notifications", font="heading-lg")

    shell.add_header("Advanced")
    with shell.add_page("developer", text="Developer", icon="terminal"):
        with bs.VStack(fill="both", expand=True, anchor_items="w", gap=8, padding=20):
            bs.Label("Developer options", font="heading-lg")

    shell.navigate("profile")

shell.run()

When to use

Use a grouped sidebar when authored pages fall into a few clear categories. If you find yourself wanting a section that collapses to hide its items, that is a content concern rather than navigation — compose an Accordion inside a custom sidebar. If a “section” is really a long list of records, use Master–detail (list).