# App Layout

The app shell: sticky navbar and sidebar over a scrolling page, aside, banner and footer, skip link, and a drawer below 64rem.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/app-layout
- Tier: Core and Pro

## Install

App Layout ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { AppLayout, AppLayoutAsideTrigger, AppLayoutNavigationTrigger, AppLayoutProps } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { AppLayout, AppLayoutNavigationTrigger, Navbar, Sidebar, SidebarItem, SidebarSection } from "@wunderui/react"
import { LayoutDashboard } from "lucide-react"

export function Shell({ children }: { children: React.ReactNode }) {
  return (
    <AppLayout
      navbar={<Navbar logo={<span className="flex items-center gap-2"><AppLayoutNavigationTrigger /><span className="text-sm font-semibold text-foreground">WunderUI</span></span>} />}
      sidebar={
        <Sidebar aria-label="Primary">
          <SidebarSection aria-label="Main">
            <SidebarItem icon={<LayoutDashboard />} label="Dashboard" href="/dashboard" active />
          </SidebarSection>
        </Sidebar>
      }
    >
      {children}
    </AppLayout>
  )
}
```

Expected result: You should see a top bar, a 256 px sidebar and the content beside it. Press Tab once for a Skip to content link; make the layout narrower than 64rem and the sidebar becomes a menu button.

## When to use

### Use App Layout for

- The frame of a signed-in product page: a sticky bar, a sidebar, the content and an optional detail panel
- A page that must work from 320 px up: the sidebar and the aside become drawers below a breakpoint
- Keyboard and screen reader basics for free: landmarks, a skip link and chrome that never covers a focused field

### Use something else

- [Navbar](https://wunderui.com/components/navbar) for the top bar alone, for a site without a sidebar
- [Sidebar](https://wunderui.com/components/sidebar) for the navigation column that goes into this layout
- [Sheet](https://wunderui.com/components/sheet) for a panel that opens over a page you build yourself

## Keyboard

The layout has no key handling of its own. The skip link, triggers and drawers are native links, buttons and a modal dialog, so the browser provides focus, activation and Escape.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves through the regions in the order of the document: the skip link, the banner, the bar, the sidebar, the content, the aside and the footer. Focus shows as an indigo border with a 2 px ring. |
| `Enter` | On the skip link: moves focus to the content, so the next Tab is the first control in it, and the bar is skipped. On the navigation or aside trigger: opens or toggles. |
| `Space` | On the navigation and aside triggers: the same as Enter. |
| `Esc` | In an open drawer: closes it and returns focus to the button that opened it. The aside pane has no Escape: it closes with its trigger. |

## Behavior

How the layout measures, scrolls and switches to drawers, and what it leaves to you.

- **Landmarks:** The bar is the banner landmark, sidebar sections are navs, the content is main, the aside is named by its label. Name every navigation: two unnamed ones are ambiguous.
- **Skip link:** Skip to content by default. It is hidden until focused, then appears at the top left; Enter focuses the content and scrolls it clear of the sticky bar, and an embedded layout has none.
- **Document scroll:** The default: the page scrolls while the bar, sidebar and aside stick. The panes scroll on their own, and anchors, printing and scroll restoration work as usual.
- **Pane scroll:** The layout is as tall as the viewport and only the content scrolls, without scroll chaining. For inboxes, editors, canvases and virtualised grids.
- **Chrome height:** The layout measures the banner and bar and keeps scroll padding clear of them, so an anchor or a focused field never ends up under the bar (WCAG 2.4.11). It restores everything on unmount.
- **Width:** Fluid is full width. Contained centres the content at 1280 px and steps up to 1620 px from a 110rem layout and 2160 px from 150rem, following the layout's own width.
- **Padding:** Comfortable is 24 px around the content, none is edge to edge. With none, give tables their own side padding.
- **Drawer:** Below the drawer breakpoint (40, 48 or 64rem, default 64rem) of the layout's own width, the sidebar and aside become modal drawers over the whole page and the navigation trigger appears.
- **Aside:** The pane is 320 px and open by default. Closed, it is inert and its width animates to 0; below the breakpoint it becomes a drawer, and the trigger checks what is on screen.
- **Container, not window:** The layout reads its own width. The Mobile width button of a preview narrows the card to 390 px and the layout switches to drawers as on a phone, and your own container queries inside it follow.
- **Hooks:** useAppLayout returns the controls of the surrounding layout, or null outside one. useRouteFocus returns a ref for the new view's heading and focuses it when its key changes, not on first render.

## Motion

The layout animates one thing: the aside pane. Every transition uses the motion tokens.

- **Aside pane:** The aside's width and opacity animate when it opens or closes, over the base duration.
- **Drawers:** Each Sheet slides in from its edge with a blur and a scrim, and leaves faster.
- **Everything else:** The layout itself does not move: the bar, the panes and the banner are laid out, not animated.
- **Reduced motion:** With reduced motion on, the global rule takes moving properties out of every transition: the aside's width changes at once and only its fade remains. The drawers keep their fade.

## Anatomy

- `AppLayout`: The shell: a flex column that fills the page, with banner, navbar, a three-column grid (sidebar, content, aside) and footer. It reacts to its own width, not the window's.
- `Banner`: A bar above everything for viewing as, offline or a trial notice. It sticks to the top in document scroll, and the layout measures its height.
- `Navbar`: Usually a Navbar. It must be a direct child of the layout so it can stick, and it sits below the banner.
- `Sidebar pane`: Primary navigation, sticky beside the content with its own scroll. Below the breakpoint it leaves the layout and opens in a left drawer.
- `Content`: The main landmark, which the skip link focuses, with 24 px of padding unless you turn it off. When embedded it is a plain div.
- `Aside`: A 320 px context panel on the right, named by its label. Closed, it is inert, shrinks to zero width and fades; below the breakpoint it opens in a right drawer.
- `Footer`: A footer (the contentinfo landmark) under the grid, with a top border.
- `Skip link`: The first element and the first Tab stop. It stays out of sight until focused, Enter moves focus to the content, and it is not rendered when embedded.
- `Navigation drawer`: A left Sheet with the sidebar, named Navigation, opened below the breakpoint. It is a modal dialog: focus moves in and stays, Escape closes it and focus returns to the trigger.
- `Aside drawer`: A right Sheet with the aside, named by its label, shown below the breakpoint. Closing it closes the aside.
- `AppLayoutNavigationTrigger`: An icon button that opens the navigation drawer. Visible only below the breakpoint, and renders nothing outside a layout.
- `AppLayoutAsideTrigger`: An icon button for the aside: it shows or hides the pane from the breakpoint up and opens the drawer below it. Its name follows the state: Close details, Open details.
- `Shell`

## Best practices

### When to use

- Use it as the frame of a signed-in product page: a bar, a sidebar, the content and an optional detail panel. For a single centred page, such as sign-in or a landing page, use a Navbar.

### Do

- Pass the bar as the navbar prop, not as a child. It must be a direct child to stick, and its height feeds the sticky sidebar and aside.
- Put the navigation trigger in the bar. Below the drawer breakpoint the sidebar leaves the page, and this button is the only way back to it.
- Use document scroll for ordinary pages: it keeps scroll restoration, anchors, printing and sticky content. Use pane scroll only for inboxes, editors and canvases that must fill the window.
- Always set the aside label when you pass an aside. The pane is a landmark and the drawer reuses the label as its title.
- Call useRouteFocus with the route and put its ref on the new view's heading, so focus lands there after a route change.
- Keep one logo on the screen: in the bar, next to the navigation trigger. A sidebar without a logo row is fine.

### Don't

- Don't add your own main element inside the children. The layout renders the main landmark; use embedded only for a demo inside another page, and expect no skip link there.
- Don't add sticky chrome of your own above the layout. Use the banner: its height is measured, so the bar, panes and anchors move with it.
- Don't read the window width to decide where the drawer starts. Set the drawer breakpoint: the layout measures itself.

## API reference

### AppLayout

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The content of the page, rendered inside `main`. |
| aside | React.ReactNode |  | A right-hand context panel for details, help or activity. A drawer below `drawerBelow`. |
| asideLabel | string | "Details" | The name of the aside landmark and the title of its drawer. `Details` by default. Required in practice: an unnamed aside loses its role. |
| asideOpen | boolean |  | Controls whether the aside is open. Uncontrolled, it starts open. |
| banner | React.ReactNode |  | A bar above everything, such as viewing as or offline. Its height is measured. |
| className | string |  | Extra classes for the layout root. |
| drawerBelow | "40rem" \| "48rem" \| "64rem" | "64rem" | The width of the layout below which the sidebar and the aside become drawers: `40rem`, `48rem` or `64rem` (default). |
| embedded | boolean | false | The layout is a demo inside another page: no skip link, and the content area is a `div` instead of a second `main`. `false` by default. |
| footer | React.ReactNode |  | A `<footer>` under the grid with a top border. |
| navbar | React.ReactNode |  | The top bar, usually a Navbar. Rendered as a direct child so it can stick. |
| onAsideOpenChange | (open: boolean) => void |  | Called with the new state when the aside opens or closes. |
| padding | "comfortable" \| "none" | "comfortable" | `comfortable` (default) is 24 px around the content; `none` is edge to edge. |
| scroll | "document" \| "pane" | "document" | `document` (default): the page scrolls and the chrome sticks. `pane`: the layout fills the viewport and only the content scrolls. |
| sidebar | React.ReactNode |  | Primary navigation, usually a Sidebar. A drawer below `drawerBelow`. |
| skipLinkLabel | string | "Skip to content" | The text of the skip link, the first Tab stop. `Skip to content` by default. |
| width | "fluid" \| "contained" | "fluid" | `fluid` (default) or `contained`: the content centres and steps 1280, 1620, 2160 px with the layout's width. |

### AppLayoutAsideTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the button. |
| label | string | "Details" | The noun in the accessible name: `Close details` or `Open details` for the default. `Details` by default. |

### AppLayoutNavigationTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the button. |
| label | string | "Open navigation" | The accessible name of the button. `Open navigation` by default. |

## Examples

### Regions: a banner, a footer, the landmarks

### Width: fluid, contained, edge to edge

### Drawer below: 40rem, 48rem or 64rem

## In context

### Workspace shell: pages, route focus and an aside

The sidebar changes the page and the route focus hook moves focus to the new heading, so a screen reader starts at the new view. The bar's panel button opens the aside, a drawer below the breakpoint.

### Impersonation banner above the bar

A banner above everything, such as viewing as, offline or a trial notice. Its height is measured, so the sticky bar sits below it and anchors land clear of both, and closing it moves everything up.

### Inbox: pane scroll

Pane scroll fills the window and only the content scrolls: the list and the message scroll on their own, and the bar and sidebar never move. Use it for inboxes, editors and canvases.

### Table: edge to edge

No padding removes the 24 px around the content, so the table runs to the edges. Give the first and last cells their own side padding.

## For AI agents

`get_component("app-layout")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
