Page Layouts

Overview

The sidebar (src/layout/Sidebar.tsx) is the primary in-app navigation. It reads from a single menu definition (src/data/menu.ts) and renders in one of four display modes driven by LayoutConfig:

• Default — the standard full-width panel (16rem).
• Minified — a 5rem icon rail that hover-expands to the full panel (overlaying content, no reflow).
• Dual — a 4rem icon rail of menu sections plus a secondary panel showing the active section.
• Header-only — the sidebar is hidden entirely; navigation moves into the header.

On top of the tree it layers live search, favorites/pinning, numeric count badges, a presence user card footer, and a single-open accordion that auto-opens the active branch at any nesting depth. Below lg the sidebar becomes an animated mobile drawer regardless of mode.

Navigation is data-driven: menu.ts is the single source of truth for both the sidebar and the auto-derived breadcrumbs, and any menu leaf without a matching route automatically renders a titled placeholder (see Architecture).

Architecture & files

The mode is selected by the same data-* attributes AppLayout sets on .app-shell (data-min-sidebar, data-dual-sidebar, data-header-only) — see Layout & Shell.

Usage

You don't render the sidebar directly — AppLayout does. You interact with it by:

Switching modes is a config change (from the customizer, Layout Settings, or useLayout().update):

import {useLayout} from '@/context/LayoutContext'
 
function SidebarModeButtons() {
    const {update} = useLayout()
    return (
        <>
            {/* enabling one mode clears the others (mutually exclusive) */}
            <button onClick={() => update({minSidebar: true, dualSidebar: false, headerOnly: false})}>Minified</button>
            <button onClick={() => update({dualSidebar: true, minSidebar: false, headerOnly: false})}>Dual</button>
            <button onClick={() => update({headerOnly: true, minSidebar: false, dualSidebar: false})}>Header only</button>
        </>
    )
}

MenuItem (src/data/menu.ts)

MenuSection (src/data/menu.ts)

useFavorites() (src/hooks/useFavorites.ts)

navBadges (src/data/navBadges.ts)

A Record<string, number> keyed by route path. The rendered count animates via AnimatedNumber. Seeded mock values include /apps/contacts: 4 (pending applications). In a real app these would come from the API.

The four sidebar modes

The three are mutually exclusive — enabling one clears the others.

Search / filter

SidebarSearch renders a live filter box. Typing filters the whole flattened leaf set (allLeaves) and highlights the matched substring via a <mark>; an empty result shows a nav:noResults message. The box carries the nav-label/nav-search classes so it fully collapses in the minified rail and reappears on hover-expand.

Favorites / pinning

Each leaf shows a hover-star (visible on hover or when pinned). Clicking it toggles the path in useFavorites (a useSyncExternalStore store persisted to localStorage('nav-favorites')), and every star

• the synthesized "Favorites" section update live.

• First-time seed: DEFAULT_FAVORITES = ['/layout-settings'] so the section isn't empty on first load. Users who already have a saved list (even an empty one) keep their own selection.
• Favorites render in a synthesized "Favorites" section (its own first rail menu in dual mode).
• Deep-leaf favorites have no own icon, so they inherit their group's icon (favWithIcon / iconByPath) to still show an icon in the minified rail.
• The empty state (dual mode) is an SVG illustration + nav:noFavorites / nav:noFavoritesHint.

nav-favorites is registered in src/lib/appStorage.ts so "Reset to defaults" clears it.

Numeric count badges

navBadges (src/data/navBadges.ts) maps a route path to a count. When a leaf's to has an entry, a neutral Badge with an AnimatedNumber renders. On hover (or when the item is favorited) the badge fades out so the pin-star can take its slot. A separate static badgeKey renders a primary text badge alongside.

User card footer

SidebarUserCard (src/layout/SidebarUserCard.tsx) pins to the bottom of the panel (and the dual secondary), showing the current user and a live presence dot from the shared usePresence store — so it stays in sync with the profile menu.

Accordion + auto-open

When config.accordionMenu is on, the NavList controller makes each section's groups single-open (opening one closes the rest) at every nesting depth — a group renders its children through NavList, so nested subgroups (e.g. Page Layouts) are single-open too.

• Default sidebar: only the active group is expanded; others collapse as you navigate.
• Dual secondary: passes openFirst so a lone panel is never empty (opens active-or-first group), and expands ALL groups when the section is short (countItems(section.items) <= 16) so short panels need no scroll; longer ones use the accordion.
• The active route's parent auto-opens and the active leaf scrolls to center (after the accordion finishes expanding). Nested indent is pl-5, compounding per depth.

The menu source & sections

