# AppShell
> The product frame every Nasaq app uses - resizable, collapsible sidebar at the inline start, sticky header, main area, mobile sheet, and the command registry.
Source: https://docs.nasaqui.com/components/app-shell
## Install
```bash
npx shadcn@latest add https://docs.nasaqui.com/r/app-shell.json
```
The frame every product re-solved: a sidebar at the inline start, a sticky header, and the page.
`AppShell` also owns three things you would otherwise wire by hand:
- **Sidebar state.** It collapses to an icon rail, can be dragged to resize, remembers both in
`localStorage`, and moves into a sheet below the `md` breakpoint (48rem).
- **The command registry.** It renders a `CommandProvider`, so `useRegisterCommands` and
`` work anywhere inside it with no extra setup.
- **Shared open state** for the palette, so `SearchTrigger` can open it.
The sidebar is built from small parts (`Sidebar`, `SidebarGroup`, `SidebarItem`, `SidebarNest`…) that
know whether they are on the collapsed rail and adapt: labels hide, tooltips and accessible names appear.
Two frames, one component:
- **Sidebar navigation** (pass `sidebar`). Add `variant="inset"` to put the page on its own rounded
panel, inset from the sidebar's surface, and `SidebarStatus` for the "All systems normal" line
above the user.
- **Top navigation** (leave `sidebar` out). The header carries the path as `AppBreadcrumbs` with
⇅ switchers and tags (organisation / project / environment), `AppNav` puts section tabs under it,
and `AppFooter` closes the page. Good for apps whose sections fit in one row.
Both share `AppPageHeader`: the page's big title, a line under it, and its controls (a time range,
filters, the main action) at the inline end.
## When to use
- The root layout of any product with more than one screen.
- You need a collapsible sidebar with workspace switcher, search, navigation and user menu.
- A few sections under one resource (a project, a server, a site): top navigation with a path and tabs.
## When not to use
- A single-purpose page, marketing site or auth screen: use plain layout primitives.
- Switching between products: use [`ProductSwitcher`](https://docs.nasaqui.com/components/product-switcher) inside the shell.
- Letting users reorder or hide sidebar items: add [`sidebar-layout`](https://docs.nasaqui.com/components/sidebar-layout) on top.
- Hand-rolling a second sidebar nested in the page: the shell supports one.
## Import
```tsx
import {
AppShell, AppHeader, AppMain, SidebarTrigger,
Sidebar, SidebarBrand, SidebarHeader, SidebarContent, SidebarFooter,
SidebarGroup, SidebarItem, SidebarNest, SidebarSubItem,
} from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"
```
## Quick start
```tsx
import {
AppHeader,
AppMain,
AppShell,
Breadcrumb,
BreadcrumbItem,
BreadcrumbList,
BreadcrumbPage,
Sidebar,
SidebarBrand,
SidebarContent,
SidebarGroup,
SidebarHeader,
SidebarItem,
SidebarTrigger,
} from "@fadymondy/nasaq/web";
import { Inbox, LayoutDashboard } from "lucide-react";
function AppSidebar() {
return (
} active>
Dashboard
} trailing="12">
Inbox
);
}
export function Layout({ children }: { children: React.ReactNode }) {
return (
}>
Dashboard{children}
);
}
```
`AppShell` must sit inside `NasaqProvider` (it reads the locale). `SidebarItem` renders a native ``
and has no `render` prop, so drive client-side routing through `href` and `onClick`.
## Anatomy
```
AppShell data-slot="app-shell" (flex row, min-h of 100dvh minus `--nasaq-shell-offset`)
├─ aside data-slot="app-sidebar" data-collapsed, data-resizing; md+ only
│ ├─ your `sidebar` node (SidebarRailContext = collapsed)
│ └─ resize handle data-slot="sidebar-resize-handle" role="separator"
├─ mobile sheet (Dialog) data-slot="app-shell-sheet" below md, opened by SidebarTrigger / ⌘B
│ └─ your `sidebar` node (never collapsed inside the sheet)
└─ column (children; inside app-shell-panel when variant="inset")
├─ AppHeader data-slot="app-header"
│ ├─ SidebarTrigger first (sidebar frame)
│ └─ AppBreadcrumbs data-slot="app-breadcrumbs" (top frame)