AppShell

When to useLink to "When to use"

• The outer layout of an app with a persistent navigation.

Use something else when:

• the page is a document or a marketing page: your own layout with Prose and Stack
• you only need the navigation: SideNav

UsageLink to "Usage"

import { AppShell, SideNav } from "@arshad-shah/cynosure";

<div style={{ blockSize: "100dvh" }}>
  <AppShell header={<Brand />} nav={<SideNav label="Main" items={items} current={route.id} />}>
    <Page />
  </AppShell>
</div>

The shell fills its container's height. The content and the navigation scroll on their own while the bar stays in place.

Padding and width of the pageLink to "Padding and width of the page"

The main region has no padding and no maximum width, so a page can run edge to edge (a map, a table, a canvas). For an ordinary page, wrap the content in Container, which pads it and caps its width.

<AppShell header={<Brand />} nav={<SideNav label="Main" items={items} />}>
  <Container>
    <Page />
  </Container>
</AppShell>

Narrow screensLink to "Narrow screens"

Below collapseBelow (768px of the shell's own width) the navigation leaves the layout. A menu button appears at the start of the bar and opens it in a start-side Sheet. Choosing a link or item closes the drawer; opening a group does not.

A tab bar on phonesLink to "A tab bar on phones"

tabs adds a bottom tab bar while the shell is narrow, for an app's three to five main sections. Pass a SideNav with layout="bar" and the same current; the drawer still holds the full navigation. The bar keeps clear of the phone's home indicator.

<AppShell
  nav={<SideNav label="Main" items={items} current={page} onNavigate={go} />}
  tabs={<SideNav label="Sections" layout="bar" items={sections} current={page} onNavigate={go} />}
>

A SideNav entry with kind: "action" puts one raised primary button, such as "Add", in the bar. In the drawer the same entry is a full-width button, and pressing it closes the drawer.

Reading the narrow stateLink to "Reading the narrow state"

Do not repeat the breakpoint in your product. Anything rendered inside the shell (header, navigation, tabs, content) reads it with useAppShell(). Code outside the shell uses onNarrowChange.

import { AppShell, useAppShell } from "@arshad-shah/cynosure";

function Toolbar() {
  const { narrow } = useAppShell();
  return narrow ? <CompactToolbar /> : <FullToolbar />;
}

<AppShell header={<Toolbar />} onNarrowChange={(narrow) => setCompact(narrow)}>

• narrow is true while the shell's own width is below collapseBelow.
• It is false on the server and on the first client render, so server markup hydrates without a mismatch. The shell measures itself before the first paint and renders again if it is narrow.
• Outside an AppShell the hook does not throw. It returns { narrow: false }.
• onNarrowChange is called once per change. A shell that mounts narrow calls it with true right after mounting; a shell that mounts wide does not call it until it narrows.
• There is no hook for the drawer: the shell closes it itself when a link or button inside it is pressed.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Landmarks: the bar is a <header> (banner), the navigation keeps its own <nav>, and the content is <main>.
• Skip link: a SkipLink at the shell's own top-start corner. The first Tab shows "Skip to content"; Enter moves focus to <main> without changing the URL, so your router stays in charge.
• Drawer: a modal Sheet named "Navigation" with focus trapping and Escape; focus returns to the menu button when it closes. The button reports aria-expanded.
• Touch: the menu button's hit area is at least 44px on touch screens.
• Direction: the navigation is on the right in right-to-left text, and the drawer slides from that side.
• All built-in text is in labels.

ThemingLink to "Theming"

Tokens: --cy-app-shell-nav-background, --cy-app-shell-header-background and --cy-app-shell-border.

RelatedLink to "Related"

SideNav · Container · Sheet · Toolbar