menu.ts ships 5 sections — Dashboard / Components / Data / Pages / Settings. This keeps the dual rail rich and the panels balanced. MenuItem.action (a Partial<LayoutConfig>) is available for apply-config-without-navigating shortcuts (no current items use it; the Page-Layout previews route to real pages instead).

Page-Layout preview routes

The pageLayouts group nests 5 subgroups — Sidebar Modes / Sidebar Theme / Navigation / Widgets / Feedback & Motion — each a real route. A single shared template LayoutPreviewPage({variant}) is driven by the LAYOUT_PREVIEWS data array in src/pages/layouts/LayoutPreviewPage.tsx (routes.tsx folds it into appRoutes). Each preview:

• Applies its config patch against the captured baseline on mount ({...baseline, ...preview.config}), so it shows a clean state with no leftover flags from the previously viewed preview.
• Reverts via a module-level previewSession + usePreviewSessionGuard() (called in the stable AppLayout) when you navigate out of /page-layouts/*.
• Fires a single info toast on entry (guarded by the session, so hopping between previews never stacks).
• live previews render interactive pills/toggles (e.g. toastPosition, pageTransition, showPrimaryNav) that apply live; sidebar-theme previews force themeMode: 'light' so the dark/OLED sidebar is visible.

The content is a polished Skeleton dashboard with a ScrambleText "demo content" caption — not a loading state. See Layout & Shell for the underlying options and Motion & Effects for the transition/loader kinds.

Examples

Adding a nav leaf:

// src/data/menu.ts — inside a section's `items` (or a group's `children`)
{key: 'reports', label: 'Reports', to: '/reports', icon: FileBarChart}

// src/locales/en/nav.json
{"reports": "Reports"}

Then add the route in src/routes.tsx (or let it fall back to a placeholder).

A nested (recursive) group:

{
    key: 'settings',
    label: 'Settings',
    icon: Settings,
    children: [
        {key: 'siteSettings', label: 'Site Settings', to: '/settings'},
        {key: 'permissions', label: 'Permissions', to: '/settings/permissions'},
    ],
}

Adding a live count badge:

// src/data/navBadges.ts
export const navBadges: Record<string, number> = {
    '/apps/contacts': 4, // pending applications
    '/reports': 9,
}

Toggling a favorite programmatically:

import {toggleFavorite, useFavorites} from '@/hooks/useFavorites'
 
function PinButton({path}: {path: string}) {
    const {isFavorite} = useFavorites()
    return (
        <button onClick={() => toggleFavorite(path)}>
            {isFavorite(path) ? 'Unpin' : 'Pin'}
        </button>
    )
}

Best practices

• menu.ts is the single source of truth — edit navigation there, never hard-code links elsewhere. Breadcrumbs and placeholders both derive from it.
• Always store keys, not literal strings, on menu items (item.key, badgeKey) — labels resolve via t('nav:<key>') at render.
• Keep the three-step contract in sync (menu item · route · i18n label) so the menu and router never drift and no accidental placeholder appears.
• Multi-line sidebar text needs whitespace-normal — sidebar text inherits white-space: nowrap to keep labels one-line, so any wrapping text (e.g. the favorites hint) must opt back in.
• Register new persisted nav keys (like nav-favorites) in src/lib/appStorage.ts so Reset clears them.
• Give favorites-eligible deep leaves a discoverable group icon — leaves without their own icon inherit the group's, which is what shows in the minified rail.

Troubleshooting

FAQ

How do I add a whole new section? Append a MenuSection to menu in src/data/menu.ts with a key, heading, icon, and items, then add the nav:<key> heading label. It appears in the standard tree and as a rail icon in dual mode.

Can a menu item change the layout instead of navigating? Yes — set action: Partial<LayoutConfig> (no to). Clicking applies the config patch. The Page-Layout previews use real routes instead, but the mechanism is available.

Where do the count badges come from? src/data/navBadges.ts (mock data keyed by route). Swap it for live API data in a real deployment.

How does auto-open decide what to expand? The NavList controller finds the group containing the active route and opens it (single-open when accordionMenu). The active leaf then scrolls to center.

Why is the sidebar dark by default? darkSidebar defaults to true — see Layout & Shell. It re-scopes .dark tokens to the sidebar on a light page; oledSidebar upgrades that to pure black.

Notes for designers & content editors

• All nav labels, section headings, and badge text are i18n keys — edit them in src/locales/<lng>/nav.json, not in menu.ts.
• Icons come from lucide-react; pick an icon name and import it in menu.ts.
• The Page Layouts preview routes let you experience every sidebar mode and layout option full-page, with realistic skeleton content, and revert automatically when you leave.
• Favorites, search, badges, and the user card work in all modes; the minified rail collapses text to icons and reveals the full panel on hover.

Related