App Shell

Two navigation axes, not one menu

A Comitor user belongs to many workspaces, and each workspace has many products enabled. The two are perpendicular — switching workspace does not switch product, and switching product does not switch workspace — so they cannot collapse into a single flat menu.

A third thing, often confused with these: the five display axes — light/dark, contrast, layout density, font size and theme palette. They are independent of each other and of both navigation axes, they live at the root layout rather than in the shell, and they are documented at Display Axes.

And one more, new in 3.16.0: modules — the business areas inside ONE app (Production, HR, Commerce), passed as modules and laid out by moduleLayout. A module is an internal link of the open app; an app is another domain. All four module layouts, and every other arrangement of the frame, run side by side at App Shell layouts.

Live demo

A whole frame, running, inside a 560px box. Both layouts, the sidebar on and off, two workspaces, three products — one of them locked — and a real user. The keyboard shortcuts are switched off here so the page does not take over your ⌘K, and the sidebar’s collapse state is not written to your localStorage; both are on by default in an app. (The theme toggle inside the frame is a different matter — it talks to this site’s own ThemeProvider and persists like any other theme change.)

What the frame mounts

• ShellProvider — every prop you pass that is not in the table of AppShell’s own props is forwarded here verbatim. It also wraps the tree in a TooltipProvider with a 200ms delay, which is what the collapsed icon rail needs.
• Sidebar — the desktop rail, hidden below md by CSS. Configure it through sidebarProps; it is documented in full at Sidebar.
• AppHeader — 56px, three regions, with the search pill in the middle one. Configure it through headerProps; see App Header.
• <main> — your children, in the frame’s page-level scroll container. The outer element is h-dvh overflow-hidden, so the page scrolls inside the shell rather than the document scrolling under it. It is not the only scroller in the frame: the sidebar’s <nav> and the mobile sheet each scroll on their own, which is what keeps a long menu from dragging your page with it.
• MobileMenu — the off-canvas sheet for narrow screens, mounted in both layouts and driven by mobileMenuOpen. Its content order deliberately differs from the desktop rail; see Navigation Model.
• --app-accent for the whole tree — the frame reads currentApp out of context and sets that app’s three accent variables as an inline style on the root element. This is the one job that forced the frame to be split into an inner component: useShell() can only be called inside the provider that AppShell itself renders.
• ComitorLocaleProvider, only if you pass locale — and outside ShellProvider, because the provider builds its merged labels from the language’s shell table and has to see it. Without the prop nothing is added, and the frame reads the provider in your root layout. See “The locale shortcut” below.

The two layouts

sidebar-first is the Linear/Lark shape: a full-height rail on the left with the workspace switcher at its top, and the header occupying only the remaining width. header-first is the Google/Atlassian shape: one header across the whole top, the sidebar below it. The difference is not only flex-row versus flex-col — four defaults move with it so that no control appears in both places at once.

All four are fallbacks, applied with ?? after your object has been spread — so anything you set yourself wins, and only the keys you left out are filled in. The order matters: spread last and {...headerProps} would overwrite a computed default with undefined. The practical consequence: passing your own headerProps.logo in header-first replaces the workspace switcher, and axis 1 vanishes from the frame unless you put it back.

import type { ReactNode } from 'react'
import { AppShell, ComitorLockup } from '@comitor/ui/shell'
import { NAV, WORKSPACES } from './shell-model'

// Default. The sidebar runs the full height on the left, the header sits to the
// right of it, and the WorkspaceSwitcher lives at the top of the sidebar.
export function SidebarFirst({ children }: { children: ReactNode }) {
  return (
    <AppShell layout="sidebar-first" nav={NAV} workspaces={WORKSPACES}>
      {children}
    </AppShell>
  )
}

// Header full width across the top, sidebar underneath it. AppShell moves the
// WorkspaceSwitcher into the header's logo slot and turns on the header's
// sidebar toggle; the sidebar drops its own switcher strip and collapse button,
// so neither control is ever drawn twice.
export function HeaderFirst({ children }: { children: ReactNode }) {
  return (
    <AppShell layout="header-first" nav={NAV} workspaces={WORKSPACES}>
      {children}
    </AppShell>
  )
}

// Every one of those four defaults is only a fallback: anything you set on
// headerProps / sidebarProps yourself wins. Supplying your own logo in
// header-first therefore REPLACES the workspace switcher — put it back
// somewhere, or the workspace axis disappears from the frame.
export function HeaderFirstWithLogo({ children }: { children: ReactNode }) {
  return (
    <AppShell
      layout="header-first"
      nav={NAV}
      workspaces={WORKSPACES}
      headerProps={{ logo: <ComitorLockup size="xs" variant="auto" /> }}
      sidebarProps={{ showWorkspaceSwitcher: true }}
    >
      {children}
    </AppShell>
  )
}

