App Shell

Install

pnpm dlx shadcn@latest add @vegastack/app-shell

Usage

import {
  AppShell,
  AppShellContent,
  AppShellHeader,
  AppShellSidebar,
} from "@/components/ui/app-shell";
import { SidebarContent, SidebarHeader } from "@/components/ui/sidebar";
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbPage,
} from "@/components/ui/breadcrumb";
import { Button } from "@/components/ui/button";

<AppShell defaultOpen>
  <AppShellSidebar>
    <SidebarHeader>…logo / workspace switcher…</SidebarHeader>
    <SidebarContent>…nav groups…</SidebarContent>
  </AppShellSidebar>
  <div className="flex h-svh min-w-0 flex-1 flex-col">
    <AppShellHeader actions={<Button size="sm">New agent</Button>}>
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem>
            <BreadcrumbPage>Dashboard</BreadcrumbPage>
          </BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
    </AppShellHeader>
    <AppShellContent>…page content…</AppShellContent>
  </div>
</AppShell>;

Anatomy

AppShell is a composition layer over Sidebar (+ Sheet/useIsMobile for its mobile behavior) — not a new primitive. It wraps SidebarProvider and renders a skip-to-content link as the first focusable element; you compose AppShellSidebar as one child and your own content column (a plain flex h-svh flex-col <div>) wrapping AppShellHeader + AppShellContent as the other:

<AppShell defaultOpen keyboardShortcut mobileBreakpoint={768}>
  <AppShellSidebar variant="sidebar" collapsible="icon">
    <SidebarHeader>…</SidebarHeader>
    <SidebarContent>…</SidebarContent>
    <SidebarFooter>…</SidebarFooter>
  </AppShellSidebar>
  <div className="flex h-svh min-w-0 flex-1 flex-col">
    <AppShellHeader actions={<>…buttons…</>}>
      <Breadcrumb>…</Breadcrumb>
    </AppShellHeader>
    <AppShellContent variant="sidebar">…</AppShellContent>
  </div>
</AppShell>

• AppShell — the root (data-slot="app-shell"). Wraps SidebarProvider, forwarding defaultOpen/open/onOpenChange/mobileBreakpoint/keyboardShortcut. Renders the skip link.
• AppShellSidebar — a thin wrapper over Sidebar (data-slot="app-shell-sidebar") that defaults aria-label="Main navigation" and passes variant/collapsible/side straight through.
• AppShellHeader — a <header> banner landmark (data-slot="app-shell-header"): always-visible SidebarTrigger + a min-w-0 middle slot (children) + a shrink-0 actions slot.
• AppShellContent — the <main tabIndex={-1}> data-slot="app-shell-content" — this shell's skip-link target, carrying @container/app-shell-content for width-aware grids. Its id is generated per shell by AppShell (contentId pins it), never a fixed literal.
• AppShellSkeleton — a full-shell loading composition for loading.tsx (data-slot="app-shell-skeleton").

Why no AppShellBody/column component? Keeping the content column a plain, undecorated <div> you write yourself keeps AppShellHeader's <header> a true SIBLING of AppShellContent's <main> — never nested inside it, which is what lets the header keep its banner landmark role. A wrapping component that owned both would tempt collapsing them into one element, silently losing that landmark.

Examples

Variants

AppShellSidebar passes variant straight through to Sidebar (sidebar / floating / inset). Pass the SAME variant to AppShellContent to keep the shell visually consistent — unlike Sidebar + SidebarInset's CSS peer selector, AppShellContent applies its panel treatment directly via the prop (see the API reference for why).

Skeleton

AppShellSkeleton composes a full loading shell — a sidebar column, a header line, and a stat-card + chart-placeholder content region — server-safe, so it drops straight into a Next.js loading.tsx with no 'use client' needed.

// app/(dashboard)/loading.tsx — a Server Component.
import { AppShellSkeleton } from "@/components/ui/app-shell";

export default function Loading() {
  return <AppShellSkeleton navItemCount={6} statCardCount={4} />;
}

Mobile

Below mobileBreakpoint (768px by default), Sidebar swaps to a Sheet drawer — AppShellHeader already renders SidebarTrigger OUTSIDE AppShellSidebar (it's a sibling in the content column, not nested inside the rail), so the one control that opens the mobile sheet is always reachable, with zero extra composition on your part. The header's middle slot truncates (min-w-0 flex-1) instead of wrapping — pair it with BreadcrumbTrail's maxItems for long trails on narrow screens.

Switch the preview's width toggle (the toolbar's phone icon) to mobile to watch the rail collapse into the Sheet — open it from the header trigger. This is viewport-driven, so a real narrow browser does the same on its own; the toggle only constrains a container, so this demo forces the branch to make it visible without resizing your window.

Route-change focus

AppShell is deliberately router-agnostic — it has no dependency on Next.js/React Router and never imports one. Moving keyboard focus to the new page's heading on a client-side route change is standard SPA accessibility practice, and it's the DOWNSTREAM app's responsibility: focus your PageHeader's title (give it tabIndex={-1}) or AppShellContent itself — pass contentId to AppShell when you need a known id to focus — keyed on the router's pathname:

"use client";
import { usePathname } from "next/navigation";
import { useEffect, useRef } from "react";

function RouteFocus() {
  const pathname = usePathname();
  const headingRef = useRef<HTMLHeadingElement>(null);
  useEffect(() => {
    headingRef.current?.focus();
  }, [pathname]);
  return (
    <h1 ref={headingRef} tabIndex={-1}>
      …
    </h1>
  );
}

API Reference

AppShell

AppShellSidebar

AppShellHeader

AppShellContent

AppShellSkeleton

Accessibility

• Skip link. The very first focusable element in the shell (sr-only focus:not-sr-only), targeting THIS shell's AppShellContent. Tab once on page load to reach it. The target id is generated with React.useId() and shared down, so a page holding several shells gives each one its own target rather than sending every link to the first; pass contentId on AppShell to pin it. Setting id on AppShellContent moves the element but does not rewire the link.
• Landmark trio. AppShellHeader is a banner (<header>, never nested inside <main>), AppShellSidebar is a navigation (<nav aria-label="Main navigation">, overridable), and AppShellContent is the single main on the page. If the shell is embedded in a page that already owns a <main> — a docs preview, a gallery, a shell shown inside a larger document — pass landmark="region" (with an aria-label) so it renders a <div role="region"> instead. Two <main> elements in one document is a real defect; this escape exists so the answer is never to delete the landmark from the component. SidebarInset carries the same prop. Every preview on this page is an embedded shell and therefore uses landmark="region" — this page already owns the site's one <main>, so no preview here can demonstrate the main landmark, and the skip links you can try below land on a region. In a real application the default applies and the target is a <main>.
• Mobile trigger. SidebarTrigger always renders in AppShellHeader — below the mobile breakpoint it's the only way to open the sidebar, and it's never nested inside the collapsible rail it controls (see sidebar.tsx's own composition note).
• Reduced motion. The sidebar's collapse/expand and the mobile sheet's slide-in both route through the design system's centralized prefers-reduced-motion block — no shell-specific motion to opt out of.
• Route-change focus is the host app's responsibility (see above) — AppShell stays router-agnostic and cannot own it.

Do / Don't