App Shell with Inset Sidebar
Application frame with a sidebar, a top bar holding the sidebar trigger and breadcrumb, and a rounded inset main region with the page title. The default starting point for a SaaS product.
How it differs. Two regions: the page sits as an inset frame on the sidebar surface and scrolls under a fixed top bar. The sidebar slides off canvas on wide screens and becomes a modal sheet on narrow ones.
Install
pnpm dlx shadcn@latest add @hazine/app-shell-sidebar-insetAdds 2 files, 6 shadcn primitives (breadcrumb, button, kbd, separator, sidebar, tooltip), 2 Hazine items (@hazine/heading, @hazine/use-controllable-state), and 1 package (lucide-react).
First time? Add the registry to components.json
{
"registries": {
"@hazine": "https://api.hazine.dev/r/{name}.json"
}
}Needed once per project. Items resolve each other through the @hazine namespace.
The demo in the preview, 274 lines
"use client"
import * as React from "react"
import { Check, CircleAlert, Clock, Plus } from "lucide-react"
import {
AppShellSidebarInset,
type ShellNavGroup,
} from "@/components/blocks/app-shell-sidebar-inset"
import { Button } from "@/components/ui/button"
type InvoiceStatus = "awaiting" | "overdue" | "paid"
interface Invoice {
id: string
client: string
due: string
amount: number
status: InvoiceStatus
}
const INVOICES: Invoice[] = [
{ id: "INV-2041", client: "Okafor Dental Group", due: "2026-11-28", amount: 4800, status: "awaiting" },
{ id: "INV-2038", client: "Lindqvist Architects", due: "2026-11-06", amount: 2350, status: "overdue" },
{ id: "INV-2036", client: "Tamsin Reyes Photography", due: "2026-11-20", amount: 640, status: "awaiting" },
{ id: "INV-2035", client: "Brightwater Cycles", due: "2026-11-14", amount: 1920.5, status: "awaiting" },
{ id: "INV-2031", client: "Mercer & Vale Legal", due: "2026-10-30", amount: 3275, status: "overdue" },
{ id: "INV-2029", client: "Pelham Street Bakery", due: "2026-11-03", amount: 1180, status: "paid" },
]
const STATUS = {
awaiting: { label: "Awaiting payment", icon: Clock },
overdue: { label: "Overdue", icon: CircleAlert },
paid: { label: "Paid", icon: Check },
}
const money = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" })
const day = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC" })
const sum = (invoices: Invoice[]) => invoices.reduce((total, invoice) => total + invoice.amount, 0)
const plural = (count: number) => (count === 1 ? "1 invoice" : `${count} invoices`)
// Hash links keep the preview on this page. A real app passes its routes.
function navigation(openInvoices: number): ShellNavGroup[] {
return [
{
label: "Work",
items: [
{ id: "overview", label: "Overview", href: "#overview", icon: "gauge" },
{
id: "invoices",
label: "Invoices",
href: "#invoices",
icon: "receipt",
count: openInvoices > 0 ? openInvoices : undefined,
countLabel: "unpaid",
},
{ id: "clients", label: "Clients", href: "#clients", icon: "users" },
{ id: "projects", label: "Projects", href: "#projects", icon: "folder" },
],
},
{
label: "Money",
items: [
{ id: "payouts", label: "Payouts", href: "#payouts", icon: "landmark" },
{ id: "expenses", label: "Expenses", href: "#expenses", icon: "card", count: 12, countLabel: "to categorise" },
{ id: "reports", label: "Reports", href: "#reports", icon: "chart" },
],
},
{
label: "Workspace",
items: [
{ id: "team", label: "Team", href: "#team", icon: "team" },
{ id: "settings", label: "Settings", href: "#settings", icon: "settings" },
],
},
]
}
const WORKSPACE = { name: "Harbour Row Studio", plan: "Team plan", href: "#overview" }
const USER = { name: "Ines Carvalho", email: "ines@harbourrow.studio", href: "#settings" }
const USAGE = { used: 38, limit: 50, label: "invoices sent in November", href: "#settings" }
function InvoicesPage({
invoices,
onInvoicePay,
}: {
invoices: Invoice[]
onInvoicePay: (invoice: Invoice) => void
}) {
const open = invoices.filter((invoice) => invoice.status !== "paid")
const overdue = invoices.filter((invoice) => invoice.status === "overdue")
const paid = invoices.filter((invoice) => invoice.status === "paid")
const stats = [
{ label: "Outstanding", rows: open },
{ label: "Of which overdue", rows: overdue },
{ label: "Paid", rows: paid },
]
return (
<>
<p role="status" className="text-sm text-muted-foreground">
<span className="font-medium text-foreground tabular-nums">
{money.format(sum(invoices))} billed across {plural(invoices.length)}.
</span>{" "}
<span className="tabular-nums">
{money.format(sum(open))} outstanding + {money.format(sum(paid))} paid.
</span>
</p>
<dl className="grid gap-px overflow-hidden rounded-xl border border-border bg-border bg-clip-padding @2xl:grid-cols-3">
{stats.map((stat) => (
<div key={stat.label} className="bg-background p-4">
<dt className="text-sm text-muted-foreground">{stat.label}</dt>
<dd className="mt-1 text-2xl font-semibold tracking-tight tabular-nums">
{money.format(sum(stat.rows))}
</dd>
<dd className="mt-0.5 text-xs text-muted-foreground tabular-nums">{plural(stat.rows.length)}</dd>
</div>
))}
</dl>
<ul aria-label="Invoices" className="divide-y divide-border border-y border-border text-sm">
{invoices.map((invoice) => {
const status = STATUS[invoice.status]
const Icon = status.icon
const paid = invoice.status === "paid"
return (
<li key={invoice.id} className="flex flex-wrap items-center gap-x-4 gap-y-2 py-3">
<div className="min-w-0 flex-1 basis-48">
<p className="truncate font-semibold" title={invoice.client}>{invoice.client}</p>
<p className="mt-0.5 text-muted-foreground">
{invoice.id}, due <time dateTime={invoice.due}>{day.format(new Date(invoice.due))}</time>
</p>
</div>
<p className={invoice.status === "overdue" ? "flex items-center gap-1.5 font-medium @2xl:w-40" : "flex items-center gap-1.5 text-muted-foreground @2xl:w-40"}>
<Icon aria-hidden="true" className="size-3.5" />
{status.label}
</p>
<p className="ms-auto w-24 text-end font-medium tabular-nums">{money.format(invoice.amount)}</p>
<Button
variant="outline"
size="sm"
// Stays focusable once paid, so the keyboard does not lose its place in the list.
aria-disabled={paid || undefined}
className="aria-disabled:pointer-events-none aria-disabled:opacity-50"
aria-label={`Mark paid, ${invoice.id} for ${invoice.client}`}
onClick={() => {
if (!paid) onInvoicePay(invoice)
}}
>
Mark paid
</Button>
</li>
)
})}
</ul>
</>
)
}
export default function AppShellSidebarInsetDemo() {
const [current, setCurrent] = React.useState("invoices")
const [invoices, setInvoices] = React.useState(INVOICES)
const open = invoices.filter((invoice) => invoice.status !== "paid").length
return (
<AppShellSidebarInset
workspace={WORKSPACE}
navigation={navigation(open)}
current={current}
onCurrentChange={setCurrent}
user={USER}
usage={USAGE}
actions={
current === "invoices" ? (
<Button size="sm">
<Plus aria-hidden="true" />
New invoice
</Button>
) : undefined
}
>
{current === "invoices" ? (
<InvoicesPage
invoices={invoices}
onInvoicePay={(paid) =>
setInvoices((rows) =>
rows.map((row) => (row.id === paid.id ? { ...row, status: "paid" } : row))
)
}
/>
) : undefined}
</AppShellSidebarInset>
)
}
const LONG_CLIENTS = [
"Okafor Dental Group and Orthodontic Partners of Greater Manchester",
"Lindqvist Architects",
"Tamsin Reyes Photography",
"Brightwater Cycles",
"Mercer & Vale Legal",
"Pelham Street Bakery",
"Castellan Freight Forwarding",
"Ashdown Veterinary Hospital",
"Nkemelu Structural Engineering",
]
const OVERFLOW_NAVIGATION: ShellNavGroup[] = ["Retainers", "Fixed fee projects", "Archived clients"].map(
(label, group) => ({
label,
items: LONG_CLIENTS.map((client, index) => ({
id: `${group}-${index}`,
label: client,
href: `#client-${group}-${index}`,
icon: group === 0 ? "users" : group === 1 ? "folder" : "receipt",
count: index % 3 === 0 ? (index + 1) * 1040 * (group + 1) : undefined,
countLabel: "time entries to bill",
})),
})
)
export const scenarios = {
empty: () => (
<AppShellSidebarInset
workspace={WORKSPACE}
navigation={navigation(0)}
defaultCurrent="projects"
user={USER}
usage={{ ...USAGE, used: 0 }}
/>
),
loading: () => <AppShellSidebarInset workspace={WORKSPACE} user={USER} loading />,
collapsed: () => (
<AppShellSidebarInset
workspace={WORKSPACE}
navigation={navigation(5)}
defaultCurrent="invoices"
defaultOpen={false}
user={USER}
usage={USAGE}
/>
),
overflow: () => (
<AppShellSidebarInset
workspace={{
name: "Harbour Row Studio for Brand Identity, Packaging and Exhibition Design",
plan: "Team plan, billed yearly, 14 seats",
href: "#overview",
}}
navigation={OVERFLOW_NAVIGATION}
defaultCurrent="0-0"
breadcrumb={[
{ label: "Harbour Row Studio for Brand Identity, Packaging and Exhibition Design", href: "#overview" },
{ label: "Retainers", href: "#retainers" },
{ label: "Okafor Dental Group and Orthodontic Partners of Greater Manchester", href: "#client-0-0" },
{ label: "Quarterly retainer statement for July to September 2026" },
]}
title="Quarterly retainer statement for July to September 2026, Okafor Dental Group and Orthodontic Partners"
user={{
name: "Maximiliana Oyelaran-Featherstonehaugh",
email: "maximiliana.oyelaran-featherstonehaugh@harbourrow.studio",
href: "#settings",
}}
usage={{ used: 1248, limit: 1200, label: "invoices sent in November", href: "#settings" }}
actions={
<>
<Button variant="outline" size="sm">
Download statement
</Button>
<Button size="sm">Send to client</Button>
</>
}
/>
),
}
Props16
- workspace
- ShellWorkspace = DEFAULT_WORKSPACE
- Name, plan and home link shown at the top of the sidebar.
- navigation
- ShellNavGroup[] = DEFAULT_NAVIGATION
- Navigation groups. Each group renders a label and a list of links.
- current
- string
- Id of the navigation item for the page on screen, when controlled by your router.
- defaultCurrent
- string
- Initial current item when uncontrolled. Defaults to the first item.
- onCurrentChange
- (id: string) => void
- Called with the item id when a navigation link is followed.
- open
- boolean
- Whether the desktop sidebar is shown, when controlled.
- defaultOpen
- boolean = true
- onOpenChange
- (open: boolean) => void
- Called when the trigger or Ctrl or Command plus B shows or hides the desktop sidebar.
- breadcrumb
- ShellCrumb[]
- Trail in the top bar. Defaults to the workspace followed by the current item.
- title
- string
- Page heading at the top of the main region. Defaults to the current item label.
- actions
- React.ReactNode
- Page level actions at the end of the title row.
- user
- ShellUser | null = DEFAULT_USER
- Account row at the foot of the sidebar. Pass null to leave it out.
- usage
- ShellUsage | null = DEFAULT_USAGE
- Plan usage meter above the account row. Pass null to leave it out.
- loading
- boolean = false
- Shows skeletons in the navigation, top bar and main region while the workspace loads.
- headingLevel
- HeadingLevel = 1
- Rank of the page heading. The shell owns the page, so it defaults to 1.
- locale
- string = "en-US"
Also accepts every prop of Omit<React.ComponentProps<"div">, "title">.
Accessibility
- Pattern
- Landmarks and headings, Breadcrumb (APG, opens in a new tab), Dialog (Modal) (APG, opens in a new tab), Meter (APG, opens in a new tab), Tooltip (APG, opens in a new tab)
- Keyboard
Keyboard support for App Shell with Inset Sidebar Key Effect Tab Moves through the skip link, workspace link, navigation, plan link, account link, sidebar trigger, breadcrumb and then the page. On a narrow screen the sidebar links are reached inside the sheet Enter on Skip to content Moves focus to the main region Ctrl+B or Command+B Shows or hides the sidebar, or opens and closes the sheet on a narrow screen. Opening the sheet moves focus to its Close sidebar button Enter or Space on the trigger Shows or hides the sidebar. A hidden sidebar leaves the tab order, and focus that was inside it moves to the trigger Enter on a navigation link Follows the link, marks it as the current page and closes the sheet on a narrow screen. A click with a modifier key only opens the link Enter or Space on Close sidebar Closes the sheet on a narrow screen and returns focus to the trigger Esc Closes the sheet and returns focus to the trigger, or dismisses the trigger tooltip - Screen reader
Banner, navigation labelled Main and a main region labelled by the page heading, with a skip link first. As the page frame it renders main itself. The trigger reports aria-expanded, and the narrow sidebar is a modal dialog.
- Announces: Sidebar shown.
- Announces: Sidebar hidden.
- Announces: Loading workspace.
- Reduced motion
- The desktop sidebar shows and hides with no slide. The narrow sheet keeps the host sheet primitive's own short fade and slide.
- Checked
- Not checked yet. Automated results appear here once CI has run.
Dependencies9
- breadcrumb
- button
- kbd
- separator
- sidebar
- tooltip
- @hazine/heading
- @hazine/use-controllable-state
- lucide-react
Filled chips are registry items the CLI adds for you. Outlined chips are npm packages.
Tokens shipped0
None. The item is styled by the tokens your theme already has.