Single-area apps: showSidebar={false}

Some products have nothing to put in a rail — a reader, a single-screen console, an onboarding flow. showSidebar={false} removes the <aside> rather than rendering an empty one, and the rest of the frame is untouched: header, app launcher, user menu, and the off-canvas menu that narrow screens use regardless. Note that this is different from passing an empty nav, which still draws the rail — just with nothing in it.

import type { ReactNode } from 'react'
import { AppShell } from '@comitor/ui/shell'
import { APPS, USER, WORKSPACES } from './shell-model'

// A single-area product — an inbox, a report viewer, a settings-only console —
// has nothing to put in a rail. showSidebar={false} drops the <aside> entirely
// rather than rendering an empty one.
//
// The frame keeps everything else: header, app launcher, user menu, and the
// off-canvas MobileMenu, which is what narrow screens use anyway.
export function ReaderLayout({ children }: { children: ReactNode }) {
  return (
    <AppShell
      showSidebar={false}
      apps={APPS}
      workspaces={WORKSPACES}
      user={USER}
      headerProps={{ title: 'Reader', showSearch: false }}
    >
      {children}
    </AppShell>
  )
}

Where it goes in a Next app

Two layouts, two jobs. The root layout owns the display axes and the language — the axes must sit above everything so the page does not flash the wrong theme during hydration, and the language must reach the pages that never render the shell. A nested layout owns the shell, one per product, and must be a client component: every callback you pass it is a function.

// app/layout.tsx — the display axes and the language belong at the ROOT, outside AppShell.
// (PaletteProvider, the fifth axis, only where users may choose a theme palette — see Display Axes.)
import type { ReactNode } from 'react'
import { ComitorLocaleProvider } from '@comitor/ui'
import { ContrastProvider, DensityProvider, FontSizeProvider, ThemeProvider } from '@comitor/ui/shell'
import { getLocale } from 'next-intl/server'
import './globals.css' // @import "tailwindcss"; @import "@comitor/ui/styles.css";

export default async function RootLayout({ children }: { children: ReactNode }) {
  // The user's language from next-intl — 'vi', 'en'… Without the provider below,
  // every string in the package, the shell's included, is English.
  const locale = await getLocale()

  return (
    // Required: the four anti-flash scripts touch <html> before React hydrates,
    // so the client markup never matches the server markup here.
    <html lang={locale} suppressHydrationWarning>
      <body>
        {/* None of the five reads another, so the nesting order is free.
            ThemeProvider already defaults to attribute="class",
            defaultTheme="system" and the comitor-theme storage key — pass
            nothing unless you mean to override it. */}
        <ComitorLocaleProvider locale={locale}>
          <ThemeProvider>
            <ContrastProvider>
              <DensityProvider>
                <FontSizeProvider>{children}</FontSizeProvider>
              </DensityProvider>
            </ContrastProvider>
          </ThemeProvider>
        </ComitorLocaleProvider>
      </body>
    </html>
  )
}

// app/(app)/layout.tsx — one AppShell for every route of one product.
'use client'

import type { ReactNode } from 'react'
import { useRouter } from 'next/navigation'
import { AppShell } from '@comitor/ui/shell'
import { signOut } from '@/lib/auth'
import { APPS, NAV, WORKSPACES } from './shell-model'

export default function AppLayout({ children }: { children: ReactNode }) {
  const router = useRouter()

  return (
    <AppShell
      workspaces={WORKSPACES}
      currentWorkspaceId="acme"
      apps={APPS}
      currentAppId="tasks"
      nav={NAV}
      user={{ id: 'u1', name: 'Nguyễn Đức Thành', email: '[email protected]', role: 'Quản trị viên' }}
      // The shell never routes by itself — it has no useRouter() anywhere,
      // because that hook throws when there is no App Router (Storybook, tests).
      onWorkspaceChange={(id) => router.push(`/w/${id}`)}
      onAppSelect={(app) => router.push(app.href)}
      onUpsell={(appId) => router.push(`/billing?app=${appId}`)}
      onLogout={signOut}
      // No `locale` here: the root layout's provider already covers this frame, and
      // the sign-in and error pages that never render it.
    >
      {children}
    </AppShell>
  )
}

