# App shell

> The frame of a product: translucent sidebar, sticky toolbar, page header; the sidebar becomes a sheet on phones.

Category: Layout · Atomic level: template
Page: https://ui.dtheo.dev/docs/components/app-shell

## Install

```bash
npx dtheo@latest add app-shell
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/app-shell.json
```

Dependencies: @base-ui/react, clsx, tailwind-merge, lucide-react. Registry dependencies: utils, sheet, button, scroll-area.

## Exports

`AppShell`, `AppToolbar`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarSection`, `SidebarItem`, `PageHeader`

## Use it for

- Every tool in a suite, so they feel like one family

## Reach for something else

- Marketing pages and docs
- Single-purpose dialogs or embedded widgets

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sidebar` | `ReactNode` | – | AppShell: sidebar content. Below 768px it moves into a sheet. |
| `embedded` | `boolean` | `false` | AppShell: fill a fixed-height parent instead of the viewport. |
| `level` | `1 \| 2` | `1` | PageHeader: heading level of the title; use 2 when the page already has an h1. |

## Accessibility

- The current page carries `aria-current="page"`. Sections are labelled navigation landmarks.

## Examples

### app-shell

```tsx
import * as React from 'react';
import {
  CircleXIcon,
  DownloadIcon,
  FlaskConicalIcon,
  HistoryIcon,
  PlayIcon,
  ServerIcon,
  TriangleAlertIcon,
} from 'lucide-react';
import {
  AppShell,
  AppToolbar,
  PageHeader,
  SidebarContent,
  SidebarFooter,
  SidebarHeader,
  SidebarItem,
  SidebarSection,
} from '@/components/ui/app-shell';
import { Avatar } from '@/components/ui/avatar';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';

const views = [
  { id: 'all', label: 'All runs', icon: <HistoryIcon aria-hidden="true" />, count: 412 },
  { id: 'review', label: 'Needs review', icon: <TriangleAlertIcon aria-hidden="true" />, count: 3 },
  { id: 'failed', label: 'Failed', icon: <CircleXIcon aria-hidden="true" />, count: 7 },
];

const benches = [
  { id: 'bench-1', label: 'Bench 1', count: 128 },
  { id: 'bench-2', label: 'Bench 2', count: 141 },
  { id: 'bench-3', label: 'Bench 3', count: 143 },
];

export default function AppShellExample() {
  const [current, setCurrent] = React.useState('review');
  const currentLabel = [...views, ...benches].find((v) => v.id === current)?.label;
  const item = (id: string) => ({
    href: `#${id}`,
    active: current === id,
    onClick: (e: React.MouseEvent) => {
      e.preventDefault();
      setCurrent(id);
    },
  });

  const sidebar = (
    <>
      <SidebarHeader>
        <span className="flex items-center gap-2 px-1 text-headline">
          <FlaskConicalIcon className="size-4 text-primary" aria-hidden="true" />
          Bench Review
        </span>
      </SidebarHeader>
      <SidebarContent>
        <SidebarSection title="Runs">
          {views.map((v) => (
            <SidebarItem key={v.id} icon={v.icon} count={v.count} {...item(v.id)}>
              {v.label}
            </SidebarItem>
          ))}
        </SidebarSection>
        <SidebarSection title="Benches">
          {benches.map((b) => (
            <SidebarItem key={b.id} icon={<ServerIcon aria-hidden="true" />} count={b.count} {...item(b.id)}>
              {b.label}
            </SidebarItem>
          ))}
        </SidebarSection>
      </SidebarContent>
      <SidebarFooter>
        <Avatar name="Maya Okafor" />
        <span className="flex min-w-0 flex-col">
          <span className="truncate text-label">Maya Okafor</span>
          <span className="truncate text-caption text-subtle-foreground">Controls</span>
        </span>
      </SidebarFooter>
    </>
  );

  return (
    // AppShell fills the viewport by default; `embedded` makes it fill this fixed-height frame instead.
    <div className="h-105 w-full overflow-hidden rounded-card border border-border">
      <AppShell sidebar={sidebar} embedded>
        <AppToolbar>
          <span className="min-w-0 flex-1 truncate text-label text-muted-foreground">
            <span className="hidden sm:inline">{currentLabel} / </span>R-0412
          </span>
          <Button variant="ghost" size="icon" aria-label="Export run as CSV">
            <DownloadIcon aria-hidden="true" />
          </Button>
          <Button variant="primary" size="sm">
            <PlayIcon aria-hidden="true" />
            Rerun
          </Button>
        </AppToolbar>
        <div className="flex flex-col gap-4 px-4 py-5 sm:px-6">
          <PageHeader
            level={2}
            eyebrow="Bench 3 · firmware 4.18.2"
            title="R-0412 High-gain step"
            description="Overshoot reached 17.6 %, past the 10 % limit. Settling took 186 ms."
          >
            <div className="flex flex-wrap gap-1.5 pt-1">
              <Badge variant="destructive">
                <CircleXIcon aria-hidden="true" />
                Failed
              </Badge>
              <Badge variant="outline">Kp 4.20</Badge>
            </div>
          </PageHeader>
          <dl className="grid grid-cols-2 gap-px overflow-hidden rounded-card border border-border bg-border sm:grid-cols-3">
            {[
              ['Peak torque', '9.41 N·m'],
              ['Phase current', '31.2 A'],
              ['Winding temperature', '71.2 °C'],
            ].map(([label, value]) => (
              <div
                key={label}
                className="flex flex-col gap-0.5 bg-card px-3 py-2.5 last:col-span-2 sm:last:col-span-1"
              >
                <dt className="truncate text-label font-normal text-muted-foreground">{label}</dt>
                <dd className="text-callout font-semibold tabular-nums">{value}</dd>
              </div>
            ))}
          </dl>
        </div>
      </AppShell>
    </div>
  );
}
```

## Used in

- Run review (page): https://ui.dtheo.dev/examples/run-review
- Motor map (page): https://ui.dtheo.dev/examples/motor-map
- Loop tuning (page): https://ui.dtheo.dev/examples/tuning
- Lab assistant (page): https://ui.dtheo.dev/examples/assistant
