Component

App Shell

A responsive application layout with a collapsible sidebar, sticky header, and scrollable content. Built on the headless @refraction-ui/app-shell core, with state exposed via useAppShell().

Layout

A typical dashboard shell. The preview is constrained to a fixed-height region; in your app you would size the root to the viewport.

Welcome back

This is the scrollable main content region. On narrow viewports the sidebar becomes an off-canvas drawer toggled by the header hamburger button.

Installation

$pnpm add @refraction-ui/react-app-shell

Usage

tsx

import { AppShell } from '@refraction-ui/react'

export function MyApp() {
  return (
    <AppShell className="h-screen">
      <AppShell.Sidebar className="w-56 p-4">
        <nav>{/* nav links */}</nav>
      </AppShell.Sidebar>

      <AppShell.Main>
        <AppShell.Header>
          <span>Dashboard</span>
        </AppShell.Header>
        <AppShell.Content maxWidth="6xl">
          {/* page content */}
        </AppShell.Content>
      </AppShell.Main>

      <AppShell.Overlay />
    </AppShell>
  )
}

Props

Prop	Type	Default	Description
`config`	`AppShellConfig`	--	Headless configuration — breakpoints, sidebar position/width, and mobile-nav position. Drives responsive behavior and the emitted CSS variables.
`className`	`string`	--	Additional CSS classes for the root flex container.
`children`	`React.ReactNode`	--	Compose the layout from the sub-components below.

Compound sub-components — compose these inside <AppShell>.

Prop	Type	Default	Description
`AppShell.Sidebar`	`aside`	--	Off-canvas drawer on mobile, static rail on desktop. Reads width from CSS variables.
`AppShell.Main`	`div`	--	Flex column holding the header and content beside the sidebar.
`AppShell.Header`	`header`	--	Sticky top bar. Renders a hamburger toggle automatically on mobile.
`AppShell.Content`	`main`	--	Scrollable content region. Accepts an optional `maxWidth` (e.g. "6xl").
`AppShell.MobileNav`	`nav`	--	Fixed bottom navigation bar, shown only on mobile when configured.
`AppShell.Overlay`	`div`	--	Scrim shown behind the open mobile drawer; clicking it closes the sidebar.