AppShell
A complete application shell that composes LeftNav, TopBar, and main content area. Provides responsive layout coordination, controlled or uncontrolled navigation state, and automatic spacing for fixed headers.
Quick Start
Set up AppShell with navigation items and content slots
Quick Start
Basic Setup
Define navigation items
import { LeftNavItem } from '@dashforge/ui';
const navItems: LeftNavItem[] = [
{
id: 'dashboard',
type: 'item',
key: 'dashboard',
label: 'Dashboard',
icon: <DashboardIcon />,
},
{
id: 'users',
type: 'item',
key: 'users',
label: 'Users',
icon: <PeopleIcon />,
},
];Render the AppShell
import { AppShell } from '@dashforge/ui';
<AppShell
items={navItems}
topBarLeft={<Typography variant="h6">My App</Typography>}
topBarRight={<UserMenu />}
>
<YourContent />
</AppShell>✓
AppShell automatically handles responsive layout, drawer state, and spacing for fixed headers.
Examples
Interactive demos showing common usage patterns
Basic AppShell
Complete application shell with navigation
LeftNav
Home
Analytics
Users
Settings
TopBar
Main Content Area
AppShell composes LeftNav, TopBar, and main content into a complete application layout with automatic responsive behavior and state management.
<AppShell
items={navItems}
topBarLeft={<Logo />}
topBarRight={<UserMenu />}
>
<MainContent />
</AppShell>Real-World Scenarios
Common use cases and implementation patterns
Router Integration
Integrate AppShell with React Router
Example pattern below
import { Link } from 'react-router-dom';
<AppShell
items={navItems}
renderLink={(item, children) => (
<Link to={item.key}>{children}</Link>
)}
isActive={(item) => location.pathname === item.key}
>
<Outlet />
</AppShell>Controlled Navigation State
Control drawer state externally
Example pattern below
const [navOpen, setNavOpen] = useState(true);
<AppShell
items={navItems}
navOpen={navOpen}
onNavOpenChange={setNavOpen}
>
<Content />
</AppShell>Custom TopBar Slots
Add custom content to TopBar
Example pattern below
<AppShell
items={navItems}
topBarLeft={<Typography variant="h6">My App</Typography>}
topBarCenter={<SearchBar />}
topBarRight={
<>
<NotificationButton />
<UserMenu />
</>
}
>
<Content />
</AppShell>API Reference
Complete API documentation
AppShell Props
| Prop | Type | Required | Description |
|---|---|---|---|
| items | LeftNavItem[] | Yes | Navigation items for LeftNav |
| renderLink | RenderLinkFn | No | Router-agnostic link renderer |
| isActive | IsActiveFn | No | Callback to determine if item is active |
| navOpen | boolean | No | Controlled drawer open state |
| defaultNavOpen | boolean | No | Default drawer open state (default: true) |
| onNavOpenChange | (open: boolean) => void | No | Callback when drawer state changes |
| navWidthExpanded | number | No | Width when expanded (default: 280) |
| navWidthCollapsed | number | No | Width when collapsed (default: 64) |
| breakpoint | 'sm' | 'md' | 'lg' | 'xl' | No | Mobile breakpoint (default: lg) |
| topBarLeft | ReactNode | No | Left content slot for TopBar |
| topBarCenter | ReactNode | No | Center content slot for TopBar |
| topBarRight | ReactNode | No | Right content slot for TopBar |
| topBarPosition | AppBarProps['position'] | No | TopBar position (default: 'fixed') |
| leftNavHeader | ReactNode | No | Header slot for LeftNav |
| leftNavFooter | ReactNode | No | Footer slot for LeftNav |
| children | ReactNode | Yes | Main content to render |
| mainSx | SxProps<Theme> | No | Optional sx props for main container |
Implementation Notes
Important details about behavior and best practices
Responsive Behavior
AppShell automatically switches between desktop and mobile layouts based on the breakpoint prop. On mobile, LeftNav becomes a temporary drawer that overlays content.
Navigation State
Supports both controlled and uncontrolled modes. Use navOpen/onNavOpenChange for controlled state, or defaultNavOpen for uncontrolled mode.
Router Integration
AppShell is router-agnostic. Use the renderLink prop to integrate with React Router, Next.js router, or any other routing solution.
Fixed TopBar Spacing
When topBarPosition is 'fixed', AppShell automatically adds a Toolbar spacer to prevent content from being hidden under the fixed header.
Main Content Offset
The main content area automatically adjusts its left margin based on LeftNav width and open/closed state for smooth transitions.