AppFrame
Full-page application shell with persisted collapsible sidebar. Includes a signal-driven top progress bar with determinate progress, error state, and dismissible error strip.
Category: layout · WCAG 2.1-AA · layout, shell, sidebar, navigation
States
- expanded
- collapsed
- loading
- error
Props
| Prop | Type | Default | Description |
|---|---|---|---|
footer | ReactNode | — | Optional sticky footer rendered below the content area. |
sideNavMode | 'push' | 'overlay' | push | push (default): sidebar takes grid space; overlay: sidebar floats over content. |
header | ReactNode | — | Top header slot |
sideNav | ReactNode | — | Side navigation slot |
aside | ReactNode | — | Right aside slot |
children | ReactNode | — | Main content |
persistKey | string | false | cascade.appshell | localStorage key prefix. Pass false to disable persistence. |
state | ShellState | — | External shell state from createShellState(). Created internally when omitted. |
Design tokens
--cascivo-space-3--cascivo-space-4--cascivo-space-6--cascivo-duration-200--cascivo-ease-out--cascivo-color-border--cascivo-color-surface--cascivo-text-xs--cascivo-color-accent--cascivo-color-destructive--cascivo-color-destructive-subtle--cascivo-focus-ring
When to use
- A full-page application frame with header, collapsible sidebar, and content
- You need a bare shell to compose your own navigation into
When not to use
- You want opinionated, prewired sidebar navigation — use SidebarApp
- A simple centered content page — use Section or Center
- You just need a drop-in header + toggleable nav with no persistence — use the published `AppShell` from @cascivo/react (a `nav` prop, no copy-paste), not this richer copy-paste shell.
Examples
Basic
App shell with collapsible nav
<AppFrame header={<Header />} sideNav={<Nav />}>content</AppFrame>Related components
- AppShell (@cascivo/react) — The published, self-contained AppShell: header + a single `nav` slot with an animated accessible drawer, no persistence/progress/aside. Simpler prop surface (`nav` vs this frame’s `sideNav`/`aside`/`persistKey`/`state`). Use it for a quick drop-in; use this copy-paste frame when you need persisted collapse, a progress bar, or a right aside. This entry used to be called `AppShell` too — one name for two incompatible prop surfaces — and was renamed to `AppFrame` so an import can only mean one thing.
- SidebarApp — Use the opinionated block when you want prewired sidebar nav
- DashboardLayout — Use for a stats-strip dashboard page rather than a bare shell