Navigation

AppShell

The landmarks of a product — a sidebar column, a sticky topbar, a scrolling main region and an optional status strip — plus the navigation model that fills them.

Examples

The standard shell

The real component at a bounded height: sidebar, topbar, content and status bar are the same frame the Showcase itself runs in. Push the rail on the edge, or the toggle in the sidebar footer, and the column becomes a rail with every label kept as an accessible name; below 1024px the column gives way to the drawer in the topbar. Ctrl/⌘ + B is off here so the demo cannot fight the Showcase's own shell.

The column is on.

Window1Y

Samples365

Series3

Prepared locallyUpdated 12:04 UTC

<AppShell
  height="fill"
  pathname={pathname}                 // a string, not a router
  renderLink={(props) => <Link {...props} />}
  onNavigate={closeDrawer}
  sidebarCollapsed={collapsed}        // controlled, or leave it out
  onSidebarCollapsedChange={setCollapsed}
  sidebarPersistKey="product:sidebar" // the rail survives a reload
  sidebar={
    <>
      <SidebarHeader>…</SidebarHeader>
      <SidebarContent ariaLabel="Sections">
        <SidebarGroup>
          <SidebarGroupLabel>Overview</SidebarGroupLabel>
          <SidebarMenu>
            <SidebarItem label="Datasets" href="/datasets" icon={<RiDatabase2Line />}>
              <SidebarItem label="Prices" href="/datasets/prices" />
            </SidebarItem>
            <SidebarItem label="Billing" disabled />
          </SidebarMenu>
        </SidebarGroup>
      </SidebarContent>
      <SidebarFooter>
        <SidebarToggle />
      </SidebarFooter>
    </>
  }
  topbar={
    <AppShellTopbar>
      <AppShellMobileTrigger />
      <Breadcrumbs items={[{ label: "Luc UI", href: "/" }, { label: "Overview" }]} />
    </AppShellTopbar>
  }
  statusBar={<AppShellStatusBar>Updated 12:04 UTC</AppShellStatusBar>}
>
  <AppShellContent>…</AppShellContent>
</AppShell>

Filtering the model

The same tree the sidebar renders, filtered as the reader types. A parent survives when one of its children matches, so a search never hides the way to the page it found — and the function that drives this demo is the one the Showcase sidebar calls.

Filtering keeps the path

The model is data, so everything that reads it is a pure function: filter it, flatten it, or turn it into command entries without keeping a second copy of the routes.

const groups = filterNavigation(navigation, "prices");
// The Datasets parent survives the filter; nothing else does. isNavigationItemActive("/charts/timeseries", "/charts");
// true

isNavigationItemActive("/charts-archive", "/charts");
// false — the boundary is a path segment, not a prefix

findActiveNavigationItem(groups, pathname);
// the most specific ancestor

const groups = filterNavigation(navigation, query);

<SidebarProvider collapsible={false} shortcut={false}>
  <SidebarContent ariaLabel="Sections">
    {groups.map((group) => (
      <SidebarGroup key={group.id}>
        <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
        <SidebarMenu>
          {group.items.map((item) => (
            <SidebarItem key={item.id} label={item.label} href={item.href} icon={item.icon} />
          ))}
        </SidebarMenu>
      </SidebarGroup>
    ))}
  </SidebarContent>
</SidebarProvider>

What the model derives

Every navigable item, depth-first, with a pre-computed lowercase haystack for matching. The command palette does not keep its own copy of the routes; extras are for actions that are not navigation — copy the view, switch the theme, run a job.

Overview/application
Datasetsaction
Prices/application/navigation
Flows/application/navigation
Reports/application/workspace
Settings/application/url-state
Billing/application/url-state

6 command entries derived from 7 navigation items.

// The palette's list is derived, never hand-written.
const entries = navigationCommandEntries(navigation, [
  { id: "copy-view", label: "Copy view link", action: copyView },
]);

entries.map((entry) => (
  <CommandItem key={entry.id} value={entry.haystack} onSelect={() => run(entry)}>
    {entry.label}
  </CommandItem>
))

Routing is injected, not imported

The library never imports a router. Three props say what an href means, which location is current, and what happens when someone follows one — which is the whole integration, for Next, React Router or a plain anchor.

NextReact RouterPlain anchor

Every link in the frames above is a real anchor to a real route. That is the default, not the adapter.

<AppShell
  pathname={usePathname()}
  renderLink={(props) => <Link {...props} />}
  onNavigate={(href) => analytics.track("nav", href)}
/>

// With no adapter at all the default renders a real anchor, so middle-click,
// "open in a new tab" and the browser's own link preview keep working.

Usage

import {
  AppShell,
  AppShellContent,
  AppShellStatusBar,
  AppShellTopbar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarItem,
  SidebarMenu,
  SidebarToggle,
} from "@luc/ui/app-shell";

<AppShell
  pathname={pathname}
  renderLink={(props) => <Link {...props} />}
  sidebar={
    <SidebarContent ariaLabel="Sections">
      <SidebarGroup>
        <SidebarGroupLabel>Research</SidebarGroupLabel>
        <SidebarMenu>
          <SidebarItem label="Datasets" href="/datasets" />
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
  }
  topbar={<AppShellTopbar>…</AppShellTopbar>}
>
  <AppShellContent>…</AppShellContent>
</AppShell>

The shell owns the landmarks, the skip link and the responsive switch; the sidebar's contents are yours. `renderLink`, `pathname` and `onNavigate` are the only router-shaped props — the library never imports a router.

Exports

Read from the published TypeScript API, so a prop that is not listed here does not exist and a default that is listed is the one the compiler sees.

