App Shell

Installation

import {
  AppShell,
  AppShellHeader,
  AppShellNav,
  AppShellAside,
  AppShellMain,
  AppShellFooter,
} from "@gradeui/ui"

Usage

AppShell is a CSS-grid layout with fixed grid-area slots. The nav prop picks the template — none, top, side, or three-pane — and the slot components drop wherever they go in the JSX. Order doesn't matter; each slot has a fixed area.

Header and Footer always span full width, regardless of nav variant — that's what makes the same primitive work for marketing pages (Header / Main / Footer) and three-column workspaces (Header spanning a sidebar+aside+main grid).

It's intentionally just structure — no collapse state, no context, no runtime JS. Server-rendered, consumer-themeable. For user-adjustable column widths (drag-to-resize), use Resizable instead.

nav="side"

The classic dashboard shape — nav on the left, main filling the rest.

nav="top"

In-app nav bar above main — a tab strip or section nav row. Combine with maxWidth="container" on the main region to cap the content width.

nav="three-pane"

The Slack/Mail/Notion shape — narrow nav rail + fixed-width Aside (a list, channel picker, or page tree) + flex Main. The middle column's width comes from the --rds-app-shell-aside CSS variable (default 320px) — override per-screen via inline style or a parent class without forking the component.

Marketing layout (Header + Footer)

Header and Footer span full width and always sit at the very top / very bottom — independent of the nav variant. With nav="none" you get the canonical marketing shape: Header / Main / Footer.

Header + side nav + Footer

Header and Footer span all columns, with the side-nav body row in the middle. Useful when an app has site-wide chrome (org switcher, help menu) above and an in-app side nav for navigation.

nav="none"

No nav — useful for auth flows, single-screen prototypes, or any page where you don't need an in-app navigation rail.

Aside width

When using nav="three-pane", the Aside column's width comes from a CSS variable, not a prop. The default is 320px — fits a typical inbox / channel-list / file-tree comfortably. To override per-screen, set --rds-app-shell-aside on the shell element (or any ancestor):

{/* Inline style on the shell */}
<AppShell
  nav="three-pane"
  style={{ "--rds-app-shell-aside": "280px" } as React.CSSProperties}
>
  …
</AppShell>

{/* Or via a parent class — useful for breakpoint-based switching */}
<div className="[--rds-app-shell-aside:240px] lg:[--rds-app-shell-aside:360px]">
  <AppShell nav="three-pane">…</AppShell>
</div>

Sticky header / nav / aside

AppShellHeader, AppShellNav and AppShellAside each take a sticky prop. Defaults: Nav true, Header and Aside false. Side and aside variants get h-screen self-scroll when sticky — so a long list scrolls inside its column, not the page.

User-adjustable columns

AppShell columns are static — the widths come from the grid template. If you want users to drag column dividers to resize, drop a ResizablePanelGroup inside an AppShellMain (or use it as the only child of nav="none") and let it manage the splits.

Composition

Drop any nav component into AppShellNav and any page content into AppShellMain. A typical productivity-app shell with site chrome, side nav, and a footer:

<AppShell nav="side">
  <AppShellHeader sticky>
    <OrgSwitcher /> <SearchInput /> <UserMenu />
  </AppShellHeader>

  <AppShellNav placement="side">
    <Sidebar>
      <SidebarHeader><Logo /></SidebarHeader>
      <SidebarContent>
        <SidebarSection title="Main">
          <SidebarItem href="/" icon={<Home />}>Home</SidebarItem>
          <SidebarItem href="/projects">Projects</SidebarItem>
        </SidebarSection>
      </SidebarContent>
    </Sidebar>
  </AppShellNav>

  <AppShellMain>
    <Stack gap="lg" className="p-6">
      <PageHeader title="Dashboard" />
      <DashboardGrid />
    </Stack>
  </AppShellMain>

  <AppShellFooter>
    <FooterLinks />
  </AppShellFooter>
</AppShell>

AppShell props

AppShellHeader props

AppShellNav props

AppShellAside props

AppShellMain props

AppShellFooter props

When to use

• As the root layout for any screen — app or marketing — at the top of a layout.tsx or full-page route.
• When you need a 3-column workspace (Slack/Mail/Notion shape) without hand-rolling grid grid-cols-[auto_320px_1fr] — use nav="three-pane".
• When you want columns the user can drag to resize, compose with Resizable inside the AppShell instead of relying on the grid.
• Pair Nav with Sidebar or TopMenu, and Main with Stack.