Notice that the shell never routes. It calls no useRouter() anywhere, because that hook throws without an App Router and would make the shell unusable in Storybook and in tests. Active navigation is yours, through onWorkspaceChange, onAppSelect and onNavigate; static links go through LinkComponent.

The locale shortcut

Since 3.0.0 AppShell takes a locale prop: <AppShell locale="vi"> wraps the frame in a ComitorLocaleProvider of its own. It exists for an app with no root layout of its own to put the provider in. Everyone else should leave it alone, for three reasons.

• It covers the frame and nothing else. The sign-in page, the error page and every public route never render the shell, so they stay English — the provider in the root layout reaches all of them.
• It starts from scratch. The provider it builds is a new one: it does not inherit messages (your wording overrides) or dateFnsLocale from a provider further up. Inside the frame, those quietly disappear.
• Adding or removing it remounts the shell. With the prop the tree has one more level than without it, so toggling between the two throws the whole frame away and builds it again — the page inside it too, with its scroll position and any state it held. Keep it always present or always absent.

Keeping the state, dropping the frame

When the arrangement is wrong for you — a header of your own, a two-column split, a chrome-less embed — keep ShellProvider and place the parts yourself. They will still find their data, because they never took it as props in the first place.

'use client'

import type { ReactNode } from 'react'
import { AppLauncher, ShellProvider, WorkspaceSwitcher } from '@comitor/ui/shell'
import { MyOwnBreadcrumb } from './breadcrumb'
import { APPS, NAV, USER, WORKSPACES } from './shell-model'

/**
 * AppShell is ShellProvider plus one particular arrangement of parts. When that
 * arrangement is wrong for you, keep the provider and lay out the rest yourself:
 * WorkspaceSwitcher, AppLauncher, Sidebar, AppHeader, MobileMenu and UserMenu all
 * read the shell model out of context and take none of it as props.
 */
export function CustomFrame({ children }: { children: ReactNode }) {
  return (
    <ShellProvider nav={NAV} workspaces={WORKSPACES} apps={APPS} user={USER}>
      {/* ShellProvider emits NO element of its own — context plus a TooltipProvider and
          nothing else. The frame is entirely yours, including the h-dvh column that gives
          <main> something to be flex-1 of; without it the scroll container has no bounded
          height and the whole document scrolls instead. */}
      <div className="flex h-dvh w-full flex-col overflow-hidden bg-background">
        <header className="flex h-header shrink-0 items-center gap-2 border-b border-border px-3">
          <WorkspaceSwitcher align="start" className="w-56" />
          <AppLauncher />
          <MyOwnBreadcrumb />
        </header>
        {/* Keep relative for the same reason AppShell's own <main> has it — see
            "Why the main element is positioned" below. */}
        <main className="relative flex-1 overflow-y-auto">{children}</main>
      </div>
    </ShellProvider>
  )
}

useShell()

The hook every part of the shell uses, and the one your own components use to join in. Called outside a ShellProvider it throws — it does not return undefined and it does not quietly render an empty frame, which is the failure mode that would otherwise ship to production looking like a styling bug.

'use client'

import { CommandPalette } from '@comitor/ui'
import { useShell } from '@comitor/ui/shell'

/**
 * The command palette is a SLOT, not a built-in: what is searchable is the app's
 * data, so the package ships the keyboard state and leaves the content to you.
 * Read and write that state through useShell().
 */
export function AppCommandPalette() {
  // Outside a <ShellProvider> (or <AppShell>) this THROWS — it does not return
  // undefined and it does not render an empty frame.
  const { commandPaletteOpen, setCommandPaletteOpen, apps, onAppSelect } = useShell()

  return (
    <CommandPalette
      open={commandPaletteOpen}
      onOpenChange={setCommandPaletteOpen}
      // The shell already binds Cmd/Ctrl+K. Leaving this on gives you two
      // listeners flipping one boolean — it opens and closes in the same press.
      registerShortcut={false}
      placeholder="Search apps, tasks, people…"
      groups={[
        {
          id: 'apps',
          label: 'Apps',
          items: apps.map((app) => ({
            id: app.id,
            label: app.name,
            icon: app.icon,
            onSelect: () => onAppSelect?.(app),
          })),
        },
      ]}
    />
  )
}

// …then hand it to the frame:
// <AppShell commandPaletteSlot={<AppCommandPalette />}>{children}</AppShell>

Global keyboard shortcuts

One keydown listener on window, registered by the provider and removed on unmount. Set enableShortcuts={false} and it is never attached at all.

