# App shell

> The frame of an application: a sidebar of navigation that folds into a rail, and a top bar for the page title, search and account.

- Category: Navigation
- Import: `import { AppShell } from "@sagui/ui";`
- Page: /components/app-shell

```tsx
import { useEffect, useState, CSSProperties, MouseEvent } from "react";
import { Search, Settings } from "lucide-react";
import { AppShell, Breadcrumb, Button, CommandPalette, Dialog, DialogContent, MetricCard, NotificationCenter, UserMenu } from "@sagui/ui";

export function Hero() {
  const [current, setCurrent] = useState("/app");
  const [searching, setSearching] = useState(false);

  // In a real app the links navigate; in this preview a click only moves the current page.
  function stayHere(event: MouseEvent) {
    const link = (event.target as HTMLElement).closest<HTMLAnchorElement>('a[href^="/app"]');
    if (!link) return;
    event.preventDefault();
    setCurrent(link.getAttribute("href")!);
  }

  // Cmd/Ctrl + K opens search from anywhere in the app.
  useEffect(() => {
    function onKey(event: KeyboardEvent) {
      if (event.key.toLowerCase() === "k" && (event.metaKey || event.ctrlKey)) {
        event.preventDefault();
        setSearching(true);
      }
    }
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, []);

  return (
    <div onClickCapture={stayHere} className="h-[560px] w-full overflow-y-auto rounded-[var(--radius-lg)] border border-border-default" style={{ "--app-shell-height": "558px" } as CSSProperties}>
      <AppShell
        nav={nav}
        currentHref={current}
        brand={<span className="flex items-center gap-2 font-semibold"><span className="grid size-7 place-items-center rounded-control bg-accent-default text-xs text-fg-on-accent">S</span>Sales</span>}
        brandMark={<span className="grid size-7 place-items-center rounded-control bg-accent-default text-xs font-semibold text-fg-on-accent">S</span>}
        header={<Breadcrumb items={[{ label: "Acme Inc.", href: "/app" }, { label: titles[current] }]} />}
        actions={
          <>
            <Button variant="ghost" size="sm" leadingIcon={<Search />} onClick={() => setSearching(true)}>
              <span className="hidden sm:inline">Search</span>
            </Button>
            <NotificationCenter notifications={notifications} />
            <UserMenu user={{ name: "Sagnik Dey", email: "sagnik@example.com", plan: "Pro", avatarSrc: face("photo-1507003211169-0a1dd7228f2d") }} items={[{ label: "Profile" }, { label: "Settings", icon: <Settings />, keys: ["⌘", ","] }]} onSignOut={() => {}} />
          </>
        }
      >
        <div className="grid gap-6 p-6">
          <h1 className="type-h2">{titles[current]}</h1>
          <div className="grid gap-4 sm:grid-cols-3">
            <MetricCard label="Revenue" value={128.4} prefix="$" suffix="k" decimals={1} change="+12.4%" context="vs last month" />
            <MetricCard label="Deals won" value={42} change="+6" context="vs last month" />
            <MetricCard label="Win rate" value={31.5} suffix="%" decimals={1} change="+2.1 pts" context="vs last month" />
          </div>
          <p className="type-body-sm text-fg-muted">Press ⌘B to fold the sidebar into a rail, and ⌘K to search. Narrow the window to see the drawer.</p>
        </div>
      </AppShell>

      <Dialog open={searching} onOpenChange={setSearching}>
        <DialogContent title="Search" className="p-0">
          <CommandPalette
            items={commands}
            autoFocus
            placeholder="Search pages and actions"
            onSelect={(item) => {
              if (item.id.startsWith("/app")) setCurrent(item.id);
              setSearching(false);
            }}
            onClose={() => setSearching(false)}
          />
        </DialogContent>
      </Dialog>
    </div>
  );
}
```

## When to use

- The outer layout of a product: a dashboard, an admin tool, a workspace with several sections.
- Apps with five to fifteen destinations that people move between all day.
- Screens that need the most width on demand, where the sidebar can fold into an icon rail.

## When not to use

- Marketing sites and docs. They need a site header, not a sidebar.
- Two or three destinations. Use [tabs](/components/tabs) in the page instead.
- Moving between views of one dataset. That is [tabs](/components/tabs) or a [segmented control](/components/segmented-control), not navigation.

## Installation

Install the package and import the styles once. The [installation guide](/docs/installation) covers the Tailwind setup.

```bash
npm install @sagui/ui
```

## Usage

Render it once in the layout that wraps your app's pages, and pass it the current path so the right item is marked.

```tsx title="app/(app)/layout.tsx"
"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";
import { Handshake, LayoutDashboard, Settings } from "lucide-react";
import { AppShell } from "@sagui/ui";

const nav = [
  { items: [
    { label: "Overview", href: "/", icon: <LayoutDashboard /> },
    { label: "Deals", href: "/deals", icon: <Handshake />, badge: 12 },
  ] },
  { label: "Workspace", items: [{ label: "Settings", href: "/settings", icon: <Settings /> }] },
];

export default function AppLayout({ children }: { children: React.ReactNode }) {
  return (
    <AppShell nav={nav} currentHref={usePathname()} linkComponent={Link} brand={<span className="font-semibold">Sales</span>}>
      {children}
    </AppShell>
  );
}
```

