Skip to content
View as Markdown

SidebarLayout ​

SidebarLayout is the default AppShell layout. By default it renders:

  • SidebarLayout.DefaultSidebar
  • SidebarLayout.DefaultHeader
  • the current route outlet

You can replace the sidebar, replace the content header, add a full-width topBar above the whole shell, or take over the entire region beside the sidebar with the body slot.

If you want the opinionated "global app header + icon rail" mode, use GlobalHeaderLayout, which is built on top of SidebarLayout.

Import ​

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

Basic usage ​

tsx
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";

function App() {
  return (
    <AppShell modules={modules}>
      <SidebarLayout />
    </AppShell>
  );
}

This gives you:

  • ✅ Responsive sidebar with auto-generated navigation from modules
  • ✅ Breadcrumb navigation
  • ✅ Theme toggle via the built-in header
  • ✅ Mobile-friendly collapse behavior

Props ​

Common props ​

PropTypeDefaultDescription
sidebarReact.ReactNode<SidebarLayout.DefaultSidebar />Replaces the entire sidebar region.
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. Mobile/tablet drawer access is independent of this setting.
collapsibleboolean-Deprecated compatibility prop: explicit false maps to "fixed" and explicit true to "collapse". Cannot be combined with sidebarBehaviour.
topBarReact.ReactNode-Full-width bar above both the sidebar and the content region.

Default content mode ​

Use this when AppShell should keep owning the content column.

PropTypeDefaultDescription
headerReact.ReactNode<SidebarLayout.DefaultHeader />Replaces the content header above the main column.
children(props: { Outlet: () => React.ReactNode }) => React.ReactNodecurrent route outletCustom content renderer that wraps or surrounds the outlet.

Body-slot mode ​

Use this when you need to compose your own columns beside the sidebar.

PropTypeDefaultDescription
bodyReact.ReactNoderequiredReplaces everything to the right of the sidebar. Compose it with ContentContainer, Outlet, and Trigger.

body is mutually exclusive with header and children, because it replaces the region those props normally describe.

Resizing the sidebar ​

sidebarBehaviour selects the desktop operations. It defaults to "collapse-and-resize":

ModeCollapseResize
"fixed"NoNo
"collapse"YesNo
"resize"NoYes
"collapse-and-resize"YesYes
tsx
<SidebarLayout />; // Both operations are enabled by default
<SidebarLayout sidebarBehaviour="fixed" />;
<SidebarLayout sidebarBehaviour="collapse" />;
<SidebarLayout sidebarBehaviour="resize" />;
<SidebarLayout sidebarBehaviour="collapse-and-resize" />;

"fixed" and "resize" always keep the desktop sidebar expanded, ignore defaultOpen, and make useAppShellSidebar().setOpen() inert. They hide desktop collapse controls and do not intercept the desktop toggle shortcut. "collapse" has toggle controls but no resize handle.

All modes keep the layout's normal mobile/tablet drawer and icon-rail overlay presentation. The trigger, toggle(), and shortcut can still open the full menu when desktop collapsing is disabled. These responsive visibility states are independent of desktop expansion.

Deprecated collapsible ​

The existing boolean remains supported but is deprecated. Explicit false maps to "fixed"; explicit true maps to "collapse". Omitting both props uses the new "collapse-and-resize" default. TypeScript rejects specifying both props together.

tsx
// Before
<SidebarLayout collapsible={false} />;

// After
<SidebarLayout sidebarBehaviour="fixed" />;

This intentionally changes the responsive presentation of legacy collapsible={false}: it no longer forces a fixed sidebar on mobile/tablet. It keeps desktop fixed while using the normal responsive drawer/overlay. A completely custom sidebar still owns its own presentation and sizing.

Resize interaction ​

The initial width is 256px. In "resize" and "collapse-and-resize" modes, the whole outer edge of the expanded desktop sidebar is a resize handle. Hovering it shows the resize cursor and a small pill beside the border that follows the pointer. Drag the edge, or focus the handle and use Left/Right arrows (16px steps), Home, or End (480px). Double-click restores the default 256px width.

In "resize" mode, dragging follows the pointer and clamps to 192–480px without collapse resistance. Home and Left at the minimum keep the sidebar at 192px; double-clicking at 256px does not collapse it.

