build-app-layout

name

build-app-layout

description

Use this skill for any task involving app layouts — building new layouts, adding sidebars or navigation to existing apps, migrating an existing layout to mui-treasury components, or reviewing/improving layout structure. Trigger whenever the user mentions dashboard layout, sidebar navigation, app shell, header/footer/content structure, collapsible sidebar, drawer navigation, layout with sidebar, or asks to "build a layout", "add a sidebar", "set up the app layout", "review the layout". Also trigger when a mockup or design shows an app with sidebar + header + content regions, even if the user doesn't say "layout" explicitly.

Installation

Components are installed via the mui-treasury CLI into src/mui-treasury/:

# Layout core (Root, Header, Content, Footer, EdgeSidebar, InsetSidebar, etc.)
npx mui-treasury@latest add layout-core

# Sidebar primitives (SidebarContainer, SidebarMenuButton, SidebarIcon, etc.)
npx mui-treasury@latest add sidebar

After installation, import from:

• @/mui-treasury/layout/layout-core — layout components
• @/mui-treasury/components/sidebar — sidebar primitives

Recommended Defaults

Use these as starting values unless the user specifies otherwise.

Collapsible EdgeSidebar

• collapsedWidth: "52px"
• SidebarIcon shrinkSize="20px" to center icons in the collapsed sidebar
• permanentAutoCollapse="lg" to auto-collapse below the lg breakpoint
• <EdgeSidebarCollapser render={<SidebarRail />} /> as a click-to-collapse trigger — SidebarRail is a pure visual component, EdgeSidebarCollapser injects the collapse onClick
• Use sidebar primitives for sidebar content — they auto-adapt to collapsed state
• left/right arrow icons for EdgeSidebarCollapser
• down arrow icon for CollapsibleIcon

EdgeSidebar Content Structure

Place SidebarContainer in the middle of EdgeSidebarContent so it grows to fill available space and becomes the scrollable area for menus. Static-height content (sidebar header/footer) should be siblings of SidebarContainer:

EdgeSidebarContent
├── Sidebar header (static) — e.g. app switcher, logged-in user, logo
├── SidebarContainer (flex: 1, scrollable) — navigation menus
└── Sidebar footer (static) — e.g. user preferences, settings, ads/banner

• EdgeSidebarContent uses display: flex; flex-direction: column by default
• SidebarContainer grows via flex: 1 and handles its own overflow scroll
• Sidebar header/footer keep their natural height and never scroll
• Sidebar primitives (SidebarMenuButton, SidebarIcon, etc.) still work in the header/footer areas because they are descendants of EdgeSidebar — but collapse-aware CSS variables (--_collapsed/--_uncollapsed) only work inside SidebarContainer

SidebarMenuButton

• should use the component prop for polymorphism, e.g. <SidebarMenuButton component="a" href="/dashboard"> or <SidebarMenuButton component={Link} to="/dashboard">

• MUST be a child of SidebarMenuItem which is a child of SidebarMenuList. Never wrap SidebarMenuButton in a plain div or Box — the list structure (SidebarMenuList > SidebarMenuItem > SidebarMenuButton) is required for proper spacing, collapse behavior, and accessibility

• Never use consecutive SidebarText siblings inside a SidebarMenuButton. For multi-line text, use a single SidebarText wrapping the content. For two-line text labels, use SidebarGroupText:

  // ❌ Wrong — consecutive SidebarText
  <SidebarMenuButton>
    <Avatar />
    <SidebarText><Typography>siriwatknp</Typography></SidebarText>
    <SidebarText><Typography>[e-mail]</Typography></SidebarText>
  </SidebarMenuButton>
  
  // ✅ Correct — single SidebarText with SidebarGroupText for 2 lines
  <SidebarMenuButton>
    <Avatar />
    <SidebarText>
      <SidebarGroupText>
        <Typography variant="body2">siriwatknp</Typography>
        <Typography variant="caption">[e-mail]</Typography>
      </SidebarGroupText>
    </SidebarText>
  </SidebarMenuButton>
  