The shell gives you the frame; you fill its slots. Put the page title or a [breadcrumb](/components/breadcrumb) in `header`. Put search, [notifications](/components/notification-center) and the [user menu](/components/user-menu) in `actions`. Open a [command palette](/components/command-palette) in a dialog for search.

## Examples

### Starting as a rail

`defaultCollapsed` starts with the icon rail. Each icon names itself in a tooltip on hover or focus.

```tsx
import { CSSProperties } from "react";
import { AppShell } from "@sagui/ui";

export function StartFolded() {
  return (
    <div className="h-[360px] w-full overflow-hidden rounded-[var(--radius-lg)] border border-border-default" style={{ "--app-shell-height": "358px" } as CSSProperties}>
      <AppShell nav={nav} currentHref="/app/deals" defaultCollapsed brand={<span className="font-semibold">Sales</span>} brandMark={<span className="font-semibold">S</span>} header={<span className="type-title">Deals</span>}>
        <p className="p-6 text-sm text-fg-muted">Point at an icon to see its label.</p>
      </AppShell>
    </div>
  );
}
```

### Inset sidebar

`variant="inset"` floats the sidebar as a rounded panel 12px in from the edges, on a muted canvas, and drops the border under the top bar. The current page is an accent pill, the fold toggle sits in the sidebar header beside `brand` (stacked under `brandMark` on the rail), and a group that holds the current page tints in the accent color. Use it for dashboards and tools where the content sits in panels of its own.

```tsx
import { CSSProperties } from "react";
import { AppShell } from "@sagui/ui";

export function Inset() {
  return (
    <div className="h-[360px] w-full overflow-hidden rounded-[var(--radius-lg)] border border-border-default" style={{ "--app-shell-height": "358px" } as CSSProperties}>
      <AppShell
        nav={nav}
        variant="inset"
        currentHref="/app/deals"
        brand={<span className="font-semibold">Sales</span>}
        brandMark={<span className="font-semibold">S</span>}
        header={<span className="type-title">Deals</span>}
        sidebarFooter={<span className="type-body-sm text-fg-muted">Acme workspace</span>}
      >
        <p className="p-6 text-sm text-fg-muted">The toggle beside the title folds the floating sidebar into a rail.</p>
      </AppShell>
    </div>
  );
}
```

### Dotted grid background

`background="dots"` fills the content area with a faint dotted grid, like a FigJam canvas. A dot sits on every `gridSize` pixels (8 by default, or 4 for a finer texture) counted from the top-left of the content, so cards and panels laid out with SagUI spacing land on the dots. The sidebar and top bar stay solid, and cards keep their own surface color on top. Use it for canvas-like work such as builders, boards and dashboards; leave forms and reading pages plain.

```tsx
import { CSSProperties } from "react";
import { AppShell } from "@sagui/ui";

export function DotGrid() {
  return (
    <div className="h-[360px] w-full overflow-hidden rounded-[var(--radius-lg)] border border-border-default" style={{ "--app-shell-height": "358px" } as CSSProperties}>
      <AppShell nav={nav} background="dots" currentHref="/app/deals" brand={<span className="font-semibold">Sales</span>} brandMark={<span className="font-semibold">S</span>} header={<span className="type-title">Deals</span>}>
        <div className="grid gap-4 p-6 sm:grid-cols-2">
          <div className="h-32 rounded-container border border-border-default bg-bg-surface p-4 type-body-sm text-fg-muted shadow-raised">Cards sit on the 8px grid.</div>
          <div className="h-32 rounded-container border border-border-default bg-bg-surface p-4 type-body-sm text-fg-muted shadow-raised">Padding and gaps land on dots.</div>
        </div>
      </AppShell>
    </div>
  );
}
```

### Remembering the choice

The shell does not store whether the sidebar is folded. Control it with `collapsed` and `onCollapsedChange`, and save the choice where it suits your app, for example a cookie, so the server renders the right width on the next visit.

```tsx
const [collapsed, setCollapsed] = useState(initialFromCookie);

<AppShell nav={nav} collapsed={collapsed} onCollapsedChange={(next) => { setCollapsed(next); document.cookie = `sidebar=${next ? "rail" : "open"}; path=/; max-age=31536000`; }}>
```

## API reference

