---
title: Shell
description: A collapsible, resizable sidebar beside the viewport it shares the screen with, with an edge hotspot 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 {
IconBox,
IconChevronDown,
IconHome,
IconInbox,
IconLayoutSidebar,
} from "@tabler/icons-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 the hotspot holds it out. A sidebar left in flow can only animate
* its own width, so it can never float over the content, and the hotspot 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 hotspot. */}
{/* The gutter. Not a part of the package: a div reading the property the
grip 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"
>
OverviewInboxWorkspace
{["Initiatives", "Projects", "Views", "Loops"].map((label) => (
{label}
))}
{/* A sibling of the sidebar, not a child: the sidebar clips its overflow
for the collapsed card, so a handle hung off its edge would be cut in
half. Positioned instead against the viewport's left edge — the 6px hit
area straddles the content card's border, so the hairline it reveals
lands exactly on the line already drawn there. */}
{/* 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(" ");
```
## Usage guidelines
- **App shell, not a chat part** — the sidebar-and-viewport frame an app sits in. The sidebar in the demo holds a [Nav](/primitives/nav); the two are separate primitives built for each other.
- **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.
- **No global keys** — the package claims none, because it cannot know which combinations your app has already spent. Bind your own around `toggle`.
- **Hotspot is opt-in** — render `Shell.Hotspot` and a collapsed sidebar floats back out when the pointer rests against the screen edge. Omit the part to opt out; there is no prop, because not rendering it already says so.
- **Persists nothing itself** — state goes out through `onOpenChange` and `onResize`, and comes back as `defaultOpen` and a CSS custom property. Where it is kept is yours.
- **The sidebar must leave the flow** — see [Why the sidebar is positioned](#why-the-sidebar-is-positioned). This is the one arrangement everything else depends on.
- **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
save({ width })}>
{children}
```
## Examples
### Setting the drag range
`min-width` and `max-width` on the sidebar are the whole configuration, and
there is no prop for either. The range below is deliberately narrow, so both
stops are a short drag away.
```tsx title="primitives/shell/demos/range.tsx"
"use client";
import { Shell, useShell } from "@intentface/chat/shell";
/*
* The drag range, made obvious by making it small: 160px to 260px, so both
* stops are a short drag away.
*
* Nothing here configures the range. `min-width` and `max-width` on the
* sidebar are the whole configuration — the grip reads them off computed style
* when a drag starts, clamps against them, and writes the result back as
* `--shell-sidebar-width`. The readout is the measurement coming back out, and
* it is the same number `aria-valuenow` announces.
*/
export const Range = () => (
Drag the divider
{/* A 6px hit area with a hairline inside, so the target is comfortable
while the divider stays thin. */}
The sidebar stops at 160px and 260px. The browser clamps it, not the primitive.
);
/**
* `width` is what the browser settled on after clamping, not what the drag
* asked for — which is why it stops moving at the bounds even while the
* pointer keeps going.
*/
const WidthReadout = () => {
const width = useShell((shell) => shell.width);
return (
);
};
```
```css
[data-shell-sidebar] {
min-width: 200px;
max-width: 380px;
}
```
The grip writes `--shell-sidebar-width` on the root, the browser clamps it
against those bounds, and the sidebar reports back whatever the browser settled
on. That number is what gets persisted and announced as `aria-valuenow`.
### Styling the grip
The grip is a bare div with a role and some keys, so the whole appearance is
yours. This one draws nothing at rest and fades in an iOS-style pill that rides
the pointer vertically, clamped by half its own height at each end so it never
hangs out of the track.
The pointer position goes straight into a custom property rather than React
state. A `pointermove` that re-rendered would re-render the whole shell on every
frame of a drag, and there is nothing here React needs to know — only a number
CSS reads. Passing `onPointerMove` is safe because the primitive merges handlers
rather than replacing them, so the drag on that same event still runs.
```tsx title="primitives/shell/demos/grip.tsx"
"use client";
import { Shell } from "@intentface/chat/shell";
/*
* Styling the grip: an iOS-style pill that fades in on hover and rides the
* pointer vertically.
*
* The grip is a bare div with a role and some keys — no shadow DOM, no
* built-in affordance — so the whole appearance is yours. Nothing is drawn at
* rest; the pill is a child, faded in on hover and positioned from `--grip-y`.
*
* The pointer position is written straight to a custom property rather than
* held in React state. A pointermove that re-rendered would re-render the
* whole shell on every frame of a drag, and there is nothing here React needs
* to know about — only a number CSS reads.
*
* `onPointerMove` is safe to pass: the primitive merges handlers rather than
* replacing them, so the drag it runs on the same event still happens.
*/
export const Grip = () => (
{
event.currentTarget.style.setProperty("--grip-y", `${event.nativeEvent.offsetY}px`);
}}
className={[
// A 20px hit area straddling the sidebar's edge. Wide enough for a
// fingertip, while the 4px pill drawn inside it stays thin — which
// is the point of separating the target from the affordance.
"group/grip -right-2.5 absolute inset-y-0 w-5 cursor-col-resize select-none",
"focus-visible:-outline-offset-2 focus-visible:outline-2 focus-visible:outline-[#1a1a1a] dark:focus-visible:outline-[#fcfcfc]",
].join(" ")}
>
Move the pointer onto the sidebar's right edge. The handle appears and follows it.
);
```
### Styling the hotspot
Resting the pointer on `Shell.Hotspot` floats a collapsed sidebar out as a card,
and every part in the shell carries `data-hotspot` while it is out. Bake the card
geometry into the whole collapsed state rather than into `data-hotspot` alone, so
only `left` animates as it slides. The demo starts collapsed and tints the
hotspot, which is invisible in a real app.
```tsx title="primitives/shell/demos/hotspot.tsx"
"use client";
import { Shell, type ShellStore, useShell, useShellStore } from "@intentface/chat/shell";
import { useState } from "react";
/*
* Starts collapsed, so the hotspot is the first thing there is to try: rest the
* pointer on the strip at the left edge and the sidebar floats out as a card.
* Two ways back: the header control, reached through the hotspot once the
* sidebar is away, and the button under the shell, which drives the same state
* from outside the tree through a `Shell.createStore()` handle.
*
* `Shell.Hotspot` is the part; `hotspot` is the state it produces. The hotspot is
* the hit area you hover, and while the pointer rests there the sidebar and
* everything else in the shell carry `data-hotspot`.
*
* The card geometry is baked into the whole collapsed state rather than into
* `data-hotspot` alone. Off-canvas the card is invisible anyway, so the hotspot then
* animates `left` and nothing else — no vertical movement, no radius appearing
* mid-slide. Only expand and collapse morph card to flat.
*/
export const HotspotDemo = () => {
const [store] = useState(() => Shell.createStore());
return (
{/* Invisible in a real app. Tinted here so there is something to aim at,
since the whole point is a hit area you cannot otherwise see.
It sits *under* the sidebar, so the card tucks the strip away as it
slides out. Nothing is lost by that: `Shell.Sidebar` carries its own
hold handler, so the hotspot survives the pointer moving from the strip
onto the card even though the strip is no longer beneath it.
Not rendering this part at all is how you opt out of hotspot. */}
);
};
/**
* The label has to name the action, not the part. While the hotspot is holding the sidebar out
* it is collapsed but visible, and pressing the trigger pins it open rather
* than closing it — so "Hide" would be wrong in exactly the state this demo
* spends most of its time in.
*/
const TriggerLabel = () => {
const open = useShell((shell) => shell.open);
return (
{open ? "Hide" : "Pin"}
);
};
```
```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-hotspot] {
left: 0.5rem;
}
```
Off-canvas the card is invisible, so nothing moves vertically mid-slide. Only
expand and collapse morph card to flat. Hotspot is never persisted, and it means
nothing while the sidebar is open.
### Driving the shell from outside
Pass a `Shell.createStore()` handle to the Root and anything holding the same
handle can read and drive the state, including a control that is not inside the
tree at all. The package binds no global keys, so the shortcut below is the
app's own; `toggle` pins a floated-out sidebar open rather than closing it.
Press Cmd or Ctrl and B with the pointer over the demo. The hover test in the
source is this page's problem rather than yours, since a docs page carries many
demos and a search field; an app binds the key for its whole window.
```tsx title="primitives/shell/demos/external.tsx"
"use client";
import { Shell, type ShellStore, useShellStore } from "@intentface/chat/shell";
import { useEffect, useState } from "react";
/*
* Driving the shell from outside its tree, and binding a key to it.
*
* `Shell.createStore()` is the handle. Pass it to the Root and the primitive
* uses it instead of making its own, which means anything holding the same
* handle can read and drive the state — including the button under the shell,
* which is a sibling of the Root rather than a descendant, and so could never
* have reached it through context.
*
* The store is created inside `useState` so it survives re-renders. Creating
* it during render would hand the Root a different store every time.
*/
export const External = () => {
const [store] = useState(() => Shell.createStore());
// The element the shortcut is scoped to. A real app binds the key for the
// whole window and needs no such ref; this one shares a page with other
// demos and with the docs' own search field.
const [host, setHost] = useState(null);
return (
{/* Outside Shell.Root entirely — it reaches the state through the store
handle, not through context. */}
);
};
/**
* A sibling of the Root, not a child. It reads the same state the sidebar
* renders from, and calls the same action the built-in trigger would.
*/
const ExternalTrigger = ({ store }: { store: ShellStore }) => {
const open = useShellStore(store, (shell) => shell.open);
return (
);
};
/**
* The package binds no global keys, because it cannot know which combinations
* the surrounding app has already spent. Binding one is a few lines, and
* `toggle` is all it needs — a floated-out sidebar is pinned open rather than
* closed. Press Cmd/Ctrl + B with the pointer over this demo.
*
* The `host` test is this page's problem, not yours: a docs page carries many
* demos and a search field, so a bare window listener here would swallow
* Cmd/Ctrl + B everywhere on it. An app binding its own shortcut drops the
* check and keeps the rest.
*/
const Shortcut = ({ store, host }: { store: ShellStore; host: HTMLElement | null }) => {
useEffect(() => {
if (!host) return;
const onKeyDown = (event: KeyboardEvent) => {
if (event.key !== "b" || !(event.metaKey || event.ctrlKey)) return;
if (!host.matches(":hover") && !host.contains(document.activeElement)) return;
event.preventDefault();
store.getSnapshot().toggle();
};
window.addEventListener("keydown", onKeyDown);
return () => window.removeEventListener("keydown", onKeyDown);
}, [store, host]);
return null;
};
```
### Persisting across sessions
The stored 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 this arrangement exists to
avoid. A cookie is worth choosing over `localStorage` for that one reason: it is
readable from the request.
```tsx
// app/layout.tsx — a server component
const stored = readSidebarLayout((await cookies()).toString());
return ;
```
The width goes back as the custom property, not as a prop, because that is
where it already lives:
```tsx
save({ open })}
style={stored?.width ? { "--shell-sidebar-width": `${stored.width}px` } : undefined}
>
```
Validate on the way in. Stored state outlives the code that wrote it, so a
value from an older release should fall back to the defaults rather than reach
your tree.
## Why the sidebar is positioned
Taking the sidebar out of flow is not a styling preference, and the primitive
does not work without it.
All three states are one element morphing between three positions: flush while
expanded, off-canvas while collapsed, floating slightly inside the edge while the
hotspot holds it out. A sidebar left in flow can only animate its own width. It can never
float over the content, so the hotspot has nothing to slide across and the state
has nowhere to exist.
The gutter is what makes the layout still add up once the panel has left it.
Because the gutter reads the same custom property the grip writes, the two stay
in agreement at every width without either knowing about the other. Collapsing
then animates two cheap properties on two different elements — `left` on the
panel and `width` on the gutter — rather than fighting one element to do both.
```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 grip 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;
}
```
## Keyboard
Only the grip claims keys, and only while it has focus. Everything else is
yours to bind.
export const shellKeys = [
{ keys: "Arrow left", description: "Narrows a left sidebar by `step` pixels, and widens a right one." },
{ keys: "Arrow right", description: "Widens a left sidebar by `step` pixels, and narrows a right one." },
{ keys: "Tab", description: "Moves focus to the grip, which is a focusable separator so resizing is never mouse-only." },
];
## API reference
Every part accepts `className`, `style`, and `render` (see
[Styling](/handbook/styling)) and emits a bespoke part attribute
(`data-`) unless noted. `className` and `style` may be functions of the
part's state.
### Shell.Root
The provider and container. Holds the store every other part reads, so
`defaultOpen` and the width must arrive here rather than on a child. Renders a
`
` element.
export const rootProps = [
{ name: "defaultOpen", type: "boolean", description: "Where the sidebar starts when nothing controls it. Read it from the request so the first paint is already right." },
{ name: "open", type: "boolean", description: "Controlled open state." },
{ name: "onOpenChange", type: "(open: boolean) => void", description: "Fires on every open/close. Persist it here." },
{ name: "store", type: "ShellStore", description: "An explicit Shell.createStore() handle, for state reachable from outside this tree. Must be stable for the Root's lifetime." },
];
export const rootAttrs = [
{ attribute: "data-shell", description: "The container." },
{ attribute: "data-state", values: '"expanded" | "collapsed"', description: "Whether the sidebar is open." },
{ attribute: "data-hotspot", description: "Present while the collapsed sidebar is floating out." },
{ attribute: "data-resizing", description: "Present for the duration of a resize drag." },
{ attribute: "--shell-sidebar-width", values: "measured px", description: "Written by the grip, on the root rather than the sidebar so anything in the shell can size itself to match." },
];
### Shell.Sidebar
The panel, and the element whose width is measured and reported back. Carries
the `id` the trigger's `aria-controls` points at. Renders a `
` element.
export const sidebarProps = [
{ name: "side", type: '"left" | "right"', default: '"left"', description: "Which edge it sits against. Surfaces as data-side; the resize drag inverts accordingly." },
{ name: "onResize", type: "(width: number) => void", description: "A settled width in pixels — once when a drag ends, never per frame, and whenever anything else resizes the panel. This is the measurement coming back out; there is no width prop going in, because that is CSS's." },
];
export const sidebarAttrs = [
{ attribute: "data-shell-sidebar", description: "The panel." },
{ attribute: "data-side", values: '"left" | "right"', description: "The edge it sits against." },
{ attribute: "data-state", values: '"expanded" | "collapsed"', description: "Whether it is open." },
{ attribute: "data-hotspot", description: "Present while floating out on hover." },
{ attribute: "data-resizing", description: "Present mid-drag — use it to suppress width transitions." },
];
### Shell.Viewport
The content area beside the sidebar. Carries the same state attributes as the
root, so it can react to the sidebar without a group selector. Renders a
`
` element.
export const viewportAttrs = [
{ attribute: "data-shell-viewport", description: "The content area." },
{ attribute: "data-state", values: '"expanded" | "collapsed"', description: "Whether the sidebar is open." },
{ attribute: "data-hotspot", description: "Present while the sidebar is floating out." },
{ attribute: "data-resizing", description: "Present mid-drag." },
];
### Shell.Trigger
Toggles the sidebar, and pins a floated-out one open rather than closing it. Ships
no copy — supply the label as children. Renders a `