AppShell

Layout structure

Visual map of where each subcomponent lives in the viewport.

Full layout

import { AppShell, Burger, ScrollArea } from '@davaux/ui'

<AppShell
  header={{ height: 56 }}
  navbar={{ width: 260, breakpoint: 'md', burgerId: 'my-burger' }}
  aside={{ width: 200 }}
  footer={{ height: 40 }}
  withBorder
>
  <AppShell.Header>
    <Burger id="my-burger" />
    <span>My App</span>
  </AppShell.Header>

  <AppShell.Navbar>
    <ScrollArea style="flex:1;min-height:0">
      {/* nav links */}
    </ScrollArea>
  </AppShell.Navbar>

  <AppShell.Main>
    {/* page content */}
  </AppShell.Main>

  <AppShell.Aside>
    {/* aside content */}
  </AppShell.Aside>

  <AppShell.Footer>
    <span>© 2025</span>
  </AppShell.Footer>
</AppShell>

Navbar only

Omit any subcomponent you don't need. Here footer and aside are omitted.

<AppShell
  header={{ height: 56 }}
  navbar={{ width: 260, breakpoint: 'sm' }}
  withBorder
>
  <AppShell.Header>...</AppShell.Header>
  <AppShell.Navbar>...</AppShell.Navbar>
  <AppShell.Main>...</AppShell.Main>
</AppShell>

Alt layout

layout="alt" makes the navbar and aside span the full viewport height instead of sitting between the header and footer.

<AppShell layout="alt" navbar={{ width: 260 }} header={{ height: 56 }}>
  ...
</AppShell>

Mobile navbar with Burger

Set navbar.breakpoint to a size token. Below that viewport width the navbar becomes a slide-in overlay. Wire a Burger by passing its id to navbar.burgerId — the AppShell's inline script connects them automatically.

<AppShell
  navbar={{ width: 260, breakpoint: 'md', burgerId: 'nav-burger' }}
  header={{ height: 56 }}
>
  <AppShell.Header>
    {/* Burger is hidden on desktop via CSS, visible below the breakpoint */}
    <Burger id="nav-burger" aria-label="Toggle navigation" />
    <span>My App</span>
  </AppShell.Header>
  <AppShell.Navbar>...</AppShell.Navbar>
  <AppShell.Main>...</AppShell.Main>
</AppShell>

Collapsed desktop navbar

Pass collapsed.desktop: true to start with the navbar hidden on desktop. The inline script and burger button toggle it open/closed.

<AppShell
  navbar={{
    width: 260,
    breakpoint: 'md',
    burgerId: 'nav-burger',
    collapsed: { desktop: true },
  }}
  header={{ height: 56 }}
>
  ...
</AppShell>

AppShell.Section

Use AppShell.Section inside AppShell.Navbar or AppShell.Aside to divide the sidebar into fixed-height and scrollable regions. Sections support Style Props, so padding can be applied with shorthand props like p="md".

<AppShell.Navbar>
  {/* Fixed top area — e.g. a search input */}
  <AppShell.Section style="padding: var(--dv-spacing-md)">
    <input placeholder="Search..." />
  </AppShell.Section>

  {/* Scrollable nav links — grows to fill remaining space */}
  <AppShell.Section grow>
    <ScrollArea style="height:100%">
      <nav>{/* links */}</nav>
    </ScrollArea>
  </AppShell.Section>

  {/* Fixed bottom area — e.g. user profile */}
  <AppShell.Section style="padding: var(--dv-spacing-md)">
    <UserProfile />
  </AppShell.Section>
</AppShell.Navbar>

Scrollable navbar / aside

Add scrollable to AppShell.Navbar or AppShell.Aside to automatically wrap the children in a ScrollArea that fills the available height. Use this when the sidebar has a single scrollable region. For the fixed-header + scrollable-middle + fixed-footer pattern, leave scrollable unset and compose with AppShell.Section and ScrollArea manually.

{/* Simple — single scrollable region */}
<AppShell.Navbar scrollable>
  <nav>{/* links */}</nav>
</AppShell.Navbar>

{/* Flexible — fixed top/bottom, scrollable middle */}
<AppShell.Navbar>
  <AppShell.Section p="md">
    <input placeholder="Search..." />
  </AppShell.Section>
  <AppShell.Section grow>
    <ScrollArea style="height:100%">
      <nav>{/* links */}</nav>
    </ScrollArea>
  </AppShell.Section>
  <AppShell.Section p="md">
    <UserProfile />
  </AppShell.Section>
</AppShell.Navbar>

Non-sticky footer

By default AppShell.Footer renders in document flow below Main and scrolls with the page — no footer config needed on AppShell. Add sticky to fix it to the bottom of the viewport instead; in that case also pass footer={ height } so Main and the Navbar reserve the correct space.

{/* Non-sticky footer (default) — no footer config needed */}
<AppShell ...>
  <AppShell.Main>...</AppShell.Main>
  <AppShell.Footer>
    <span>© 2025</span>
  </AppShell.Footer>
</AppShell>

{/* Sticky footer — reserve height in the AppShell config */}
<AppShell footer={{ height: 40 }} ...>
  <AppShell.Footer sticky>
    <span>© 2025</span>
  </AppShell.Footer>
</AppShell>

Surface elevation

Each subcomponent accepts a surface prop (0–5) that maps to the global --dv-surface-N CSS token. The defaults reflect a natural depth hierarchy — Main sits at surface 0 (page canvas), Navbar and Aside at 1 (raised panel), and Header and Footer at 2. Override any part to shift it up or down the elevation scale.

{/* Raise the navbar one level above default */}
<AppShell.Navbar surface={2}>...</AppShell.Navbar>

{/* Drop the header to match the navbar */}
<AppShell.Header surface={1}>...</AppShell.Header>

Responsive padding

Pass a breakpoint object to padding to use different spacing at different viewport widths. Keys follow the same size tokens as breakpoint — unspecified breakpoints inherit from the nearest smaller one.

<AppShell padding={{ base: 'sm', md: 'xl' }} ...>
  ...
</AppShell>

Custom transition

The navbar and aside slide-in animation defaults to 250ms. Pass transitionDuration to speed it up, slow it down, or set it to 0 to disable it.

<AppShell transitionDuration={400} ...>
  ...
</AppShell>

Custom Main element

AppShell.Main renders as <main> by default. Pass component to change the element — useful when <main> is used elsewhere on the page.

<AppShell.Main component="div">
  {/* page content */}
</AppShell.Main>

Burger button

The Burger component is a standalone button — see the Burger docs for its own props. AppShell does not manage its opened state: the inline script on the shell root handles all toggling by reading and writing data-navbar-opened / data-aside-opened attributes directly on the shell element.