App Shell React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

App Shell is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import AppShell from @/components/ui/app-shell.

import type { ReactNode } from "react"
import Link from "next/link"
import { cookies } from "next/headers"
import { usePathname, useRouter } from "next/navigation"
import { FileText, House, Inbox, LayoutDashboard, Settings, Users } from "lucide-react"
import { AppShell } from "@/components/ui/app-shell"
import { Sidebar, type SidebarNavGroup } from "@/components/ui/sidebar"
import { Topbar } from "@/components/ui/topbar"
import { persistedCookieName } from "@/hooks/use-persisted-state"
import { LinkProvider, type NavItem } from "@/lib/navigation"

// app/providers.tsx ("use client"): every NavLink inside renders through next/link
export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter()
  return (
    <LinkProvider component={Link} currentPath={usePathname()} navigate={router.push}>
      {children}
    </LinkProvider>
  )
}

const nav: SidebarNavGroup[] = [
  {
    items: [
      { label: "Home", href: "/", icon: <LayoutDashboard /> },
      { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
    ],
  },
  {
    label: "Sales",
    items: [
      { label: "Clients", href: "/clients", icon: <Users /> },
      { label: "Invoices", href: "/invoices", icon: <FileText /> },
    ],
  },
  { label: "Account", items: [{ label: "Settings", href: "/settings", icon: <Settings /> }] },
]

const tabs: NavItem[] = [
  { label: "Home", href: "/", icon: <House /> },
  { label: "Clients", href: "/clients", icon: <Users /> },
  { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
  { label: "Settings", href: "/settings", icon: <Settings /> },
]

// app/(app)/layout.tsx, a server component: the cookie renders the right sidebar on the first paint
export default async function AppLayout({ children }: { children: ReactNode }) {
  const stored = (await cookies()).get(persistedCookieName("app-shell-collapsed"))?.value
  return (
    <AppShell
      defaultCollapsed={stored === "true"}
      sidebar={<Sidebar groups={nav} filter />}
      topbar={<Topbar title="Summit CRM" />}
      tabs={tabs}
      labels={{ openMenu: "Open menu", closeMenu: "Close menu", collapse: "Collapse", expand: "Expand", navigation: "Main" }}
      skipLinkLabel="Skip to content"
    >
      {children}
    </AppShell>
  )
}

Props

• sidebar
  ReactNode

  A Sidebar. The shell renders it in the desktop column (it drives its collapsed state, width and variant) and, on phones, a second copy with mode="sheet" inside the drawer, mounted only while the drawer is open. A wrapper component must forward its props (mode, variant, collapsible, width, className, style) to the Sidebar.

• nav
  SidebarNavGroup[]

  A shortcut for small apps: renders <Sidebar groups={nav} /> when sidebar is not given.

• topbar
  ReactNode

  A Topbar, sticky at the top of the content column. It renders the menu button (sidebar toggle on desktop, hamburger on phones) and gets aria-controls and the shortcut hint from the shell unless you set menuControls / menuShortcut (pass the Topbar element itself, not a wrapper component, for that). For your own header use AppShellTrigger (see Parts).

• tabs
  ReactNode | NavItem[]

  Phones only: a BottomTabBar, or just its items. Hidden from mobileBreakpoint up. Fixed to the viewport with window scroll (the page is padded by --bottom-bar-offset), a static row under the page with content scroll.

• banner
  ReactNode

  A full-width strip above everything, e.g. an Alert with radius="none" for a maintenance notice.

• children
  ReactNode

  The page, rendered in <main id={mainId}>. The shell never animates it on navigation. Components inside it read the shell state with useAppShell (see Parts).

• variantdefault "sidebar"
  "sidebar" | "inset" | "floating"

  sidebar: flush columns with a hairline. inset: the page sits in a raised rounded panel on a tinted shell (Linear, Vercel). floating: the sidebar is a raised panel 8px off the edges. Sets the sidebar's variant unless it has its own.

• defaultCollapseddefault false
  boolean

  Starts with the rail (or the sidebar hidden, with offcanvas). A stored cookie wins after hydration; read it on the server (persistedCookieName(`${persistKey}-collapsed`)) and pass it here so the first paint is right.

• collapsed
  boolean

  Controlled collapsed state of the desktop sidebar. Pair it with onCollapsedChange.

• onCollapsedChange
  (collapsed: boolean) => void

  Every change: the shortcut, the top bar button, the sidebar's collapse button, a drag to the rail.

• collapsibledefault "icon"
  "icon" | "offcanvas" | "none"

  icon: the sidebar folds into a 64px rail with tooltips. offcanvas: it slides out completely and the page takes the width. none: always expanded (the desktop toggle disappears; phones keep the drawer).

• persistKeydefault "app-shell"
  string

  Remembers collapsed and the width in the cookies `${persistKey}-collapsed` and `${persistKey}-width` (a server layout can read them). "" keeps both in memory.

• defaultSidebarWidthdefault 256
  number

  The expanded sidebar width in px, and what a double-click on the resize handle resets to.

• sidebarWidth
  number

  Controlled width in px. Pair it with onSidebarWidthChange.

• onSidebarWidthChange
  (width: number) => void

  Fires once per change (pointer up, a key press, a reset), never per frame.

• resizabledefault false
  boolean

  A handle on the sidebar's end edge: drag between 200 and 400px, below 120px it snaps to the rail, double-click resets. It is a keyboard-operable separator (arrows ±16px, Home, End, Enter).

• mobileBreakpointdefault "md"
  "md" | "lg"

  Below it the sidebar becomes a drawer and the tabs show: md (768px) or lg (1024px, tablets get the phone layout). Layout switches with CSS, so the server HTML is right.

• defaultMobileOpendefault false
  boolean

  Starts with the phone drawer open (it only shows below the breakpoint).

• mobileOpen
  boolean

  Controlled drawer state. Pair it with onMobileOpenChange.

• onMobileOpenChange
  (open: boolean) => void

  The drawer opened or closed (menu button, shortcut, edge swipe, navigation, Escape, a tap outside, a swipe back).

• mobileDrawerSizedefault "sm"
  "sm" | "md"

  The drawer's width: 320 or 400px, always leaving a 48px sliver of the page to tap.

• edgeSwipedefault false
  boolean

  Phones: a 16px strip on the start edge opens the drawer after a 40px drag or a flick. Turn it on in installed PWAs; in Safari that edge is the browser's back gesture.

• scrolldefault "window"
  "window" | "content"

  window: the document scrolls (router scroll restoration, the iOS toolbar minimizing; the right default for apps). content: the content column scrolls on its own and is provided to the bars as their scroll container (embedded apps, iframes, this demo). Docs-only: the playground always runs in content mode inside its frame.

• heightdefault "screen"
  "screen" | "full"

  screen: the viewport height (dvh). full: fills the parent, which needs a height. Docs-only: the playground frame always uses full.

• shortcutdefault "mod+b"
  string

  Toggles the sidebar: the rail on desktop, the drawer on phones. Shown in the top bar button's tooltip. "" binds nothing.

• skipLinkLabeldefault "Skip to content"
  string

  The skip link, the first focusable element: hidden until tabbed to, then it focuses the page.

• mainIddefault "main"
  string

  The id of <main>, the skip link's target.

• mainAsdefault "main"
  "main" | "div"

  The content column's element. Keep main for the app's own shell; use div when the shell renders inside a page that already has its <main> (a docs preview, an embedded demo).

• container
  HTMLElement | null

  Where the drawer is portaled (default document.body).

• labels
  { openMenu?: string; closeMenu?: string; collapse?: string; expand?: string; resize?: string; collapsed?: string; navigation?: string }

  English defaults ("Open menu", "Close menu", "Collapse sidebar", "Expand sidebar", "Resize sidebar", "Collapsed", "Navigation"). The first four are shared with the top bar's menu button through the shell context; resize names the resize handle, collapsed is its value text while the sidebar is a rail, navigation is the drawer's hidden title.

• classNames
  Partial<Record<"sidebar" | "body" | "main" | "topbar" | "tabs" | "drawer" | "resize", string>>

  Extra classes for the parts: the desktop sidebar column, the content column (the raised panel in inset), <main>, the top bar, the tabs row, the drawer body and the resize handle.

• className
  string

  Extra classes for the root.

Parts

FAQ

Used in

More React layout components