In "collapse-and-resize" mode, Home or Left at the minimum collapses the sidebar, and double-clicking at 256px collapses it. The collapsed desktop sidebar keeps its handle. Double-clicking it or using Enter/Space restores 256px; a single pointer click does nothing.

In "collapse-and-resize" mode, dragging uses a position-based resistance curve, not a delayed CSS transition. Between the collapsed width and the minimum expanded width (192px), most of the interval uses a 25% movement gain: moving the pointer 10px moves the edge only 2.5px. In the final quarter near the opposite boundary, a smooth position-based blend catches up to the pointer. The edge stops when the pointer stops; it does not catch up over time. At 192px and above it follows the pointer 1:1, up to 480px. Shrinking through the same range resists toward the collapsed position. It collapses slightly early, when the pointer enters the final 20% of that interval, with the curve already meeting the collapsed width at that point. The same pointer stays captured across both transitions, without a jump to 256px.

With collapsing enabled, releasing inside the resistance range settles back to the current mode's boundary (collapsed width or 192px).

Live drag pixels are applied through CSS custom properties rather than React state on every pointer movement. React commits the width at mode changes and when the gesture ends; ARIA values stay current during dragging. Width changes still require browser layout because the content column resizes live.

Width is not persisted across remounts or reloads. The icon rail keeps its existing collapsed width. Mobile drawers and tablet overlays keep their existing widths and do not show handles.

This applies to the built-in sidebar primitives, including SidebarLayout.DefaultSidebar. An arbitrary custom sidebar element still owns its own sizing.

Extending the built-in header ​

The supported "small customization" path is to pass SidebarLayout.DefaultHeader into the header slot and fill its actions cluster.

tsx
import { AppearanceSwitcher, Button, SidebarLayout } from "@tailor-platform/app-shell";
import { BellIcon } from "lucide-react";

<SidebarLayout
  header={
    <SidebarLayout.DefaultHeader
      actions={[
        <Button key="notifications" variant="outline" size="icon" aria-label="Notifications">
          <BellIcon className="size-4" />
        </Button>,
        <AppearanceSwitcher key="appearance" />,
      ]}
    />
  }
/>;

actions replaces the entire right-hand cluster. If you still want the built-in appearance switcher, include <AppearanceSwitcher /> yourself.

Replacing the sidebar ​

Pass sidebar to replace the whole left-side region. The built-in component is SidebarLayout.DefaultSidebar, also exported as DefaultSidebar.

tsx
import {
  SidebarGroup,
  SidebarItem,
  SidebarLayout,
  SidebarSeparator,
} from "@tailor-platform/app-shell";

<SidebarLayout
  sidebar={
    <SidebarLayout.DefaultSidebar>
      <SidebarItem to="/" />
      <SidebarSeparator />
      <SidebarGroup title="Main">
        <SidebarItem to="/dashboard" />
        <SidebarItem to="/orders" />
      </SidebarGroup>
    </SidebarLayout.DefaultSidebar>
  }
/>;

Adding an app-wide top bar ​

topBar renders above the whole shell, spanning both the sidebar and the content region.

tsx
<SidebarLayout topBar={<MyGlobalTopBar />} sidebar={<SidebarLayout.DefaultSidebar hideHeader />} />

When topBar is present, the fixed sidebar is offset below it. The bar should be 3.5rem tall (h-14) to match the built-in layout.

If you specifically want AppShell's opinionated global-header mode, use GlobalHeaderLayout, which wires the top bar, icon rail, and matching default sidebar for you.

Owning the region beside the sidebar ​

Use body when the stock content column is too restrictive and you need your own side columns.

tsx
<SidebarLayout
  body={
    <>
      <aside className="w-64 shrink-0 overflow-y-auto border-r">
        <TableOfContents />
      </aside>
      <SidebarLayout.ContentContainer header={<SidebarLayout.DefaultHeader />}>
        <SidebarLayout.Outlet />
      </SidebarLayout.ContentContainer>
      <aside className="w-96 shrink-0 overflow-y-auto border-l">
        <AssistantPanel />
      </aside>
    </>
  }
/>

