Skip to content
View as Markdown

GlobalHeaderLayout ​

GlobalHeaderLayout is AppShell's opinionated "global top bar" layout. It is a thin wrapper over SidebarLayout that wires together:

  • an app-wide header above both the sidebar and the content area
  • a default sidebar with its own header removed
  • icon-rail collapse behavior
  • the stock content container and outlet

Use it when you want the whole app to share one top bar. Reach for SidebarLayout directly when you need the more flexible primitive.

Import ​

tsx
import { GlobalHeaderLayout } from "@tailor-platform/app-shell";

Basic usage ​

tsx
import {
  AppShell,
  AppearanceSwitcher,
  GlobalHeaderLayout,
  SidebarGroup,
  SidebarItem,
} from "@tailor-platform/app-shell";
import { LayersIcon } from "lucide-react";

function App() {
  return (
    <AppShell title="Operations" modules={modules}>
      <GlobalHeaderLayout
        header={
          <GlobalHeaderLayout.DefaultHeader actions={[<AppearanceSwitcher key="appearance" />]} />
        }
        sidebar={
          <GlobalHeaderLayout.DefaultSidebar>
            <SidebarItem to="/" />
            <SidebarGroup title="Main" icon={<LayersIcon className="size-4" />}>
              <SidebarItem to="/dashboard" />
              <SidebarItem to="/orders" />
            </SidebarGroup>
          </GlobalHeaderLayout.DefaultSidebar>
        }
      />
    </AppShell>
  );
}

Props ​

PropTypeDefaultDescription
headerReact.ReactNode<GlobalHeaderLayout.DefaultHeader />Replaces the full-width app header.
sidebarReact.ReactNode<GlobalHeaderLayout.DefaultSidebar />Replaces the primary sidebar.
defaultOpenbooleantrueWhether the sidebar starts expanded on desktop. Ignored in "fixed" and "resize" modes.
sidebarBehaviour"fixed" | "collapse" | "resize" | "collapse-and-resize""collapse-and-resize"Selects the permitted desktop operations without restricting mobile/tablet drawer access.
collapsibleboolean-Deprecated compatibility prop: explicit false maps to "fixed" and explicit true to "collapse". Cannot be combined with sidebarBehaviour.
children(props: { Outlet: () => React.ReactNode }) => React.ReactNodecurrent route outletCustom content renderer for the stock content container.
bodyReact.ReactNode-Escape hatch that replaces the entire region beside the sidebar.

children and body are mutually exclusive. Use body when you need to add your own side columns around the main content.

Resizing the sidebar ​

sidebarBehaviour selects the desktop operations and defaults to "collapse-and-resize". The four modes are shared with SidebarLayout:

tsx
<GlobalHeaderLayout />; // Both operations are enabled by default
<GlobalHeaderLayout sidebarBehaviour="fixed" />; // Neither operation
<GlobalHeaderLayout sidebarBehaviour="collapse" />; // Collapse only
<GlobalHeaderLayout sidebarBehaviour="resize" />; // Resize only
<GlobalHeaderLayout sidebarBehaviour="collapse-and-resize" />; // Both

"fixed" and "resize" keep desktop expanded, ignore defaultOpen, and make the hook's setOpen() action inert. "fixed" has no desktop interaction controls; "resize" has a resize handle but no collapse controls. "collapse" has collapse controls but no resize handle. Desktop toggle shortcuts are not intercepted when collapsing is disabled.

Every mode keeps the layout's normal responsive icon rail and mobile/tablet overlay, so the trigger, toggle(), and shortcut can still open the full menu. Desktop expansion and responsive drawer visibility are independent.

collapsible remains supported but deprecated. Explicit false maps to "fixed", explicit true maps to "collapse", and omitting both props uses the new default. TypeScript rejects specifying both props. Replace legacy collapsible={false} with sidebarBehaviour="fixed"; it keeps desktop fixed but intentionally no longer forces a fixed sidebar on mobile/tablet.

The edge resize handle and keyboard resizing match SidebarLayout. Resize-only mode clamps pointer and keyboard widths to 192–480px without collapse resistance, and double-click only resets to 256px. With "collapse-and-resize", dragging uses resistance near the rail and can open, resize, and collapse in one gesture; double-clicking at 256px collapses, and double-click or keyboard expansion restores 256px. Width is not saved across reloads. Responsive overlay widths and the collapsed rail width are unchanged.

Custom sidebars can read the effective, normalized sidebarBehaviour through useAppShellSidebar(). Its existing state and actions remain available; arbitrary custom markup still owns its presentation and sizing.

Built-in parts ​

GlobalHeaderLayout exposes the same composition pieces as SidebarLayout, plus the opinionated header and sidebar defaults:

ExportDescription
GlobalHeaderLayout.DefaultHeaderThe app-wide header (GlobalHeader) with app title + breadcrumb on the left and actions on the right.
GlobalHeaderLayout.DefaultSidebarDefaultSidebar with hideHeader and iconRail forced on.
GlobalHeaderLayout.ContentContainerThe stock main content column.
GlobalHeaderLayout.OutletThe current route outlet.
GlobalHeaderLayout.TriggerThe built-in sidebar toggle button.
GlobalHeaderLayout.BreadcrumbThe route-driven breadcrumb component (DynamicBreadcrumb).

The layout's default header is also exported as a top-level GlobalHeader component. It renders:

  • the AppShell title and optional icon
  • the route-driven breadcrumb
  • a right-aligned actions cluster

actions behaves the same way as on SidebarLayout.DefaultHeader: omitting it renders the built-in AppearanceSwitcher, and passing it replaces the entire right-hand cluster.

tsx
import { AppearanceSwitcher, GlobalHeader } from "@tailor-platform/app-shell";

<GlobalHeader actions={[<AppearanceSwitcher key="appearance" />]} />;

Owning the body region ​

Use body when you want custom columns beside the content while still keeping the global header and icon-rail sidebar.

tsx
<GlobalHeaderLayout
  body={
    <>
      <GlobalHeaderLayout.ContentContainer>
        <GlobalHeaderLayout.Outlet />
      </GlobalHeaderLayout.ContentContainer>
      <aside className="w-96 shrink-0 overflow-y-auto border-l">
        <AssistantPanel />
      </aside>
    </>
  }
/>

When to use which layout ​

GoalUse
Built-in sidebar + content headerSidebarLayout
Full-width app header above the whole shellGlobalHeaderLayout
Completely custom page structure with AppShell routingSidebarLayout body={...} or GlobalHeaderLayout body={...}
  • SidebarLayout - lower-level primitive that GlobalHeaderLayout wraps
  • DefaultSidebar - underlying sidebar component used by GlobalHeaderLayout.DefaultSidebar
  • DefaultHeader - content-column header for SidebarLayout