InstallCopy Anchor Link

pnpm exec vegastack-design verify app-shell

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

UsageCopy Anchor Link

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>;

AnatomyCopy Anchor Link

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>
  <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">
      <AppShellPage size="default">…</AppShellPage>
    </AppShellContent>
  </div>
</AppShell>

• AppShell — the root (data-slot="app-shell"). Wraps SidebarProvider, forwarding defaultOpen/open/onOpenChange — every prop upstream's provider takes. Renders the skip link.
• AppShellSidebar — a thin wrapper over Sidebar that passes variant/collapsible/side straight through and adds the <nav> landmark upstream leaves to the page: a data-slot="app-shell-sidebar" element wrapping the rail's children, defaulting to aria-label="Main navigation". It sits INSIDE the rail so that below the mobile breakpoint — where upstream moves the rail into a Sheet — the landmark appears exactly when the navigation does, instead of standing empty in the document.
• 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, padded by the page gutter (--page-gutter) so its edges line up with the page's.
• 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.
• AppShellPage — the page container inside AppShellContent (data-slot="app-shell-page", data-size): the page gutter, a gap-6 rhythm and the prose / default / full width.
• 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.

ExamplesCopy Anchor Link

VariantsCopy Anchor Link

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). Under inset it paints exactly what SidebarInset paints — m-2 ms-0 rounded-xl shadow-sm from md up, no border — so the two agree on their own corner.

Page containerCopy Anchor Link

Put each page's content in AppShellPage inside AppShellContent. It is the one place a page's width and gutters come from: a column padded by the page gutter (--page-gutter — 16px, 24px from 640px, 32px from 1024px, 48px from 1920px, the header's own padding) with a gap-6 rhythm between the PageHeader and each section. size picks the width — prose (720px of content, centred) for forms and settings, default (1280px, centred) for lists, dashboards and record pages, and full (edge to edge, fills the height) for boards and canvases; narrow is prose's deprecated old name. Choose it per route from one map — see Page layout. It renders a plain <div>, because AppShellContent is already the main landmark.

<AppShellContent>
  <AppShellPage size="prose">
    <PageHeader title="Profile" />
    <ProfileForm />
  </AppShellPage>
</AppShellContent>

Section measureCopy Anchor Link

AppShellSection holds one region of a page at its own measure, with no max-w-* of its own. measure="prose" caps it at 720px — a settings tab under a default-width header and tabs — and full (the default) takes the page's width. align places a prose section: start (the default) keeps it under the header's start edge.

align="center" centres it in the page, so a settings tab reads like a settings page (AppShellPage size="prose"). align is ignored at full.

Width follows the content, not the route. measure="default" caps a section at a default page's content width and centres it (its align defaults to center), so a full frame that hosts several kinds of content — a folder list, a document, a grid on one route — keeps its list at exactly the width every other list has, while the grid beside it fills.

<AppShellPage size="full">
  <AppShellSection measure="default">
    <PageHeader title="Contracts" />
    <DataList … />
  </AppShellSection>
</AppShellPage>

<AppShellPage>
  <PageHeader title="Product" tabs={tabs} />
  <AppShellSection measure="prose" align="center">
    <SpaceSettings />
  </AppShellSection>
</AppShellPage>

BleedCopy Anchor Link

AppShellBleed is a region of the page that reaches the page's side edges and bottom, past the page gutter: a grid under the PageHeader whose scroll bars should rest at the edge of the page's region instead of floating inside the gutter. It owns the three negative margins, so no wrapper carries a gutter class of its own. Put it directly inside the page, after the header; active={false} keeps the gutter (a grid that lays out as cards on a phone).

<AppShellPage size="full">
  <PageHeader title="Schedule" />
  <AppShellBleed>
    <DataGrid fill … />
  </AppShellBleed>
</AppShellPage>

Header tools by widthCopy Anchor Link

AppShellHeader is an inline-size container named app-shell-header, so tools in it compact by the header's own width — which counts the sidebar being open or collapsed — with container queries: no measuring script and no first-paint flash.

<AppShellHeader
  actions={
    <Button size="sm" variant="ghost" aria-label="Share">
      <ShareIcon />
      <span className="hidden @2xl/app-shell-header:inline">Share</span>
    </Button>
  }
>
  …
</AppShellHeader>

Two parts cover the common cases without a class of your own. AppShellHeaderSlot is a fixed 32px place for something that arrives late or changes shape — a save status, a connection icon — reserved from the first paint so the buttons beside it never move (a tooltip trigger can render as it). AppShellHeaderShow when="narrow" shows its content only while the bar is under 40rem, and when="wide" only from 40rem.

<AppShellHeader
  actions={
    <>
      <AppShellHeaderShow when="narrow">
        <AvatarStack people={here} max={2} />
      </AppShellHeaderShow>
      <AppShellHeaderSlot>
        <AutoSaveIndicator variant="icon" status={status} />
      </AppShellHeaderSlot>
    </>
  }
>
  …
</AppShellHeader>

Actions that give way. AppShellHeaderActions takes the page's actions as data and moves each one into a single ⋮ menu when the bar is narrower than its overflow width — laptop (55rem), tablet (40rem), or never for the page's one primary action — and drops the labels to icons below 40rem. menu entries always live in the ⋮. Nothing hides without a way to reach it, and the page writes no container query of its own. render takes a router link for an action that navigates.

<AppShellHeader
  actions={
    <AppShellHeaderActions
      leading={<AvatarStack people={here} max={3} />}
      actions={[
        {
          id: "share",
          label: "Share",
          icon: <Share2 />,
          onSelect: share,
          overflow: "never",
        },
        {
          id: "watch",
          label: "Watch",
          icon: <Bell />,
          onSelect: watch,
          overflow: "laptop",
        },
      ]}
      menu={[
        { id: "copy", label: "Copy link", icon: <Link2 />, onSelect: copy },
      ]}
      menuLabel="Task actions"
    />
  }
>
  …
</AppShellHeader>

SkeletonCopy Anchor Link

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} />;
}

