--- title: Shell description: A collapsible, resizable sidebar beside the viewport it shares the screen with, with hover-peek and cookie persistence. source: shell --- ```tsx title="primitives/shell/demos/basic.tsx" "use client"; import { Nav } from "@intentface/chat/nav"; import { Shell } from "@intentface/chat/shell"; import type { ComponentProps } from "react"; /* * A shell the way it is meant to be used: a sidebar that collapses, floats out * on hover and drags wider, holding a real Nav, beside the content card it * shares the screen with. * * The load-bearing arrangement is the one that is easy to get wrong. The * sidebar is taken *out of flow* and a plain spacer — the gutter — holds its * place. That is what lets all three states be one element morphing between * three positions: flush while expanded, off-canvas while collapsed, floating * just inside the edge while peeking. A sidebar left in flow can only animate * its own width, so it can never float over the content, and the peek has * nothing to slide across. * * `absolute` inside a `relative` root because this is a box on a docs page; a * real app shell uses `fixed` against the window. */ export const Basic = () => ( {/* Not rendering this is how you opt out of hover-peek. */} {/* The gutter. Not a part of the package: a div reading the property the resize handle writes, animating to zero while the panel slides away. */}

{/* Same columns as a nav row: pl-4 puts the badge where a row's icon sits (Nav px-2 + row px-2), the badge is icon-sized, and gap-2 lands the title where a row's label starts. */}

ui @intentface/chat

{/* The nav is its own primitive — see the Nav page for the tree, the rail and the keyboard model. Here it is just what a sidebar holds. */} } className="flex min-h-0 flex-1 flex-col gap-0.5 overflow-auto px-2 pb-2" > Overview Inbox Workspace {["Initiatives", "Projects", "Views", "Loops"].map((label) => ( {label} ))} {/* A 6px hit area with a hairline inside, so the target is comfortable while the divider stays thin. */} {/* The gutter only exists while the sidebar does: collapsed, the card runs edge to edge. */}

Docs Overview

Overview

Collapse the sidebar with the button in its header, then rest the pointer against the left edge to float it back out as a card. Drag the divider to resize it, or nudge it with the arrow keys once the handle has focus.

The width and the range it may be dragged through are this stylesheet's; the primitive only measures and reports back.

); const iconButtonClass = "grid size-7 shrink-0 cursor-pointer select-none place-items-center rounded-md text-[#686868] transition-colors hover:bg-[#f4f4f4] hover:text-[#1a1a1a] focus-visible:-outline-offset-2 focus-visible:outline-2 focus-visible:outline-[#1a1a1a] dark:text-[#9b9b9b] dark:hover:bg-[#232323] dark:hover:text-[#fcfcfc] dark:focus-visible:outline-[#fcfcfc]"; // An explicit height is load-bearing: 14px text has a fractional line-height, // so padded rows land on a fraction of a pixel and nothing lines up. const rowClass = [ "group/row flex h-8 shrink-0 cursor-pointer select-none items-center gap-2 rounded-md px-2 text-sm", "text-[#686868] transition-colors hover:bg-[#f4f4f4] hover:text-[#1a1a1a] dark:text-[#9b9b9b] dark:hover:bg-[#232323] dark:hover:text-[#fcfcfc]", "focus-visible:-outline-offset-2 focus-visible:outline-2 focus-visible:outline-[#1a1a1a] dark:focus-visible:outline-[#fcfcfc]", "data-[active]:bg-[#ececec] data-[active]:text-[#1a1a1a] dark:data-[active]:bg-[#2d2d2d] dark:data-[active]:text-[#fcfcfc]", "[&_svg]:size-4 [&_svg]:shrink-0", ].join(" "); const PanelLeftIcon = (props: ComponentProps<"svg">) => ( ); const HomeIcon = (props: ComponentProps<"svg">) => ( ); const InboxIcon = (props: ComponentProps<"svg">) => ( ); const BoxIcon = (props: ComponentProps<"svg">) => ( ); const ChevronIcon = (props: ComponentProps<"svg">) => ( ); ``` The sidebar above holds a [Nav](/primitives/nav); the two are separate primitives that happen to be built for each other. ## Usage guidelines - **App shell, not a chat part** — the sidebar-and-viewport frame an app sits in. - **No global keys** — the package claims none; bind your own around `toggle`. Only the resize handle's arrow keys are local enough to belong here. - **Width is CSS** — the sidebar's size and the range the drag may move it through are `width` / `min-width` / `max-width` in your stylesheet. The primitive measures; it never sizes. - **Hover-peek** — a collapsed sidebar floats back out when the pointer rests against the screen edge. Render `Shell.PeekZone` to opt in; omit it to opt out. - **Persists nothing itself** — `open` goes out through `onOpenChange` and back as `defaultOpen`; the width goes out through the sidebar's `onResize` and back as CSS. Where it is kept is yours, and reading it from the request keeps the first paint right. - **State via `useShell`** — read open, peek, resizing and the measured width from anywhere inside. - **Get started** — see [Quick start](/quick-start) to add the package. ## Anatomy ```tsx ``` A shell whose sidebar starts where the visitor left it. Note the gutter — it is not a part of the package, and it is the piece that makes the rest work: ```tsx {children} ``` ## Layout: take the sidebar out of flow This is the arrangement everything else depends on, and the one that is easy to get wrong. The sidebar is **positioned**, not a flex item, and a plain spacer — a gutter — holds its place in the layout: ```css [data-shell-sidebar] { position: fixed; inset-block: 0; left: 0; width: var(--shell-sidebar-width, 240px); /* Opaque in every state: the content passes beneath the panel while the two animate, and a transparent expanded state would show it through. */ background: var(--chrome); } /* The gutter: your own div, reading the property the handle writes. */ [data-slot="shell-gutter"] { width: var(--shell-sidebar-width, 240px); flex-shrink: 0; transition: width 150ms linear; } [data-shell][data-state="collapsed"] [data-slot="shell-gutter"] { width: 0; } ``` That split is what lets all three states be one element morphing between three positions — flush while expanded, off-canvas while collapsed, floating just inside the edge while peeking. A sidebar left in flow can only animate its own width, so it can never float *over* the content, and the peek has nothing to slide across. It also means the collapse animates two cheap properties on two different elements — `left` on the panel, `width` on the gutter — rather than fighting one element to do both. ## Sizing The drag range is `min-width` and `max-width` on the sidebar — that pair *is* the whole configuration, and there is no prop for it: ```css [data-shell-sidebar] { min-width: 200px; max-width: 380px; } ``` The handle writes `--shell-sidebar-width` on the root, the browser clamps it against those bounds, and the sidebar reports back whatever the browser settled on — which is the number that gets persisted and announced as `aria-valuenow`. Measure in JS, size in CSS; nothing here second-guesses your stylesheet. Publishing the variable on the root rather than the sidebar is what lets the gutter read the same number, and anything else in the shell size itself to match. ## Hover-peek With the sidebar collapsed, resting the pointer in the edge strip floats it out as a card; leaving both the card and the strip slides it away after a grace period. Both delays are intent filters — a pointer merely crossing the strip never opens it, and clipping a corner on the way to the panel never loses it. Collapse the demo above and hover its left edge to see it. The card geometry is worth baking into the *whole* collapsed state rather than into `data-peek` alone: ```css [data-shell-sidebar][data-state="collapsed"] { left: calc(-1 * var(--shell-sidebar-width)); inset-block: 0.5rem; border-radius: 0.75rem; } [data-shell-sidebar][data-state="collapsed"][data-peek] { left: 0.5rem; } ``` Off-canvas the card is invisible anyway, so the peek animates `left` only — no vertical movement, and the inset never grows mid-slide. Only expand and collapse morph card ↔ flat. Peek is never persisted, and it only means anything while collapsed. Clicking the trigger inside a peeked sidebar pins it open rather than closing it. ## Keyboard There is no global key binding in the package, and that is deliberate: it cannot know which combinations your app has already spent, and a window-level `keydown` claimed by a library is a collision waiting to happen. `toggle` is all a binding needs — it pins a peeking sidebar open rather than closing it: ```tsx const SidebarShortcut = () => { const toggle = useShell((shell) => shell.toggle); useEffect(() => { const handleKeyDown = (event: KeyboardEvent) => { if (event.key !== "b" || !(event.metaKey || event.ctrlKey)) return; event.preventDefault(); toggle(); }; window.addEventListener("keydown", handleKeyDown); return () => window.removeEventListener("keydown", handleKeyDown); }, [toggle]); return null; }; ``` `Shell.ResizeHandle` does own its keys, because those are local rather than global: with the handle focused, the arrow keys nudge the width by `step`. ## useShell Read shell state from anywhere inside ``. Pass a selector so a component re-renders only for the value it reads: ```tsx const collapsed = useShell((shell) => !shell.open); ``` export const hookMembers = [ { name: "open", type: "boolean", description: "Whether the sidebar is expanded." }, { name: "peek", type: "boolean", description: "The collapsed sidebar is floating out on hover. Never persisted." }, { name: "resizing", type: "boolean", description: "True for the duration of a resize drag, so parts can suppress transitions." }, { name: "width", type: "number | null", description: "The width the browser settled on. Null until the sidebar has mounted and been measured." }, { name: "setOpen", type: "(open: boolean) => void", description: "Expand or collapse." }, { name: "toggle", type: "() => void", description: "Flip it; a peeking sidebar expands in place rather than closing. This is what an app's keyboard shortcut calls." }, { name: "setPeek", type: "(peek: boolean) => void", description: "Float a collapsed sidebar out, or put it away. Ignored while it is already open." }, { name: "setResizing", type: "(resizing: boolean) => void", description: "Marks a drag in progress, which is what defers the settled-width report." }, { name: "setWidth", type: "(width: number) => void", description: "Reports a measurement. Not a request to resize — CSS decides the size." }, ]; To drive the same state from outside the tree — a command palette, a global shortcut handler — create the store yourself and pass it in: ```tsx const store = Shell.createStore(); {/* … */}; // Anywhere, including outside the tree: const open = useShellStore(store, (shell) => shell.open); ``` There is deliberately no global fallback, so shell state is never read or driven by accident from somewhere that merely imported this. ## Persistence `Shell` persists nothing and knows nothing about where you keep things. `open` goes **out** through `onOpenChange` and comes back **in** as `defaultOpen`. Format, key, cookie flags, per-browser or per-user account — all yours, and all changeable without waiting on a release here. The one thing worth stating plainly: the value has to arrive as a prop. Reading storage at init is a client-only act, so a server-rendered shell would paint the default layout and snap to the stored one a frame later — the flash the whole arrangement exists to avoid. ```tsx // app/layout.tsx — a server component const stored = readSidebarLayout((await cookies()).toString()); return ; ``` ```tsx // Writing is a client-only act, so it goes in the callback. save({ open })}> ``` ### Width goes back as CSS, not as a prop There is deliberately no `defaultWidth`. The width already lives in your stylesheet — the resize handle writes `--shell-sidebar-width` and your rule reads it — so restoring one means setting that property, which is the same mechanism rather than a second one: ```tsx ``` Coming the other way, `Shell.Sidebar`'s `onResize` reports a **settled** width — once when a drag ends, not once per frame. That debounce is the one piece of persistence machinery worth having in the package, because it depends on knowing a drag is in progress. Everything else is yours: ```tsx save({ width })} /> ``` A cookie is worth choosing over `localStorage` for exactly one reason: it is readable from the request, which is what makes the server read above possible. And validate on the way in — stored state outlives the code that wrote it, so a value from an older release or a half-written entry should fall back to the defaults rather than reach your tree. ## Accessibility `Shell.Trigger` is a `