Shell — Sidebar

Import and example

use maud::html;
use maud_ui::blocks::shell::sidebar::{self, MobileNavigation, NavGroup, NavItem, Props};
sidebar::render(Props {
    id: "reservation-app".into(),
    brand: html! { "Garden House" },
    header: Some(html! { label { "Workspace" select { option { "Front desk" } } } }),
    nav_groups: vec![NavGroup {
        label: Some("Operations".into()),
        items: vec![NavItem { label: "Reservations".into(), short_label: Some("Stays".into()), href: "/reservations".into(), icon: None, badge: Some("48".into()), ..Default::default() }],
    }],
    active_path: "/reservations".into(),
    mobile_navigation: MobileNavigation::Tabs,
    children: html! { p { "Your page content" } },
    ..Default::default()
});

NavItem fields: label/href: String, short_label: Option, icon: Option, badge: Option, children: Vec. Use ..Default::default() for optional fields. Nested items indent without a rail. A group's label names its accessible group. Tabs uses the first four flattened destinations plus More; any later current destination marks More as current. All destinations remain in the drawer. Put your frequent destinations first. The optional header can use a labelled input with data-mui-nav-search for local destination filtering.

Navigation preferences

Labeled groups use native details/summary and remember their state under mui-nav-group:{navigation-id}:{index}:{label}. A current destination opens its group on route entry unless the user has explicitly saved it closed. Sidebar collapse uses mui-shell-rail:{id}; storage failures fall back to rendered defaults. Keep IDs stable and unique, and keep group ordering stable to retain preferences. The desktop icon rail appears at 64rem, with full accessible labels and title hints. It temporarily opens groups to retain every icon and restores their remembered state when expanded or moved into the phone drawer. Inputs in the header and arbitrary footer controls are hidden while collapsed; place essentials in the page bar as well.

Header and footer composition

Pass app_header::render(...) and app_footer::render(...) into the corresponding shell slots. Their empty defaults emit no wrappers. Pass page_header::Props for breadcrumbs, native search or a custom command trigger, actions and switchers. The shell page renders this full composition in both themes. The landing example supports client-side guest filtering, row selection and adding a local example reservation; its data is fictional and never persisted or sent to a booking system.

Below 64rem, a supplied page header moves its original breadcrumb and actions/switchers into the drawer. The page bar keeps the menu, current title and search icon. At wider sizes controls return to the header; the native search input is visible. Without enhancement, the native navigation details and Settings disclosure retain access to every destination and control. The shared example uses “Reservations” and one guest-search field; the header shortcut focuses that field, and the sidebar contains no duplicate search.

Presentation states (0.10.1)

Props::state: maud_ui::blocks::state::State defaults to Ready. Loading { message } shows skeletons; Empty { message, action } and Error { message, retry } provide distinct recovery paths; Disabled { reason } retains admitted content in an inert subtree with an external reason. Loading, empty and error omit ready content. Inert disables interaction, not server authorization or submission of values by an enclosing form. Each live API page shows all four states together. Add state: Default::default() to exhaustive Props literals.

Typed identity (0.11.0)

brand_mark: Option<shell::brand_mark::Props> defaults to None and overrides the raw brand slot when supplied. The mark contains a logo, wordmark and optional tagline. Add the new field to exhaustive Props literals. See brand mark.

State::Absent (0.11.0) means no input/rule was declared and emits nothing. Keep any caller-owned section heading inside the same conditional. Use Error only for a declared operation that failed; never show an unconfigured-rule message to the user.

Still frame and current navigation (0.12.0)

Density never moves the frame. The root shell uses min-height: 100dvh and rows auto 1fr auto. Its .mui-block--shell__body contains a stretching .mui-block--shell__sidebar-column and the existing main region. Background and hairline belong to the column; the original sidebar is the sticky, independently scrolling inner node. Drawer close restores that node into its column. Embedded previews deliberately keep a 32rem minimum. See shell frame for all --mui-shell-* tokens and short/long fixtures.

The current item has a flat tint, zero corner radius and a 2px accent bar at the column edge. Nested labels indent inside the row so the bar stays aligned. Exactly one item retains aria-current="page". Its group gets data-contains-current="true"; the parent label uses --mui-text-primary, weight 600, and an accent chevron, with no fill. Group collapse does not erase this state. The primitive sidebar uses the same presentation.

Content is a stack with one --mui-stack-gap (16px) and no added child block margins. Use .mui-page-stack inside caller-owned wrappers. Put per-page density on that content container, or retain the document setting; shell spacing and type stay fixed. Existing Rust Props remain compatible. Custom direct-child CSS for the old sidebar position must target the new body/column; update CSS and JS together.

Review short and long fixtures after running cargo run --example frame_fixture.