Where the collapse state is kept

• localStorage, keyed per workspace. The key is comitor-sidebar:<workspaceId> (comitor-sidebar:default when there are no workspaces), holding "1" or "0". One workspace can be a dense rail and another expanded.
• Deliberately not a cookie. shadcn’s sidebar primitive keeps its state in a sidebar_state cookie; adopting that here would put a second source of truth next to ShellProvider, and a single cookie is the wrong shape for a preference that varies per workspace. It is also why @comitor/ui ships no shadcn sidebar at all — see Sidebar.
• Read after mount, never during render. The first client render uses exactly the defaultSidebarCollapsed the server rendered; an effect then applies the stored value. Reading storage during render would be a hydration mismatch.
• The tablet default is not a decision. Between 768px and 1023px, a reader with no stored choice starts collapsed — the media query comes from layout.breakpoints in @comitor/ui/tokens, not from a number typed into the shell. It is measured once on open, never on resize (a rail that collapses while you drag the window is a jolt), and never written back: writing it would leave the user collapsed on a wide screen next time, having never chosen anything.
• Blocked storage degrades quietly. Both the read and the write are wrapped in try/catch — Safari private mode and locked-down browsers throw on access. The state then simply lives for the session.

The LinkComponent escape hatch

The default is next/link, which is why next is a peer dependency of @comitor/ui/shell. Outside Next, hand the shell your own router link and its pathname.

import type { ReactNode } from 'react'
import { Link as RouterLink, useLocation } from 'react-router-dom'
import { AppShell } from '@comitor/ui/shell'
import type { ShellLinkProps } from '@comitor/ui/shell'
import { NAV } from './shell-model'

// ShellLinkProps is anchor props with href narrowed to a plain string — never
// Next's UrlObject — precisely so another router can be adapted to it.
function ReactRouterLink({ href, ...props }: ShellLinkProps) {
  return <RouterLink to={href} {...props} />
}

export function Shell({ children }: { children: ReactNode }) {
  const location = useLocation()

  return (
    <AppShell
      nav={NAV}
      LinkComponent={ReactRouterLink}
      // usePathname() returns null without an App Router, and the shell falls
      // back to '' — so nothing would ever be active. Pass the path yourself.
      pathname={location.pathname}
    >
      {children}
    </AppShell>
  )
}

Why the main element is positioned

<main> ships as relative flex-1 overflow-y-auto bg-background. The relative is not decoration, and contentClassName must not take it away.

overflow-y-auto does not clip an absolutely positioned descendant unless the scroll container is itself positioned: the containing block escapes to the initial one, so the element sits outside the clip and stretches the document’s scroll height. In a frame that is h-dvh overflow-hidden there is nothing to paint in that extra space, and the reader scrolls into a large blank band.

Two sources of it ship inside this very package: Tailwind’s sr-only is position: absolute with no offsets — as used for the four page labels inside TablePagination’s buttons — and Radix hides the native <input> / <select> of RadioGroup and Select the same way. Measured before the fix on a real page: scrollHeight 1531 against a clientHeight of 900 — 631px of nothing. A form-heavy page measured 892px.

contain: paint would also fix it, and is deliberately not used: it drags in paint and layout containment that nothing here asked for.

Labels — every string in the frame

Every string the shell can display is a key of ShellLabels — including the strings only a screen reader ever hears. The values come from the shell table of the nearest ComitorLocaleProvider: English when there is none, Vietnamese under locale="vi" (Set the language). So language is never what labels is for — wording is. Pass it to AppShell or ShellProvider once and every descendant picks it up from context; there is nothing to fork and nothing to wrap.

'use client'

import type { ReactNode } from 'react'
import { useComitorMessages } from '@comitor/ui'
import { AppShell, useShell } from '@comitor/ui/shell'
import type { ShellLabels } from '@comitor/ui/shell'
import { NAV } from './shell-model'

// Wording, not language: the language comes from ComitorLocaleProvider at the root.
// Partial<ShellLabels> is merged key by key over the provider's shell table, so
// overriding four keys keeps the other thirty, in the provider's language.
// This object is in ONE language — an app that runs in two keeps one per language.
const PANEL_WORDING: Partial<ShellLabels> = {
  navigationLabel: 'Project navigation',
  collapseSidebar: 'Collapse project panel',
  // Visible text on the same button. Keep it a SUBSTRING of the long string, or
  // the voice command "click Collapse" stops matching the accessible name —
  // WCAG 2.5.3, Label in Name.
  collapseSidebarShort: 'Collapse',
  expandSidebar: 'Expand project panel',
}

