StackNavigator

Preview

Installation

pnpm dlx shadcn@latest add https://pwaui.com/r/stack-navigator.json

Usage

"use client"
import * as React from "react"import { NavigationBar } from "@/components/ui/navigation-bar"import { StackNavigator, useStackNavigator } from "@/components/ui/stack-navigator"
function ProjectDetail() {  const { pop } = useStackNavigator()
  return (    <>      <NavigationBar>        <NavigationBar.Leading>          <NavigationBar.BackButton data-autofocus onClick={pop} />        </NavigationBar.Leading>        <NavigationBar.Title>Project</NavigationBar.Title>      </NavigationBar>      <main>Project detail</main>    </>  )}
export function ProjectStack() {  const [detailOpen, setDetailOpen] = React.useState(false)  const entries = [    { key: "projects", label: "Projects", content: <button onClick={() => setDetailOpen(true)}>Open project</button> },    ...(detailOpen ? [{ key: "project", label: "Project detail", content: <ProjectDetail /> }] : []),  ]
  return <StackNavigator backGesture="auto" entries={entries} onPop={() => setDetailOpen(false)} />}

Anatomy

Composition

See how PWAProvider, AppShell, SafeArea, NavigationBar, and TabBar divide viewport, scrolling, safe-area, and navigation responsibilities.

Read the app layout guide →

Behavior notes

• entries is the complete controlled stack. Append to push and remove from the end to pop; the component keeps no private navigation history.
• Covered views stay mounted but inert and aria-hidden, preserving uncontrolled input state and scroll without exposing hidden controls to keyboard or assistive-technology navigation.
• useStackNavigator exposes depth, canPop, and pop so a NavigationBar.BackButton inside the top entry can request onPop.
• backGesture defaults to auto: it enables only in standalone or fullscreen display mode. Use on only on a surface where you have verified that the browser or operating system does not own the leading edge; use off to disable it completely.
• backGestureEdgeWidth defaults to 24 pixels and backGestureThreshold defaults to half the stack width. Tracking publishes --pwa-stack-swipe-progress and data-back-gesture-state without rerendering React on pointer moves.
• onDepthChange can hide a persistent TabBar or update other shell chrome without querying the DOM.
• Keep stacks shallow enough that retaining covered DOM remains inexpensive. Each view owns its own scroll viewport.

Platform limitations

Transition support

Accessibility

Only the active view is reachable. Push focuses an autofocus target or the new view container; pop returns focus to the pointer or keyboard trigger when it remains mounted, otherwise to the revealed view.