Custom sidebar

A bespoke sidebar you build by hand — a faceted filter panel, a tool palette, a layer list. The escape hatch for when the sidebar isn’t navigation at all, so none of the built-in providers fit.

How it works

custom_nav() claims the sidebar as a blank container and returns it as a context manager — fill it with any widgets. You then drive the content area yourself through shell.content (also a container), typically by binding widgets to a Signal. Nothing is added or collapsed automatically — the sidebar is yours to fill and manage.

with shell.custom_nav():
    bs.Label("Filters", font="heading-md")
    bs.SelectButton(options=["All", "Electronics", "Home"], signal=category)

with shell.content:
    bs.Label("Results", font="heading-lg")
    bs.Label(textsignal=results)

Because there are no pages, navigate() does not apply — the content is whatever you put there and update.

Example

"""Custom sidebar — a bespoke sidebar the providers can't express (search filters).

``custom_nav()`` claims the sidebar as a blank container you fill with any widgets,
and you drive the content area yourself via ``shell.content``. A faceted filter
sidebar — category, price, rating — feeding a results area is the classic case:
it isn't navigation, so none of the nav providers fit. Reach for ``custom_nav()``
only when ``page_nav`` / ``list_nav`` / ``tree_nav`` cannot express your sidebar.
"""
import bootstack as bs

PRODUCTS = [
    {"name": "Wireless Mouse", "category": "Electronics", "price": 24},
    {"name": "Desk Lamp", "category": "Home", "price": 39},
    {"name": "Mechanical Keyboard", "category": "Electronics", "price": 89},
    {"name": "Throw Pillow", "category": "Home", "price": 19},
    {"name": "USB-C Hub", "category": "Electronics", "price": 45},
]

with bs.AppShell(title="Shop", size=(900, 580)) as shell:
    with shell.add_toolbar() as bar:
        with bar.add_menu("File") as file:
            file.add_action("New order", shortcut="Mod+N", on_click=lambda: None)
            file.add_divider()
            file.add_action("Quit", shortcut="Mod+Q", on_click=shell.close)
        bar.add_spacer()
        bar.add_button(icon="search", on_click=lambda: None)
        bar.add_button(icon="cart", on_click=lambda: None)
        bar.add_theme_toggle()

    category = bs.Signal("All")
    max_price = bs.Signal(100)
    results = bs.Signal("")

    def recompute(*_):
        matches = [
            p for p in PRODUCTS
            if (category() == "All" or p["category"] == category())
            and p["price"] <= max_price()
        ]
        lines = [f"{p['name']} — ${p['price']}" for p in matches]
        results.set("\n".join(lines) if lines else "No products match.")

    # A bespoke filter sidebar — not navigation, so custom_nav() is the right tool.
    with shell.custom_nav():
        with bs.Column(horizontal_items="left", gap=12, padding=(16, 10)):
            bs.Label("Filters", font="heading-md")
            bs.Label("Category", font="caption")
            bs.SelectButton(options=["All", "Electronics", "Home"], signal=category)
            bs.Label("Max price", font="caption")
            bs.Slider(min_value=10, max_value=100, signal=max_price)

    # Drive the content region by hand from the filter signals.
    with shell.content:
        with bs.Column(horizontal_items="left", gap=8, padding=(16, 10)):
            bs.Label("Results", font="heading-lg")
            bs.Label(textsignal=results)

    category.subscribe(recompute)
    max_price.subscribe(recompute)
    recompute()

shell.run()

When to use

Reach for a custom sidebar only when page_nav, list_nav, and tree_nav genuinely can’t express what you need — a sidebar that isn’t a navigation list. If you want collapsible sections of navigation, prefer a grouped sidebar (or an Accordion inside the panel for collapsible content). For records, use a list or tree master–detail.