One import publishes four modules: the shell, the sidebar parts, the breadcrumbs and the page header. All four tables are below — the shell's two components and `SidebarItem` are open, and the rest of the sub-surface folds away behind a disclosure, because a page that documents five modules at once has to keep a reader from scrolling through props they did not come for.

Exported symbols
Export	Kind	Signature
`AppShell`	22 documented props	`({ children, sidebar, topbar, statusBar, mobileNav, mobileNavTitle, sidebarColumn, sidebarCollapsed, defaultSidebarCollapsed, onSidebarCollapsedChange, collapsibleSidebar, sidebarPersistKey, sidebarP…`
`AppShellContent`	1 documented props	`({ className, width, ...props }: AppShellContentProps) => import("@types/react").JSX.Element`
`AppShellMobileNav`	2 documented props	`({ children, title }: AppShellMobileNavProps) => import("@types/react").JSX.Element`
`AppShellMobileTrigger`	1 documented props	`({ className }: { className?: string; }) => import("@types/react").JSX.Element`
`AppShellSidebar`	export	`({ className, children, ...props }: React.ComponentPropsWithRef<"aside">) => import("@types/react").JSX.Element`
`AppShellStatusBar`	export	`({ className, ...props }: React.ComponentPropsWithRef<"div">) => import("@types/react").JSX.Element`
`AppShellTopbar`	export	`({ className, children, ...props }: React.ComponentPropsWithRef<"header">) => import("@types/react").JSX.Element`

Exported symbols
Export	Kind	Signature
`Sidebar`	export	`({ className, children, ...props }: React.ComponentPropsWithRef<"div">) => import("@types/react").JSX.Element`
`SidebarContent`	1 documented props	`({ className, ariaLabel, ...props }: SidebarContentProps) => import("@types/react").JSX.Element`
`SidebarFooter`	export	`({ className, ...props }: React.ComponentPropsWithRef<"div">) => import("@types/react").JSX.Element`
`SidebarGroup`	5 documented props	`({ label, children, collapsible, defaultOpen, badge, className, ...props }: SidebarGroupProps) => import("@types/react").JSX.Element`
`SidebarGroupLabel`	export	`({ className, children, ...props }: React.ComponentPropsWithRef<"p">) => import("@types/react").JSX.Element`
`SidebarHeader`	export	`({ className, ...props }: React.ComponentPropsWithRef<"div">) => import("@types/react").JSX.Element`
`SidebarItem`	9 documented props	`({ label, href, icon, badge, active, disabled, children, defaultOpen, onSelect, className, ...props }: SidebarItemProps) => import("@types/react").JSX.Element`
`SidebarMenu`	export	`({ className, ...props }: React.ComponentPropsWithRef<"ul">) => import("@types/react").JSX.Element`
`SidebarProvider`	12 documented props	`({ children, collapsed: collapsedProp, defaultCollapsed, onCollapsedChange, collapsible, persistKey, persistVersion, storage, shortcut, mobileOpen: mobileOpenProp, defaultMobileOpen, onMobileOpenChan…`
`SidebarRail`	2 documented props	`({ className, expandLabel, collapseLabel, ...props }: SidebarRailProps) => import("@types/react").JSX.Element \| null`
`SidebarSubmenu`	6 documented props	`({ label, href, icon, badge, active, defaultOpen, className, children, ...props }: SidebarSubmenuProps) => import("@types/react").JSX.Element`
`SidebarToggle`	6 documented props	`({ className, label, ...props }: Omit<React.ComponentPropsWithRef<typeof IconButton>, "icon" \| "label"> & { label?: string; }) => import("@types/react").JSX.Element \| null`
`useSidebar`	export	`() => SidebarContextValue`

Exported symbols
Export	Kind	Signature
`Breadcrumb`	export	`({ className, ...props }: React.ComponentPropsWithRef<"nav">) => import("@types/react").JSX.Element`
`BreadcrumbItem`	export	`({ className, ...props }: React.ComponentPropsWithRef<"li">) => import("@types/react").JSX.Element`
`BreadcrumbLink`	2 documented props	`({ className, href, children, ...props }: BreadcrumbLinkProps) => import("@types/react").JSX.Element`
`BreadcrumbList`	export	`({ className, ...props }: React.ComponentPropsWithRef<"ol">) => import("@types/react").JSX.Element`
`BreadcrumbPage`	export	`({ className, ...props }: React.ComponentPropsWithRef<"span">) => import("@types/react").JSX.Element`
`Breadcrumbs`	4 documented props	`({ items, maxItems, className, trailing }: BreadcrumbsProps) => import("@types/react").JSX.Element`
`BreadcrumbSeparator`	export	`({ className, children, ...props }: React.ComponentPropsWithRef<"li">) => import("@types/react").JSX.Element`

Exported symbols
Export	Kind	Signature
`PageHeader`	9 documented props	`({ eyebrow, title, description, meta, actions, controls, tabs, density, sticky, className, children, ...props }: PageHeaderProps) => import("@types/react").JSX.Element`
`PageHeaderMeta`	1 documented props	`({ marker, className, children, ...props }: PageHeaderMetaProps) => import("@types/react").JSX.Element`

Exported symbols
Export	Kind	Signature
`NavigationLink`	4 documented props	`({ href, onNavigate, onClick, children, ...props }: NavigationLinkExtendedProps & { onNavigate?: (href: string) => void; }) => import("@types/react").JSX.Element`
`NavigationProvider`	4 documented props	`({ renderLink, pathname, onNavigate, children, }: NavigationProviderProps) => import("@types/react").JSX.Element`
`useNavigation`	export	`() => NavigationContextValue`