The application and page shell. One set of parts and two app shells that share it: plain, the classic rail-and-content layout, and docked, the default, a black frame with the content set into it.
Koala UIimport {
Layout, LayoutSidebar, LayoutSidebarTrigger, LayoutContent,
LayoutHeader, LayoutContainer,
} from "@/components/ui/layout"
export function AppShell({ children }: { children: React.ReactNode }) {
return (
<Layout className="h-svh overflow-hidden">
<LayoutSidebar>{/* nav */}</LayoutSidebar>
<LayoutContent>
<LayoutHeader>
<LayoutSidebarTrigger />
{/* breadcrumbs */}
</LayoutHeader>
<LayoutContainer>{children}</LayoutContainer>
</LayoutContent>
</Layout>
)
}There are two app shells and one reading shell. The two app shells are the same layout — same parts, same structure, same scroll model, rail · content — at two levels of dress. Switching between them changes nothing about your markup.
plain — the classic shell. One background, one hairline, nothing raised and nothing recessed. It is defined by what it doesn’t do: the content paints no surface of its own, and the rail is left alone, keeping the card surface and edge hairline a Sidebar wears when it stands on its own. A rail in a plain shell and a rail with no shell look identical.docked — the same shell, dressed. (Default.) The shell turns into a black bg-canvas frame with the rail sitting on it; the content is a sheet set into that frame, a narrow gutter on the sides the rail doesn’t hold and every corner rounded. In a light theme the sheet is white in the black frame; in a dark theme frame and sheet are one tone, and a hairline ring draws the sheet’s edge.flat, the third, is a different job rather than a different look. Content sits flat on the page, the rail and a right-hand LayoutAside are divided from it by hairlines, and — the part that matters — the page scrolls as a whole: the content is not its own scroll container, which is what lets a window scroll-spy drive an “on this page” list. Documentation, not apps. This very site runs on it.
What the set deliberately does not contain is a second decorated app shell, say a flush Linear-style sheet beside the framed one. Undressed versus dressed is a real axis; dressed one way versus dressed another is how a design system drifts.
The variants set how a shell is dressed. The structure is which parts you drop in, and there is no prop for it: put a LayoutTopbar first and the shell becomes a column with the band on top; put a LayoutRail before the rail and it becomes two tiers; put LayoutPanes in the content and the sheet splits into a list and its detail. The chrome always sits on the frame and the sheet keeps a gutter on every side the chrome doesn’t hold, so every arrangement below reads as one app rather than a stack of boxes.
Layout is a flex row on the black bg-canvas frame. LayoutContent is the sheet: a surface set into the frame, held off the top, right, and bottom window edges by an 8px gutter, every corner rounded. LayoutHeader, first in the sheet, is its bar, and LayoutContainer centers the column under it.
Space is distributed across four nested bands:
bg-canvas floor the w-64 (256px) rail sits on. It is black in the light themes and the theme’s own ground in the dark ones, and the rail column pins itself .dark, so its labels, chips and hairlines take their dark values on a light page with no hand-picked colours. It reads as one black surface: the rail’s header and footer drop their rules, and spacing alone sets the switchers off from the nav.bg-card surface in a light theme (white in the black frame) and the frame’s own tone in a dark one, where a second, lighter grey read as muddy. An 8px gutter of frame (the rail’s own padding, so the frame reads one width all round) on every side the chrome doesn’t hold, and rounded-lg on all four corners: with the frame on every side, no corner meets the window wall. No shadow; in the dark themes a hairline ring is the whole edge. Below lg the frame goes and the sheet fills the phone. Nest surfaces inside with a smaller, concentric radius (the sheet’s radius − padding).LayoutHeader across the top of the sheet, its rule running edge to edge. It is as tall as the rail’s switcher row (44px compact, 56px comfortable), so the two share a line across the gutter.LayoutContainer centers a max-width column (mx-auto) and sets the content padding. Horizontal padding is responsive: it steps up at sm and lg so content breathes on wider viewports.LayoutContainer takes a width: narrow (max-w-3xl), default (max-w-6xl), wide (max-w-7xl), or full. These map to Tailwind’s native max-w-* scale: use narrow (768px) for single-column forms and reading, default (1152px) for standard dashboards and two-column settings, wide (1280px) for dense tables and grids, and full for edge-to-edge canvases.
Put LayoutHeader straight inside LayoutContent, before the column, and it becomes the sheet’s bar: the rail toggle, the breadcrumbs, and anything you push right with ml-auto. It spans the sheet rather than the column, so its rule runs edge to edge however wide the screen, and the toggle sits right beside the rail it folds. It pins to the top of the sheet as the page scrolls under it, with a translucent, blurred fill (bg-card/85 + backdrop-blur-sm), and it is exactly as tall as the rail’s switcher row, so the two line up across the gutter.
Global tools (search, notifications) belong beside the workspace switcher, in a SidebarActions; the bar keeps what is about this page. Below lg, under a LayoutMobileBar, it scrolls away with the page instead of pinning a second band on a phone. Inside LayoutContainer the same part is a plain row at the top of the column instead (pass sticky to pin it), for reading layouts that have no rail to line up with.
PageHeader is the title band that opens the column, under the sheet’s bar. The heading and its supporting text go in PageHeaderContent; the trailing PageHeaderActions holds page-level triggers (an outline secondary plus a primary). It stacks on phones and splits into a row at sm, so the actions never crowd a long title.
The rail needs no configuration: nest a Sidebar inside LayoutSidebar and it comes out docked, sitting bare on the frame beside the sheet instead of painting a second card on top of it. The column owns the surface, the width, and (in the flat shell) the dividing hairline; the rail owns its own chrome and padding. That split is what keeps the app shell free of bg-transparent / border-r-0 patches at the call site.
It travels: LayoutMobileSidebar publishes the same contract, so the one rail reads correctly in the drawer too. A rail that genuinely wants its own surface opts out with docked={false}, or takes the floating card treatment shown under Resizable panels.
{/* Before: the shell's look, faked at the call site */}
<LayoutSidebar className="p-0">
<Sidebar className="w-full border-r-0 bg-transparent">…</Sidebar>
</LayoutSidebar>
{/* Now: the shell owns it */}
<LayoutSidebar>
<Sidebar>…</Sidebar>
</LayoutSidebar>The shell owns the rail’s collapse state, so a screen doesn’t have to wire it. Drop a LayoutSidebarTrigger at the start of the sheet’s bar and the rail folds to a 48px icon column and back; ⌘B (Ctrl+B on Windows and Linux) does the same from anywhere, and stands down while you’re typing in a field or an editor, where the chord means bold. Only the rail column narrows: the sheet stays set in its frame and simply gains the width.
It is uncontrolled by default. Pass defaultCollapsed for a different starting state, or collapsed + onCollapsedChange to drive it yourself and persist the choice per user. useLayoutSidebar() reads and flips the same state from any descendant, for a bespoke trigger. Give each SidebarItem a label so the icon rows keep an accessible name and a hover tooltip.
For an app with a handful of top-level sections, put the navigation in a band across the top instead of a rail. Drop a LayoutTopbar in as the first child and the shell turns into a column: the band spans the window, and the sheet fills the rest and scrolls on its own. The band hosts a Navbar the way LayoutSidebar hosts a Sidebar: the bar docks onto it, painting no fill and no bottom rule of its own, and its row runs the full width instead of the marketing column.
The band is part of the black frame, pinned dark like the rail, and the sheet starts right under it: no gutter on top, where the band holds the edge, and the frame on the other three sides. Below md the links fold into the Navbar’s own menu.
The band spans the window on the frame; the sheet starts right under it and scrolls on its own.
The band is a column, so a second row stacks under the first. Put both rows in one Navbar (one <header> landmark, two NavbarInners) with linkStyle="underline": the tab indicator lands right on the seam, so the current tab reads as the doorway into the sheet below it. The tab row never folds into a menu; on a phone it scrolls sideways.
Two rows in one band. The tab indicator sits on the seam, so the current tab reads as the doorway into the sheet below.
The Slack, YouTube and IDE shell: a band across the whole window for the brand, a global search and the account, with the rail and the sheet side by side underneath. Put the rail and the sheet in a LayoutBody, the row that fills whatever the band leaves. The rail stops being viewport-tall and simply stretches to that row.
Band and rail are one L of frame here, and the sheet sits in its corner: no gutter against either of them, the frame on the right and the bottom. The rail toggle moves up into the band, lined up with the rail’s icons, so it still reads as the rail’s own control.
The band runs over both columns. Band and rail make one L of frame, and the sheet sits in its corner.
When the app is several products in one (a mail, a calendar, a billing module), the rail splits in two. A LayoutRail strip on the far left switches between modules, and the LayoutSidebar beside it holds the open module’s own navigation. Put a plain Sidebar in the strip and it comes out as the 48px icon rail, since the strip hands it collapsed; give every row a label for its tooltip and accessible name. A hairline divides the two columns, because two columns on the same frame with no surface change between them would run together into one wide rail.
Pass collapsible="offcanvas" to the panel. The strip already is the icon column, so collapsing the panel slides it shut instead of folding it into a second strip. It slides out whole, labels and all, and leaves the tab order once it is gone.
Mail, chat and support queues are one screen split into columns: a list, the item you opened, sometimes an inspector beside it. Put LayoutPanes straight inside LayoutContent and the sheet lays them out as a row. Each pane scrolls on its own, and every pane after the first draws the hairline that divides it from the one before.
width is sm (256px), md (320px), lg (384px) or fill, the default, which takes whatever the fixed panes leave. Give exactly one pane in the row fill.LayoutPaneHeader is the bar across the top of a pane: the list’s title, the reading pane’s actions. Every pane header is the same height, so side by side their bottom rules meet in one straight line across the seams.A third pane on the right holds the details of the open item: the requester, the status, the fields an agent edits. It continues the same sheet, so it is just one more LayoutPane. Panes compose with any structure: here the queues ride in a top band, which leaves the sheet its full width for three columns. For panes the reader can drag wider, compose the same parts inside Resizable panels.
Lena Fischer 9:37 AM
Every time I open INV-2042 and click Download, the PDF comes back empty. I need it for our auditors today.
Mara Okonkwo 9:40 AM
Sorry about that, Lena. I've regenerated the file on our side. Could you try the link again and tell me if it opens?
Lena Fischer
lena@northwind.com
LayoutSidebar is hidden below lg. On small screens, put a LayoutMobileBar at the top of LayoutContent and drop a LayoutMobileSidebar inside it: a hamburger that opens the same Sidebar in a left Drawer, so one rail serves both layouts. The demo below is framed as a phone and forces the mobile bar on at every width.
Tap the menu to open navigation.
By default the rail is a constant (w-64). Compose the shell with Resizable to make it a drag instead: wrap the columns in a ResizablePanelGroup on a fixed-height shell (h-svh overflow-hidden), and each ResizablePanel takes over the width the recipe used to fix. The Layout parts go inside the panels unchanged; give the sheet’s panel flex so the sheet fills it inside its gutter.
Two rules carry across every arrangement below. Give every pane except one hard px bounds (minSize / maxSize): the unbounded one absorbs the difference, so nothing collapses into an unusable sliver at small window sizes. And the handle is the rail’s edge: a sheet in the panel after a handle drops its left gutter on its own and meets the handle directly, keeping the frame on the other three sides. Since the sheet’s edge already draws that seam, a handle on the frame paints no line of its own (bg-transparent, no grip): a hairline there would run through the gutters above and below the sheet. It still shows the resize cursor and lights up in the brand colour while you drag.
The one place a card floats in the docked shell. Pass floating to the Sidebar and it detaches into its own surface (outline, radius, shadow) on the frame, while the content stays the sheet, so the two read as distinct objects across the seam. The rail’s panel needs padding for that float to be visible: with none, the card butts against the window edge and there is nothing for it to float above.
The detail-view dashboard: a rail, the content, and a right-hand inspector, with a draggable seam between each pair. Each handle resizes only the two panes it sits between, so the three rebalance independently.
What makes this read correctly is that the two seams are not the same kind of edge, and treating them alike is the usual mistake:
bg-canvas frame and the content is the sheet. This is the shell’s real edge, so the sheet keeps its rounded corners here: it is a surface change.LayoutContent as a second resizable group: no radius, no shadow, no fill of its own. It is a division within one surface, not a boundary between two. Give it a card of its own and the screen suddenly reads as three floating objects instead of one app.Both outer panes are collapsible and bounded; the middle carries no px bounds, so it is the pane that absorbs whatever the other two give up.
SplitLayout is a second shell in this module for the full-viewport auth, onboarding, and marketing screens. It fills the viewport (min-h-svh) and splits into two columns at lg. One pane carries the content (a centered SplitPaneBody column); the other, SplitMedia, is a full-bleed image panel with an optional SplitMediaOverlay for a caption or testimonial. Below lg the grid collapses to a single column and the media pane drops away, so the form fills the screen on phones.
Fill in the details below to create your account.
Have an account already? Log in
Koala UI let us ship a polished product in days, not months.
Mara Okonkwo · Founder, Nimbus
Which side the media sits on is just DOM order. Put SplitMedia first for an image-left layout. The ratio prop divides the columns: even (the 50/50 default), start, or end to give the leading or trailing pane the larger 3:2 share. Here the media leads with start so the hero panel dominates.
Welcome back to your workspace.
Pick up right where you left off across every project.
Enter your credentials to access your account.
density on Layout flows through context to the rail padding, the column’s inner padding, and the header gap. compact is the default (app UI); comfortable is roomier. Either way the column’s horizontal padding is responsive (px-4 sm:px-6 lg:px-8 in compact), so the gutter grows with the viewport. Set it once here or for a whole subtree with DensityProvider. See Density.