### AppShell

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nav` (required) | `{ label?: string; items: AppShellNavItem[] }[]` | – | Navigation in sections. A section label is a small heading. Each item is `{ label, href?, icon?, badge?, badgeTone?, current?, items?, defaultOpen? }`. |
| `children` (required) | `ReactNode` | – | The page. It renders in the main column under the top bar. |
| `currentHref` | `string` | – | The current path. The item whose href matches it, or is its closest parent, is marked current, so `/deals/42` marks Deals. |
| `linkComponent` | `ElementType` | `"a"` | Element for nav links. Pass your router's Link, such as next/link. It must forward its ref. |
| `brand` | `ReactNode` | – | Logo and product name at the top of the sidebar and the drawer. |
| `brandMark` | `ReactNode` | – | A compact mark shown instead of `brand` while the sidebar is a rail. |
| `header` | `ReactNode` | – | Start of the top bar: the page title or a Breadcrumb. |
| `actions` | `ReactNode` | – | End of the top bar: search, notifications and the user menu. |
| `sidebarFooter` | `ReactNode` | – | Pinned to the bottom of the sidebar, above the fold toggle in the `sidebar` variant, such as a promo card and the signed-in user. |
| `sidebarFooterRail` | `ReactNode` | – | Compact footer shown while the sidebar is a rail, such as the user's avatar alone. Without it the footer hides on the rail. |
| `variant` | `"sidebar" \| "inset"` | `"sidebar"` | `sidebar` sits flush with a dividing border. `inset` floats the sidebar as a rounded panel 12px in from the edges on a muted canvas, marks the current page with an accent pill and keeps the fold toggle in the sidebar header. |
| `background` | `"plain" \| "dots"` | `"plain"` | `dots` puts a faint dotted grid behind the page content, aligned to the spacing grid. The sidebar and top bar stay solid. |
| `gridSize` | `4 \| 8` | `8` | Gap between dots in pixels when `background="dots"`. |
| `collapsed` | `boolean` | – | Controlled rail state on wide screens. |
| `defaultCollapsed` | `boolean` | `false` | Rail state on first render when uncontrolled. |
| `onCollapsedChange` | `(collapsed: boolean) => void` | – | Called when the toggle or Cmd/Ctrl + B folds or opens the sidebar. |
| `label` | `string` | `"Main"` | Accessible name of the navigation landmark. |
| `className` | `string` | – | Class on the outer grid. |

### Nav items

| Field | Type | Description |
| --- | --- | --- |
| `label` | `string` | Visible name; the tooltip on the rail. |
| `href` | `string` | Destination. Optional on a group, which links to its first page while the sidebar is a rail. |
| `icon` | `ReactNode` | 18px icon. |
| `badge` | `ReactNode` | A number or short string renders as a small Badge and shrinks to a dot on the rail. Any other node renders as given. |
| `badgeTone` | `"neutral" \| "success" \| "info" \| "warning" \| "danger"` | Tone of a number or string badge. Use danger for work that needs attention. |
| `current` | `boolean` | Marks the item current, overriding `currentHref`. |
| `items` | `AppShellNavItem[]` | Pages inside a collapsible group, drawn with a dot and a guide line. One level only. |
| `defaultOpen` | `boolean` | Whether a group starts open. Defaults to open when it holds the current page. |

The shell fills the viewport. To place it inside a fixed-height panel, set `--app-shell-height` on an ancestor, for example `style={{ "--app-shell-height": "560px" }}`.

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | The first stop is a "Skip to content" link, then the navigation, the top bar and the page. |
| Cmd + B / Ctrl + B | Folds the sidebar into a rail, or opens it again. Ignored while typing in a field. |
| Enter | Follows the focused link. |
| Escape | Closes the navigation drawer on narrow screens. |

## Accessibility

- The sidebar is a `nav` landmark named by `label`, and the page is a `main` landmark that the skip link jumps to.
- The current item has `aria-current="page"`, so screen readers announce it as the current page.
- In the rail, labels stay in the accessible name of each link, and a tooltip shows them on hover and keyboard focus.
- The fold toggle reports its state with `aria-expanded` and names its action: "Collapse sidebar" or "Expand sidebar".
- The drawer on narrow screens is a modal dialog with a title, so focus stays inside it until it closes.

## Motion

- The sidebar's width springs between full and rail, and the main column reflows on the same spring, so content does not jump.
- The current page's highlight glides from item to item.
- Labels and section headings fade as the rail closes.
- With reduced motion the width and highlight change in one step.

## Responsive behavior

- From 1024px the sidebar is a sticky column beside the page, 272px open or 76px as a rail.
- Below 1024px the sidebar hides and a menu button in the top bar opens the same navigation in a drawer from the start edge. Choosing a page closes the drawer.
- The main column has `min-width: 0`, so wide tables scroll inside it instead of widening the page.

## Performance

- The shell renders the navigation twice, once for the sidebar and once for the drawer, which only mounts while open.
- Folding animates one width; nothing re-renders on scroll.

## Notes

- Render it once in the app's layout so it persists across pages, and pass `currentHref` from the router.
- Keep icons on every item, or on none. A rail with missing icons cannot be read.
- SagUI's App shell is an original component. Arc's own app shell blocks are part of Arc Pro and are not included.

## Related

- [Breadcrumb](/components/breadcrumb): Show where a page sits in a hierarchy.
- [Command palette](/components/command-palette): A keyboard driven search for pages and actions.
- [User menu](/components/user-menu): Account, theme and sign out behind the avatar.
- [Notification center](/components/notification-center): A home for updates with read state.
- [Drawer](/components/drawer): A temporary side surface for focused work.
