App Shell

Most business applications share a common frame: a sidebar for navigation, a top bar for context and actions, and a scrollable content area. The App Shell pattern shows how to compose this frame using <AppLayout>, covering provider wiring, content placement decisions, and responsive strategy.

Structure

The App Shell divides the screen into three areas. The diagram below shows how they are arranged, and the code snippet shows how the components map to each area.

• Sidebar: Sits on the left and spans the full height. It holds the application logo, primary navigation links, grouped sections, and an optional footer. Users can collapse or expand it with a toggle button.
• Top Navigation: Stretches across the top next to the sidebar. It should provide the sidebar toggle, breadcrumbs for orientation, and user-related controls such as account menus or status indicators.
• Main: Takes up the remaining space. This is the scrollable content area where page-specific content lives, typically wrapped in spacing via <Inset>.

RouterProvider handles page navigation, Sidebar.Provider manages the sidebar's open/collapsed state, and AppLayout positions everything on a CSS Grid. Place Sidebar.Provider outside of AppLayout so the toggle in the header and the sidebar itself share the same state.

<RouterProvider navigate={navigate}>
  <Sidebar.Provider defaultOpen>
    <AppLayout>
      <AppLayout.Sidebar>
        <Sidebar.Header>...</Sidebar.Header>
        <Sidebar.Nav>...</Sidebar.Nav>
        <Sidebar.Footer>...</Sidebar.Footer>
      </AppLayout.Sidebar>
      <AppLayout.Header>
        <TopNavigation.Start>
          <Sidebar.Toggle />
        </TopNavigation.Start>
        <TopNavigation.Middle>...</TopNavigation.Middle>
        <TopNavigation.End>...</TopNavigation.End>
      </AppLayout.Header>
      <AppLayout.Main>...</AppLayout.Main>
    </AppLayout>
  </Sidebar.Provider>
</RouterProvider>

The order of the slot components inside AppLayout doesn't matter since the grid template handles positioning.

Where things go

Each area has a clear purpose. Mixing responsibilities between them makes the layout harder to use and harder to maintain.

• Logo placement: Put the application logo or name in the sidebar header, not in the top navigation. The sidebar is the persistent brand anchor; the top navigation is for orientation and utility actions.
• Primary navigation: All section-level links belong in the sidebar. Use groups (<Sidebar.GroupLabel>) and separators (<Sidebar.Separator>) to organize them. See the Sidebar docs for drill-down navigation and detail page patterns.
• Top navigation: The top navigation exists primarily for breadcrumbs and search. Breadcrumbs go in the middle slot to show users where they are in the hierarchy. A search field can replace or complement them when global search is a core workflow. Don't place tabs, links, or secondary navigation here. That's what the sidebar is for. See the TopNavigation docs for further information.
• Utility actions (top navigation, right side): The end of the top navigation is reserved for user-facing utilities like account menus, notification badges, or status indicators. Keep it concise; too many items cause the navigation to overflow on smaller screens.

Responsive behavior

<AppLayout> always renders the L-shape grid and doesn't change at breakpoints. Responsive behavior comes from the components inside it. The sidebar collapses on desktop and becomes a modal sheet on mobile. The top navigation adapts its content at smaller widths. See the Sidebar and TopNavigation docs for details.

Full demo

A complete App Shell with sidebar navigation (including drill-down), breadcrumbs, user menu, and scrollable content.

Related