Layout
AppShell
Application layout with a module rail, a navigation panel, a mobile header and a bottom navigation, independent of any router.
<script lang="ts">
import { AppShellLayout, SiteHeader, type NavModule } from "@codeatlasdev/ui";
import { goto } from "$app/navigation"; // or any router
import { page } from "$app/state";
let { children } = $props();
const modules: NavModule[] = [/* id, label, icon, basePath, items */];
</script>
<AppShellLayout {modules} pathname={page.url.pathname} onNavigate={(path) => goto(path)}>
{#snippet header()}<SiteHeader />{/snippet}
{@render children()}
</AppShellLayout>The shell never imports a router. You pass the current pathname and handle onNavigate, so it works with SvelteKit, Astro, or plain state. onNavigate fires when the user switches module from the rail or the bottom navigation. Panel items are plain <a href> links, so a client-side router takes them over like any other link. Put it only on application routes, never on marketing pages. The panel is skipped for a module with fewer than two destinations, since it would only repeat the rail icon and the page title. Below 900px the rail and panel disappear and the mobile header plus bottom navigation take over. See the templates for complete applications built on it.
The rail magnifies the module icon under the pointer, like a dock. Only the glyph grows, never the button, so the hover background cannot cover the active neighbour. The effect follows the motion scale: it is off with motion: { scale: 0 } in the theme and under prefers-reduced-motion.
Anatomy
Rail (52px), panel (200px by default) and the main content area.
52px
200px
Reference #165 · Pick in the gallery
Code
Live shell
The real component inside a fixed-height frame. The pathname lives in local state; click the rail and panel to navigate.
Revenue
Users
Click a rail icon or a panel item. The demo keeps the pathname in local state.
Reference #166 · Pick in the gallery
Code
Panel width
panelWidth={280} with resizablePanel: drag the edge or focus it and use the arrow keys.
The panel starts at 280px and holds between 160px and 480px.
Reference #480 · Pick in the gallery
Code
Props
| Prop | Type | Default | Description |
|---|---|---|---|
modules | NavModule[] | – | Navigation modules. Each has id, label, icon, basePath, optional pathPrefixes and items (NavItem or NavSection). Prefixes match whole path segments and the longest one wins, so a module at `basePath: "/"` only gets the pages no other module claims. |
pathname | string | – | Current location. Decides the active module and item. An item at `path: "/"` is active on `/` only. |
onNavigate | (path: string) => void | – | Called with the first path of the module when the rail or the bottom navigation switches module. Panel items are links and do not call it. |
defaultModule | number | 0 | Module index used when the URL matches no module and none was stored. |
persistPanel | boolean | true | Keeps the shell across page loads: panel open or closed, selected module and expanded sections (localStorage), panel scroll (sessionStorage). Restored before the first paint. Turn it off for demos and embeds that must always start from the defaults. |
panelWidth | number | 200 | Width of the navigation panel in px, for lists with long labels. Held between 160 and 480. The content offset and the open and close animation follow it, so nothing misaligns. Prefer it to overriding `--ca-panel-width`, which the layout does not read. |
resizablePanel | boolean | false | Adds a drag handle on the panel's trailing edge. It is a keyboard-operable separator: Arrow keys move it by 8px, Shift by 32px, Home and End jump to the bounds. With `persistPanel` the chosen width is kept like the open state and restored before the first paint; `panelWidth` is the width used until the user picks one. |
reorder | Component | – | Pass the exported `NavReorder` to enable `onReorder` on sections and modules. Opt-in so the drag engine is only bundled by apps that reorder. |
itemMenu | Component | – | Pass the exported `NavItemMenu` to render `NavItem.actions` as a "…" menu. Opt-in so the dropdown menu is only bundled by apps that use it. |
header | Snippet | – | Desktop header rendered above the page content. Hidden below 900px. |
brand | Snippet | – | Logo shown at the top of the rail and in the mobile header. |
railBottom | Snippet | – | Items pinned to the bottom of the rail, such as an avatar or notifications. |
mobileHeaderActions | Snippet | – | Controls at the trailing edge of the mobile header. Use it for anything that must stay reachable below 900px. |
mobileTitle | Snippet | – | Replaces the plain page title in the mobile header, for example a tappable title that opens a sheet. |
mainId | string | null | 'main' | `id` of the content region, which is the page `<main tabindex="-1">` landmark and the skip link target. Pass `null` when your page renders its own `<main id="main" tabindex="-1">`: the region becomes a plain `div`. |
skipLink | boolean | true | Renders the SkipLink. Turn it off when the shell is embedded in a page that already has one. |
children | Snippet | – | Page content. |
Panel width
The panel is 200px by default. For lists with long names pass panelWidth (px, held between 160 and 480): the content offset and the open and close animation follow it, so the page never misaligns. Add resizablePanel to let people choose: a handle sits on the panel’s trailing edge and is a keyboard-operable separator (role="separator" with aria-valuenow, aria-valuemin and aria-valuemax). Arrow keys move it by 8px, Shift by 32px, Home and End jump to the bounds. While the pointer holds the edge the panel follows it with no spring in between. With persistPanel the width is stored with the open state and restored before the first paint; panelWidth is the width used until the user picks one. A stored width is ignored when resizablePanel is off, so the prop stays the contract.
Rich panel items
A NavItem takes more than an icon and a label:
| Field | What it does |
|---|---|
color |
A decorative dot before the label, any CSS color. The icon stays. |
leading |
A snippet that replaces the icon (a color swatch, an avatar, an emoji). Decorative: the label is the name. |
count |
A neutral total after the label (1.2k above 999). The link’s name carries the exact number, never “unread”. 0 renders. |
badge |
Unread-style count: announced “N unread”, capped at 99+. Use count for a plain total. |
actions |
A snippet of DropdownMenuItems. The row gets a “…” button named Actions for <label>, a sibling of the link, shown on hover and focus. Needs itemMenu={NavItemMenu} on the shell. |
Reordering is per list: set onReorder on a NavSection (or on the NavModule for the items that sit outside any section) and pass reorder={NavReorder} to AppShellLayout. Each row gets a grip that works with the mouse, touch (press and hold) and the keyboard (Space lifts, arrows move, Enter drops, Escape cancels), and every step is announced. It is the same useDnd engine as drag and drop. The shell never reorders items for you: commit the move in your state and the new order flows back in. onReorder is not called when the drop lands where it started.
NavReorder and NavItemMenu are opt-in on purpose: the drag engine and the dropdown menu are only bundled by apps that import them, so a shell without per-item menus or reordering stays small.
<script lang="ts">
import { AppShellLayout, DropdownMenuItem, NavItemMenu, NavReorder, type NavModule, type NavReorderEvent } from "@codeatlasdev/ui";
type Row = { id: string; name: string; color: string; count: number };
let rows = $state<Row[]>([]);
function archive() {}
function reorder(e: NavReorderEvent) {
const next = rows.slice();
next.splice(e.to, 0, ...next.splice(e.from, 1));
rows = next;
}
</script>
{#snippet menu()}
<DropdownMenuItem onclick={archive}>{#snippet children()}Archive{/snippet}</DropdownMenuItem>
{/snippet}
<!-- items: rows.map((r) => ({ id: r.id, label: r.name, icon: Folder, path: `/p/${r.id}`, color: r.color, count: r.count, actions: menu })) -->
<!-- <AppShellLayout {modules} {pathname} reorder={NavReorder} itemMenu={NavItemMenu}> -->Color, count, actions and reorder
Each row has a color dot, a neutral count and a … menu; drag a row by its grip.
Open the … menu of a row, or drag a row by its grip.
Reference #481 · Pick in the gallery
Code
State across page loads
On a multi-page site (Astro, a full reload) every link loads a new document, so a shell that only keeps state in memory reopens at its defaults: the panel, the module, the expanded groups and the panel scroll are all lost. With persistPanel (the default) the shell keeps them and puts them back before the first paint, the same way the theme script does.
| What | Where | Key |
|---|---|---|
| Panel open or closed, selected module, dragged panel width, section open map | localStorage |
ca-shell |
| Panel scroll, per module | sessionStorage |
ca-shell-scroll |
An inline script emitted right after the sidebar reads those keys and sets data-ca-panel="open|closed" and data-ca-module="<id>" on <html> before anything paints, so a panel the user closed is laid out closed from the first frame instead of flashing open. Stored values are validated and discarded when malformed. A section’s last open or closed choice wins over defaultOpen, but the section that holds the current page always opens. The module comes from the URL when modules matches it, and from the stored choice otherwise.
Render the shell on the server so the first paint is not blank: the inline script and the markup travel together. A client-only mount gets the same restore on hydration, and a page whose CSP blocks inline scripts too. Keep id stable on each NavModule (it is the stored module key) and each section label unique within a module (it is the stored section key).
Building blocks for a custom panel
AppShellLayout renders the panel for you. Rail, Panel, BottomNav and MobileHeader are exported too, and two of them are the pieces to reuse when you lay out your own navigation: PanelNavItem is the row the panel draws for one NavItem (icon or leading, color dot, label, count, unread badge, new dot, the actions menu and the active pip), and SectionGroup is a titled group of items that collapses.
<script lang="ts">
import { PanelNavItem, SectionGroup, type NavSection } from "@codeatlasdev/ui";
const section: NavSection = { label: "Reports", collapsible: true, items };
</script>
<SectionGroup {section} {pathname} />
<PanelNavItem item={items[0]} isActive={pathname === items[0].path} href={items[0].path} />PanelNavItem renders a row with a plain <a> inside it (aria-current="page" when active); the actions button and the grip are siblings of the link, because a link cannot contain controls. SectionGroup opens itself when it holds the current page, and inside an AppShellLayout with persistPanel it stores its open state under the section label; a bare SectionGroup keeps nothing.
PanelNavItem props
| Prop | Type | Default | Description |
|---|---|---|---|
item | NavItem | – | The destination: `id`, `label`, `icon`, `path`, and optional `badge`, `count`, `color`, `leading`, `actions`, `isNew`, `shortcut`, `description`. Required. |
isActive | boolean | – | Marks the row as the current page (`aria-current="page"`, active pip). Required. |
href | string | – | Link target. Required. |
grip | boolean | false | Adds the drag grip. Set it when the list the row sits in is reorderable (`NavSection.onReorder`). |
describedby | string | – | `id` of the node that describes the keyboard drag (`dnd.instructionsId`), set on the grip. |
class | string | '' | Extra class names. |
SectionGroup props
| Prop | Type | Default | Description |
|---|---|---|---|
section | NavSection | – | `label`, `items`, and optional `collapsible` (default `true`), `defaultOpen` (default `true`) and `onReorder` (makes the items reorderable). Required. |
pathname | string | – | Current location, used to mark the active item and to keep the group holding it open. Required. |
class | string | '' | Extra class names. |