App shell

01Preview

A real AppShell in a fixed-height frame, so it doesn't take over this page. Change the frame width to see the layout switch: the shell measures its own width, not the window's. Collapse the sidebar with its toggle or the control.

import {
  AppShell, Sidebar, SidebarSection, SidebarItem, SidebarFooter, TopBar, TopBarSearch,
  BottomNav, BottomNavItem, Button, DropdownMenuItem,
} from '@nuton/ui'

<AppShell
  sidebar={
    <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed} logo={<Logo />}
      footer={
        <SidebarFooter name="Ada Obi" email="ada@example.com" plan="PRO">
          <DropdownMenuItem>Settings</DropdownMenuItem>
          <DropdownMenuItem>Sign out</DropdownMenuItem>
        </SidebarFooter>
      }
    >
      <SidebarSection>
        <SidebarItem intent="primary" icon={<RiAddLine />} shortcut="⌘N" onClick={startNew}>Start New</SidebarItem>
        <SidebarItem href="/library" icon={<RiBookOpenLine />} active>Library</SidebarItem>
        <SidebarItem href="/spaces" icon={<RiStackLine />}>Spaces</SidebarItem>
      </SidebarSection>
      <SidebarSection label="Recents">
        <SidebarItem kind="entry" href="/lessons/cell-biology">Cell biology basics</SidebarItem>
      </SidebarSection>
    </Sidebar>
  }
  topBar={
    <TopBar
      start={<TopBarSearch onClick={openSearch} />}
      end={<><Button appearance="stroke">Help</Button></>}
    />
  }
  bottomNav={
    <BottomNav>
      <BottomNavItem icon={<RiAddLine />} onClick={startNew}>New</BottomNavItem>
      <BottomNavItem href="/library" icon={<RiBookOpenLine />} active>Library</BottomNavItem>
      <BottomNavItem href="/spaces" icon={<RiStackLine />}>Spaces</BottomNavItem>
      <BottomNavItem href="/profile" icon={<RiUser3Line />}>Profile</BottomNavItem>
    </BottomNav>
  }
>
  <LibraryPage />
</AppShell>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. Navigation icons come from @remixicon/react (Remix Icon is Nuton's icon set, D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

The shell uses CSS container queries for its phone layout, supported by every current browser. The sidebar uses Tooltip and the profile menu uses DropdownMenu; both ship in the same stylesheet. Apps supply the logo: @nuton/ui ships no brand assets (D12).

03Usage

import {
  AppShell, Sidebar, SidebarSection, SidebarItem, SidebarFooter, TopBar, TopBarSearch,
  BottomNav, BottomNavItem, Button, DropdownMenuItem,
} from '@nuton/ui'
import { RiAddLine, RiBookOpenLine, RiStackLine, RiUser3Line } from '@remixicon/react'

export function LearnerLayout({ children }: { children: React.ReactNode }) {
  const [collapsed, setCollapsed] = useState(false)
  return (
    <AppShell
      sidebar={
        <Sidebar
          collapsed={collapsed}
          onCollapsedChange={setCollapsed}
          logo={<a href="/" aria-label="Nuton home"><Logo /></a>}
          footer={
            <SidebarFooter name={user.name} email={user.email} plan="PRO">
              <DropdownMenuItem onSelect={openSettings}>Settings</DropdownMenuItem>
              <DropdownMenuItem onSelect={signOut}>Sign out</DropdownMenuItem>
            </SidebarFooter>
          }
        >
          <SidebarSection>
            <SidebarItem intent="primary" icon={<RiAddLine />} shortcut="⌘N" aria-keyshortcuts="Meta+N" onClick={startNew}>
              Start New
            </SidebarItem>
            <SidebarItem as={Link} href="/library" icon={<RiBookOpenLine />} active={path === '/library'}>Library</SidebarItem>
            <SidebarItem as={Link} href="/spaces" icon={<RiStackLine />} active={path === '/spaces'}>Spaces</SidebarItem>
          </SidebarSection>
          <SidebarSection label="Recents">
            {recents.map((l) => (
              <SidebarItem key={l.id} kind="entry" as={Link} href={l.href} active={path === l.href}>{l.title}</SidebarItem>
            ))}
          </SidebarSection>
        </Sidebar>
      }
      topBar={<TopBar start={<TopBarSearch onClick={openSearch} />} end={<Button appearance="stroke">Help</Button>} />}
      bottomNav={
        <BottomNav>
          <BottomNavItem icon={<RiAddLine />} onClick={startNew}>New</BottomNavItem>
          <BottomNavItem as={Link} href="/library" icon={<RiBookOpenLine />} active={path === '/library'}>Library</BottomNavItem>
          <BottomNavItem as={Link} href="/spaces" icon={<RiStackLine />} active={path === '/spaces'}>Spaces</BottomNavItem>
          <BottomNavItem as={Link} href="/profile" icon={<RiUser3Line />} active={path === '/profile'}>Profile</BottomNavItem>
        </BottomNav>
      }
    >
      {children}
    </AppShell>
  )
}

• Render one AppShell around every page. It adds the skip link, the <main> landmark and the layout switch.
• Mark the current page with active on its SidebarItem and BottomNavItem. It sets aria-current="page".
• Give every SidebarItem an icon: the collapsed rail shows only icons, with the label as a tooltip.
• Pass your router's link with as (it must forward its ref). Items without href render buttons.
• Store the collapsed state (for example in local storage) and pass it back with collapsed.

04Variants and sizes

The shell has two desktop sidebar states and a phone layout. Each example below is a scaled-down shell in a 540px frame.

Expanded sidebar

<AppShell layout="desktop" sidebar={<Sidebar …>…</Sidebar>} topBar={…}>…</AppShell>

Collapsed rail

Labelled sections (Pinned, Recents) leave the rail, as in Figma. Labels stay as accessible names and appear as tooltips on hover and focus.

<Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed} …>…</Sidebar>