export function Shell({ children }: { children: ReactNode }) {
  return (
    <AppShell labels={PANEL_WORDING} nav={NAV}>
      {children}
    </AppShell>
  )
}

// Reading a string back — for a tooltip of your own, say — take it from where the
// frame takes it, so it follows the language and your overrides. Never hard-code it,
// and not DEFAULT_SHELL_LABELS either: since 3.0.0 that is the English table only.
export function InboxHint() {
  const { labels } = useShell() // inside the frame: merged, overrides included
  return <span>{labels.notifications}</span>
}

export function SignInHint() {
  const shell = useComitorMessages('shell') // outside it: the provider's table
  return <span>{shell.notifications}</span>
}

There are 34 keys since 3.7.0, which added skipToContent; before that the set had not changed since collapseSidebarShort was split out of collapseSidebar in 0.5.0. Two rules for rewording or translating them: override in pairs where one key is visible text and another is the accessible name of the same control, and keep the short string a substring of the long one, or a voice-control user saying “click Collapse” will no longer match the accessible name (WCAG 2.5.3, Label in Name). Both value columns below are read from the installed package, not typed into this page.

DEFAULT_SHELL_LABELS still lives in a plain module — types and one constant, no hooks, no 'use client' — but since 3.0.0 it is only the English table, kept for an app to spread; nothing in the shell reads it. For a string rendered on the server in the user’s language, getComitorMessages(locale).shell is the pure equivalent. What a Server Component cannot do is hand a whole table to AppShell: members is a function, and functions do not cross the server → client boundary. A labels object that carries one is built inside a client component.

AppShell props

AppShellProps extends ShellProviderProps, so everything in the next table is accepted here too and forwarded untouched. These are the props AppShell keeps for itself.

ShellProvider props

The complete data contract of Tier 3. Nothing here is stored by the package — every workspace, product, menu and user is yours, passed in.

useShell() return value

ShellContextValue, memoised on its inputs. Callbacks are passed through as-is, so an undefined handler is information: several parts of the shell drop a row rather than render one that does nothing.

ShellBrand fields

The shape of brand (3.15.0). Only name is required.

AppBrand props

Everything else comes from useShell().brand, so it must render inside ShellProvider or AppShell.

Accessibility

• One landmark per job. The frame emits a <header>, a <nav> named by labels.navigationLabel and a single <main> holding your page. Do not nest another <main> in children.
• Escape always works. It is the one shortcut evaluated before the typing guard, so it closes the command palette, the launcher and the mobile menu even while a text field has focus — including the search field inside the thing being closed.
• Nothing is claimed that is not implemented. ⌘/Ctrl+K flips a boolean and no more; without a commandPaletteSlot there is no dialog to announce, and no focus to trap. If you advertise the shortcut in your UI, supply the slot.
• Alt+digits use event.code. On macOS Alt+1 produces “¡”, so matching on event.key would silently fail for every Mac user. Locked apps are skipped, so the numbers count what a person can actually open.
• A skip link comes with the frame. Since 3.7.0 the first thing Tab reaches is “Skip to main content” — invisible until focused — which jumps past the whole sidebar to <main id="main-content" tabIndex={-1}>. The tabIndex is what makes the jump move focus: without it the browser scrolls but focus stays on the link, and the next Tab goes back to the top of the sidebar. An app that drew its own skip link beside the shell should delete it — and its own target — or keyboard users meet two in a row. Rename the target with mainId, drop the link with skipLink={false}, reword it with skipToContent.
• The language reaches the invisible strings too. ShellLabels covers aria-label and sr-only text as well as visible copy, and the provider switches all of it at once. An app that rewords only the visible half leaves screen reader users on different words from everyone else — and where the two describe one control, an accessible name in one language over visible text in another breaks WCAG 2.5.3 outright.
• The theme lives above the shell. Mounting ThemeProvider inside AppShell makes the page flash the wrong palette during hydration — a real problem for readers sensitive to sudden luminance change, and the reason the display axes belong at the root layout.
• position: relative on the main region is an a11y fix too. Without it the visually hidden labels that make the frame readable are exactly what stretches the document and produces the phantom blank scroll.
• The collapsed rail keeps its names. Every icon tile carries a tooltip and an aria-label, and the active row is marked aria-current="page" at both widths — see Sidebar for the measurements behind those choices.

Related

@comitor/ui/shellPeer dependencies: next and next-themes.