flow-stack

Stack-based navigation for React — designed to live inside a container, not own the page.

What it is

flow-stack is a React library for push/pop navigation inside an existing UI container — a sidebar, a sheet, a modal, an expandable panel, or any fixed-size region. It manages the entry stack, animated scene transitions, and route params, while leaving layout, sizing, and the outer shell entirely up to you.

Why it exists

Most React navigation libraries assume they own the URL or the full viewport. flow-stack makes no such assumption. It is headless by default: bring your own container, mount it wherever you need it, and use as many independent stacks on one screen as you like.

Key features

• Push / pop / replace / reset — full navigation action set with direction awareness
• Param-driven screens — typed params per route, with optional defaults
• Route guards — async canEnter / canLeave per route; return false (or a rejected promise) to block any navigation action
• Animated transitions — 8 built-in presets, fully customisable via translate, opacity, scale, easing, enterCurve, exitCurve, stagger
• Priority-aware transition resolution — stack → route → action, with timing and style merged independently so duration set at the stack level survives a string preset at the route level
• Reduced motion — reducedMotion prop on the provider; respects prefers-reduced-motion by default
• Multiple independent stacks — mount as many NavigationStackProvider instances as you need; each is fully isolated and identified by its id
• Controlled and uncontrolled — manage state externally or let the library own it
• Headless controller — use createNavigationStackController outside React for testing or state-machine integration
• Accessibility — focus management and ARIA live regions out of the box

Installation

npm install flow-stack

Requires React and react-dom ≥ 18.

Quick start

import {
  NavigationStackProvider,
  NavigationStackScreen,
  NavigationStackViewport,
  useNavigationStack,
} from 'flow-stack';

function HomeScreen() {
  const nav = useNavigationStack();
  return <button onClick={() => nav.push('details', { id: '1' })}>Open</button>;
}

function DetailsScreen({ params }) {
  const nav = useNavigationStack();
  return (
    <div>
      <p>ID: {params.id}</p>
      <button onClick={() => nav.pop()}>Back</button>
    </div>
  );
}

export function App() {
  return (
    <div style={{ width: 360, height: 600 }}>
      <NavigationStackProvider id="main" initialRoute={{ name: 'home' }}>
        <NavigationStackScreen name="home" component={HomeScreen} />
        <NavigationStackScreen name="details" component={DetailsScreen} />
        <NavigationStackViewport />
      </NavigationStackProvider>
    </div>
  );
}

Core concepts at a glance

Concept	Description
Provider	Owns the stack state. One per independent navigation context.
Screen	Declares a named route and its component.
Viewport	Renders the visible scenes and runs transitions. Separate from the provider so you can position it freely.
Scene	Individual scene container rendered by the viewport. Exposed for custom renderScene implementations.
Controller	The headless state machine. The provider wraps one internally; you can also create one directly.
useNavigationStack	Hook that gives any component inside the provider access to push, pop, replace, reset, and the current state.

Transitions are resolved in priority order: action options → route-level transition → stack-level transition → built-in fallback. Timing fields (duration, easing, enterCurve, exitCurve, stagger) and style fields (preset, translate, opacity, scale) are merged independently so you can mix a string preset at the route level with a custom duration at the stack level.

Examples

Examples coming soon. In the meantime, see the Quick start above or browse the source on GitHub.

Docs

Deeper documentation (transitions, controlled mode, accessibility, headless controller) is in progress. Questions and requests are welcome on the GitHub issues page.

API summary

Components

Name	Purpose
NavigationStackProvider	Stack state, route registry, transition resolution
NavigationStackViewport	Scene renderer and animator
NavigationStackScreen	Declarative route definition (child of provider)
NavigationStackScene	Scene container element; used when implementing a custom renderScene callback

Hooks

Name	Returns
useNavigationStack	Full controller — push, pop, replace, reset, setParams, state, and more
useNavigationEntry	Active entry snapshot — entry, routeName, params, entryKey, index, isRoot
useNavigationTransitions	Live transition state — phase, direction, anchor, isReducedMotion

Headless

Name	Purpose
createNavigationStackController	Framework-independent navigation controller

Stability

Pre-release (0.x). The public API is still evolving. Breaking changes may occur before 1.0.0. Feedback on the API surface is welcome.

Contributing

Please see the CONTRIBUTING.md file for information on how to contribute to this repository.

License

This repository is licensed under the MIT License.