Phone layout

Below 768px of the shell's own width, the sidebar hides and the tab bar appears. Force a layout with layout="desktop" or "phone".

<AppShell bottomNav={<BottomNav>…</BottomNav>} …>…</AppShell>

Phone drawer

Set phoneNav="drawer" to give phones a menu instead of a tab bar, the way chat apps do. The sidebar leaves the page and slides in from the start edge, always in its full form, with a close button, and pushes the page aside by its width (the page moves, it is not resized; they travel together). A light scrim over the part of the page still in view closes it. Put an AppShellMenuButton in the top bar's start slot: it renders nothing outside the phone layout, so the same top bar works on desktop. Choosing a page, pressing Escape or tapping the scrim closes the drawer and returns focus to the menu button; the page behind it is inert while it is open. It follows the reading direction (it opens from the right in right-to-left). The drawer is positioned inside the shell, so use it with scroll="contained", and leave out bottomNav.

<AppShell phoneNav="drawer" scroll="contained" sidebar={<Sidebar …>…</Sidebar>} topBar={<TopBar start={<><AppShellMenuButton /><TopBarSearch /></>} />}>…</AppShell>

Sizes

Values from the component CSS, which follows the Figma geometry read on 2026-10-14.

05States and interactions

06Composition examples

Course page with a panel

Course pages add a Share action to the top bar and a right panel for lesson tools. The panel is an <aside> named by labels.panel.

<AppShell
  panel={<LessonTools />}
  labels={{ panel: 'Lesson tools' }}
  topBar={<TopBar start={<TopBarSearch />} end={<><Button appearance="stroke" leadingIcon={<RiShareLine />}>Share</Button><Button appearance="stroke">Help</Button></>} />}
  …
>

Top bar on its own

The top bar has a start slot (search), an optional middle slot (a mode toggle) and an end slot (actions). Icon-only actions use TopBarButton, which takes a required label.

<TopBar
  start={<TopBarSearch onClick={openSearch} />}
  end={
    <>
      <TopBarButton label="Notifications" icon={<RiNotification3Line />} aria-pressed={open} onClick={toggle} />
      <Button appearance="stroke" leadingIcon={<RiShareLine />}>Share</Button>
      <Button appearance="stroke">Help</Button>
    </>
  }
/>

Inside another page

Previews like the ones on this page sit inside the docs' own <main>. Pass landmarks={false} so the shell doesn't nest a second main, and scroll="contained" with --nu-app-shell-height to fix its height.

07API reference

AppShell props

Sidebar props

AppShellMenuButton props

SidebarSection props

SidebarItem props

SidebarFooter props

TopBar, TopBarSearch and TopBarButton props

BottomNav and BottomNavItem props

Styling hooks

Root classes: .nu-app-shell (data-layout, data-scroll), .nu-sidebar (data-collapsed), .nu-sidebar-item (data-kind, data-intent, data-active), .nu-topbar, .nu-bottom-nav. Override points: --nu-app-shell-height, --nu-app-shell-panel-width, --nu-sidebar-width, --nu-sidebar-rail-width, --nu-topbar-height, --nu-topbar-height-phone, --nu-bottom-nav-item-height.

Accessibility

You must: name a linked logo; give every item an icon and a text label; mark the current page with active; wire any shortcut you show and set aria-keyshortcuts; keep the tab bar to 3–5 items.

Figma mapping

08Guidelines and related components

Do and don't

Common mistakes

• Forgetting active, so nothing marks the current page.
• Passing a router link to as that doesn't forward its ref, which breaks the rail tooltip.
• Putting a menu button inside an item's link. Use action, which renders outside it.
• Rendering the shell inside another page's <main> without landmarks={false}.

Related components

• TooltipLabels in the collapsed rail and on icon buttons.
• Dropdown menuThe account menu in the sidebar footer.
• AvatarThe profile picture or initials.
• BadgeThe plan badge.
• TabsNavigation within a page.