Responsive navigation

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

• Define the current area's destinations in one model. Render the same links in the desktop sidebar and the mobile Sheet.
• The mobile Sheet matches the catalog's own bottom-sheet menu. It rises from the bottom edge, opens on the current destination, and ends with a full-width Close menu button within thumb reach.
• An open Sheet closes and moves focus on the same matchMedia condition as AppShell's 760px breakpoint.
• The catalog itself uses a global top rail and a collapsible contextual sidebar. Choose the structure that fits your product's screens.
• When an app has three to five main destinations, BottomNavigation keeps them on the bottom edge at the same breakpoint, one tap away, and the Sheet can hold the rest.
• The example reuses the App shell module. Turn on Long navigation labels or Read-only navigation to try them.

• Don't drop important destinations on narrow screens. Render them in the Sheet.
• Don't mix external links, account controls, or theme controls in with the destinations. When the phone header has no room for the account menu, put it in the menu's footer, apart from the list.
• Don't hide desktop links with CSS while focus stays on a link that has disappeared. Move focus to the mobile menu button.
• Don't add app-menu arrow-key rules to destinations. Keep them as native a elements.
• Don't treat the example's read-only checkbox as a permission check. It's a local display condition, and real permission checks happen on the server and in the product router.

Anatomy

Shared destination model → desktop nav(AppShell.Sidebar + ScrollArea) / mobile trigger → bottom Sheet(Header(Title, Description), Body(native nav links), Footer(Close menu)) → workspace heading

Keyboard and accessibility

• Tab reaches the menu button, and Enter or Space activates it. The mobile Sheet opens with focus on the current destination.
• Choosing a destination moves focus to the content heading.
• Base UI manages focus trapping and Escape. Canceling returns focus to the menu button.
• Widening to desktop with the Sheet open moves focus to the current desktop link. Narrowing to mobile while a desktop link has focus moves focus to the mobile menu button.
• The mobile Sheet has a meaningful title and description. Long names keep their full accessible name when visually truncated.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { AppShell, Sheet, Button, ScrollArea } from '@surflane/ui'

const navigation = destinations
  .filter(canAccess)
  .map((item) => (
    <AppShell.Link
      key={item.id}
      href={item.href}
      label={item.label}
      icon={item.icon}
      aria-current={isCurrent(item) ? 'page' : undefined}
    />
  ))

<AppShell.Sidebar>
  <ScrollArea orientation='vertical' label='Destinations'>
    <nav aria-label='Workspace navigation'>{navigation}</nav>
  </ScrollArea>
</AppShell.Sidebar>

<Sheet.Root side='bottom' open={open} onOpenChange={setOpen}>
  <Sheet.Trigger render={<Button aria-label='Open navigation' />}>
    Menu
  </Sheet.Trigger>
  <Sheet.Content initialFocus={currentLink} finalFocus={resolveReturnFocus}>
    <Sheet.Header>
      <Sheet.Title>Workspace navigation</Sheet.Title>
      <Sheet.Description>Choose a workspace page.</Sheet.Description>
    </Sheet.Header>
    <Sheet.Body>
      <nav aria-label='Mobile workspace navigation'>{navigation}</nav>
    </Sheet.Body>
    <Sheet.Footer>
      <Button variant='secondary' onClick={() => setOpen(false)}>
        Close menu
      </Button>
    </Sheet.Footer>
  </Sheet.Content>
</Sheet.Root>

// Match AppShell's <=760px CSS breakpoint. Close the Sheet on desktop resize.
// Resolve return focus: cancel -> trigger; navigation -> heading; desktop resize -> current link.
// Revalidate routes and permissions in the product, including browser back/forward.

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens