react-screen-flow

A small, typed screen-flow engine for React apps with guarded next, prev, and goTo transitions.

Use it when navigation is driven by app state and business rules: onboarding, checkout, signup, profile completion, permission gates, or router-backed flows.

import { useScreenFlow, type FlowDefinition } from "@hbarkallah/react-screen-flow";

const screens = {
  login: LoginScreen,
  profile: ProfileScreen,
  dashboard: DashboardScreen,
};

const flow: FlowDefinition<AppState, typeof screens> = {
  screens,
  resolveStart: (state) => (state.user ? "dashboard" : "login"),
  transitions: {
    login: { next: "profile", canGoNext: (state) => Boolean(state.user) },
    profile: { next: "dashboard", prev: "login" },
    dashboard: {},
  },
};

function FlowView({ state }: { state: AppState }) {
  const flowState = useScreenFlow(flow, state, { autoNavigate: true });
  const ScreenComponent = flowState.ScreenComponent;

  return <ScreenComponent />;
}

Why Not Existing Tools?

• Use React Router or TanStack Router for URL routing, loaders, and layouts. Use react-screen-flow for typed business decisions about which screen is allowed.
• Use XState when you need a full state machine with events, nested states, and parallel states. Use react-screen-flow when your model is mostly screens, guards, and branching.
• Use simple wizard hooks for linear local steps. Use react-screen-flow when flow order depends on external app state, async guards, redirects, or router sync.

Features

• Typed screen IDs from your screens map.
• Branching next and prev targets.
• Sync and async transition guards.
• Blocked transition details and redirects.
• Loading strategies: deferred, optimistic, and block-ui.
• Lifecycle callbacks for analytics or app side effects.

Documentation

Full docs live in the VitePress site under apps/docs. From the repo root:

pnpm docs

• Getting Started
• Flow Engine — pure evaluation: guards, transitions, TransitionResult, and testing without React
• Runtime — useScreenFlow, applyTransitionResult, loading strategies, and lifecycle callbacks