Loading a page inside the shell. A route's loading.tsx shows AppShellProgress — a 2px indeterminate bar stuck to the top of the content however far it was scrolled, at once — and its own skeleton wrapped in motion-reveal (a @vegastack/design-tokens utility): the skeleton waits 150ms (--reveal-delay) before it fades in, so a fast load never flashes a skeleton and a slow one is never a blank page while it waits. One skeleton per load, in the page's own shape.

// app/(app)/tasks/loading.tsx
export default function Loading() {
  return (
    <>
      <AppShellProgress label="Loading tasks" />
      <div className="motion-reveal">
        <TasksSkeleton />
      </div>
    </>
  );
}

MobileCopy Anchor Link

Below 768px — upstream's one fixed breakpoint, read through useIsMobile, with no prop to retune it — 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 — collapse a long trail yourself with BreadcrumbEllipsis 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.

Tablet railCopy Anchor Link

From 768px up to 1023px an icon rail rests as icons. Counts stay at each icon's top-end corner (a dot past two characters), railSeparators rules a hairline between the groups once their labels fold away, and a nested list such as Spaces opens beside its row through SidebarMenuFlyout railOnly.

Phone barCopy Anchor Link

On a phone the sidebar is a drawer, so what it holds is two taps away. mobileActions puts the most frequent jumps in the bar — Search, and the Inbox with its count — each an AppShellHeaderMobileAction of 40px, before actions, so the page's primary stays rightmost; the sidebar trigger grows to 40px with them. AppShellFold folds the drawer's footer entries (Docs, Trash, Settings) into the profile menu on a phone: wrap the sidebar's copy in place="sidebar" and the menu's in place="menu", and exactly one renders. Narrow the window below 768px to see both.

Route-change focusCopy Anchor Link

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>
  );
}

Static shellsCopy Anchor Link

A prerendered or cached shell cannot read the sidebar cookie on the server, so a collapsed sidebar would paint expanded and jump on hydration. Put SidebarStateScript in the root layout's <head> with the same collapsible as your AppShellSidebar, and drive AppShell from useSidebarCookieOpen when you control it. The script marks the panel collapsed before first paint, the hook starts from that mark and writes the cookie, and the controlled shell writes none itself (LAY-13). The mechanism is documented on Sidebar.

"use client";
import { AppShell } from "@/components/ui/app-shell";
import { useSidebarCookieOpen } from "@/components/ui/sidebar";

export function AppFrame({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useSidebarCookieOpen();
  return (
    <AppShell open={open} onOpenChange={setOpen}>
      {children}
    </AppShell>
  );
}

API ReferenceCopy Anchor Link

AppShellCopy Anchor Link

AppShellSidebarCopy Anchor Link

AppShellHeaderCopy Anchor Link

AppShellHeaderMobileActionCopy Anchor Link

AppShellFoldCopy Anchor Link

AppShellHeaderActionsCopy Anchor Link

Each entry of actions and menu is an AppShellHeaderAction:

AppShellProgressCopy Anchor Link

AppShellContentCopy Anchor Link

AppShellPageCopy Anchor Link

AppShellBleedCopy Anchor Link

AppShellSectionCopy Anchor Link

AppShellSkeletonCopy Anchor Link

AccessibilityCopy Anchor Link

• 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).
• Phone tools. Each AppShellHeaderMobileAction is a 40px button named by its label, with its count in the name ("Inbox 15 unread"); the pill on the icon is decorative.
• 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'tCopy Anchor Link