• Never place secondary actions (e.g. IconButton, Badge) inside SidebarMenuButton. Use SidebarMenuAction as a sibling:

  // ❌ Wrong — actions inside SidebarMenuButton
  <SidebarMenuItem>
    <SidebarMenuButton>
      <Avatar />
      <SidebarText>siriwatknp</SidebarText>
      <Box sx={{ display: "flex", gap: 0.5 }}>
        <IconButton size="small"><MoreHorizRounded /></IconButton>
        <IconButton size="small"><NotificationsRounded /></IconButton>
      </Box>
    </SidebarMenuButton>
  </SidebarMenuItem>
  
  // ✅ Correct — SidebarMenuAction as sibling
  <SidebarMenuItem>
    <SidebarMenuButton>
      <Avatar />
      <SidebarText>siriwatknp</SidebarText>
    </SidebarMenuButton>
    <SidebarMenuAction>
      <IconButton size="small"><MoreHorizRounded /></IconButton>
      <IconButton size="small"><NotificationsRounded /></IconButton>
    </SidebarMenuAction>
  </SidebarMenuItem>
  

• Never make SidebarMenuButton non-interactive (e.g. component="div" with cursor: "default"). If the element is not clickable, use SidebarMenuItem directly instead:

  // ❌ Wrong — non-interactive button
  <SidebarMenuButton component="div" sx={{ cursor: "default", "&:hover": { bgcolor: "transparent" } }}>
    <Avatar />
    <SidebarText>siriwatknp</SidebarText>
  </SidebarMenuButton>
  
  // ✅ Correct — use SidebarMenuItem for non-interactive content
  <SidebarMenuItem>
    <Avatar />
    <SidebarText>siriwatknp</SidebarText>
  </SidebarMenuItem>
  

• SidebarMenuAction must only be used alongside a SidebarMenuButton sibling. If there is no SidebarMenuButton, use a plain IconButton instead

Rules of Thumb

• Don't use hoverUncollapse with EdgeSidebarRail — they are noy designed to work together and can cause janky behavior

• Don't use hoverUncollapse with SidebarTooltip — tooltips won't show when the sidebar is collapsed, so the hover state becomes inaccessible

• It's recommended to have only one SidebarContainer as a direct child of EdgeSidebar — having multiple containers will cause the available space to split evenly, which mostly not the desired behavior.

• Align icons in the center of the collapsed sidebar with proper shrinkSize on SidebarIcon.

• Align custom elements like avatar in the center of the collapsed sidebar using negative margins with EdgeSidebar variables (see EdgeSidebar Collapsible Variables guide)

• On pages that use EdgeDrawerTrigger but have no sidebar, add <EdgeSidebar variant={['permanent', { visibility: 'hidden' }]} /> to hide the trigger — permanent mode auto-hides EdgeDrawerTrigger, and visibility: 'hidden' prevents the sidebar from taking visual space

• To create a floating sidebar (with margin, border, shadow, rounded corners), never apply these styles directly to EdgeSidebarContent — it breaks the layout. Instead, make EdgeSidebarContent transparent and style a child div:

  <EdgeSidebarContent className="bg-transparent">
    <div className="m-2 border shadow-xl rounded-lg bg-background flex flex-col">
      {sidebar}
    </div>
  </EdgeSidebarContent>
  

Documentation

Read the relevant page based on your needs:

• Tutorials — Step-by-step lessons to build your first layout. Start here if unfamiliar with the layout system.
• Reference Guides — Complete API for all layout-core components and sidebar primitives with props tables.
• Explanation — Architecture decisions: CSS Grid + CSS variables, how collapse works, EdgeSidebar vs InsetSidebar, term mappings.

How-to Guides

Integration:

• Next.js Integration — Set up layout in App Router with layout.tsx/page.tsx split, MUI Treasury theme

Layout patterns:

• Dashboard Layout — Collapsible left sidebar, drawer on mobile, permanent on desktop
• Chat/Messenger Layout — Permanent sidebar for conversation list, standalone scrollable content, InsetSidebar for details
• Blog/Content Layout — Sticky InsetSidebar for table of contents, no EdgeSidebar
• Shopping Cart / Right Sidebar — Right-side drawer for cart/checkout panel

Sidebar features:

• Header Clipping — Make the header span over the sidebar for full-height sidebar
• Nested Popup Menus (3 Levels) — Multi-level flyout menus when sidebar is collapsed, with collapsible fallback when uncollapsed
• EdgeSidebar Collapsible Variables — Use --_collapsed/--_uncollapsed CSS variables to style non-mui-treasury elements based on sidebar state

Demos:

• Iframe Preview for Responsive Demos — Configure demos that showcase responsive behavior