SidebarLayout.ContentContainer is the stock main column: inset padding, pinned header slot, scroll region, and useAppShellScrollContainer() support. SidebarLayout.Trigger exposes the built-in sidebar toggle so custom headers do not need DOM workarounds.

Reading and controlling the sidebar ​

Use useAppShellSidebar() to read and control the sidebar state instead of observing internal DOM attributes or clicking the trigger through the DOM. It also exposes the effective sidebarBehaviour, already normalized from either public prop, so custom sidebars do not need to handle the deprecated boolean themselves.

open and setOpen() describe desktop expansion. Drawer visibility is separate: toggle() selects the mobile drawer, tablet overlay, or desktop state according to the viewport. The four existing hook fields (open, isMobile, setOpen, and toggle) remain available.

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

function CustomHeader() {
  const { sidebarBehaviour, open, isMobile, toggle } = useAppShellSidebar();

  return (
    <div className="flex items-center justify-between border-b px-4 py-3">
      <button type="button" onClick={toggle}>
        Toggle navigation
      </button>
      <span>
        {sidebarBehaviour}: {open ? "Desktop expanded" : "Desktop collapsed"}
      </span>
      <span>{isMobile ? "Mobile" : "Non-mobile"}</span>
    </div>
  );
}

Outside SidebarLayout, the hook returns a safe fallback (sidebarBehaviour: "fixed", open: true, isMobile: false, no-op actions) rather than throwing. This fallback describes the absence of a managed sidebar; it is not the layout's default mode.

The desktop capabilities can be derived from the reported mode: "collapse" and "collapse-and-resize" permit collapse, while "resize" and "collapse-and-resize" permit resizing. Reading this setting does not automatically add resize behavior to arbitrary custom markup.

Reusing the built-in breadcrumb ​

DynamicBreadcrumb is exported when you want the same route-driven breadcrumb in a custom header or top bar:

tsx
import { DynamicBreadcrumb, SidebarLayout } from "@tailor-platform/app-shell";

<header className="flex items-center gap-3 border-b px-4 py-3">
  <SidebarLayout.Trigger />
  <DynamicBreadcrumb />
</header>;

Accessing the content scroll container ​

The AppShell is viewport-bounded (h-svh), so the document itself does not scroll — the content area does. Code that previously relied on window/document scroll (reading window.scrollY, listening to window's scroll event, window.scrollTo(...), or an IntersectionObserver with the default viewport root) should target the content scroll container instead.

Use the useAppShellScrollContainer() hook to get a ref to that element from any page:

tsx
import { useAppShellScrollContainer } from "@tailor-platform/app-shell";
import { useEffect, useState } from "react";

function ReadingProgress() {
  const scrollRef = useAppShellScrollContainer();
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    const el = scrollRef.current;
    if (!el) return;
    const onScroll = () => {
      const max = el.scrollHeight - el.clientHeight;
      setProgress(max > 0 ? el.scrollTop / max : 0);
    };
    onScroll();
    el.addEventListener("scroll", onScroll, { passive: true });
    return () => el.removeEventListener("scroll", onScroll);
  }, [scrollRef]);

  return <progress value={progress} />;
}

The same element handles imperative scrolling (scrollRef.current?.scrollTo({ top: 0, behavior: "smooth" })) and works as an IntersectionObserver root (new IntersectionObserver(cb, { root: scrollRef.current })).

Notes:

  • The element mounts with the layout, above your page, so read ref.current inside an effect — it is populated by the time effects run, not during render.
  • On a <Layout fill> page this element does not scroll; its children (for example a DataTable) manage their own scrolling.
  • Outside a SidebarLayout (a fully custom layout) the returned ref's current is always null — such layouts own their own scroll region.
  • For non-React access (CSS, tests, plain DOM) the container also carries a data-appshell-scroll-container attribute: document.querySelector("[data-appshell-scroll-container]").

Styling ​

The sidebar and layout are styled with the library's internal astw:-prefixed utilities. Write plain Tailwind utilities in your own markup — see Styling AppShell components.

Accessibility ​

SidebarLayout includes built-in accessibility features:

  • Keyboard navigation for sidebar interaction
  • ARIA labels on built-in controls
  • Focus management when the sidebar opens on mobile
  • Responsive behavior that works with keyboard, mouse, and touch input