🧩 Stack Flow

Simple animated page transitions for React apps. Stack-based navigation. Zero complexity. Smooth animations.

✨ Features

• 🚀 Simple API – Just a few lines of code, no boilerplate
• 🎨 Custom animations – Per‑component enter/exit animations
• ↩️ Stack navigation – Back button works automatically
• 🔗 Link component – Like React Router, but with smooth transitions
• ⚡ Lightweight – Only ~8KB, zero extra dependencies
• 🔧 No router required – Works independently, no React Router needed
• 📦 TypeScript ready – Full type definitions included

📦 Installation

npm install react-stack-flow

🚀 Quick Start

import { StackFlow, useFlow, Link } from 'react-stack-flow';

function HomePage() {
  return (
    <div>
      <h1>🏠 Home</h1>
      <Link to="about" className="btn">Go to About →</Link>
    </div>
  );
}

function AboutPage() {
  const { goBack } = useFlow();
  return (
    <div>
      <h1>📖 About</h1>
      <button onClick={goBack}>← Back</button>
    </div>
  );
}

function App() {
  return (
    <StackFlow
      initialPage="home"
      duration={400}
      pages={{
        home: { components: [{ component: HomePage }] },
        about: { components: [{ component: AboutPage }] }
      }}
    />
  );
}

export default App;

📖 API

StackFlow Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | initialPage | string | required | First page to display | | pages | object | required | Page configuration object | | duration | number | 400 | Animation duration (ms) | | onPageChange | (page: string) => void | optional | Callback when page changes |

useFlow Hook

| Method / Property | Description | |------------------|-------------| | goTo(page, params) | Navigate to target page, optionally pass params | | goBack() | Go back to previous page | | canGoBack | boolean – whether back navigation is possible | | currentPage | string – current page name | | params | object – parameters passed to current page |

Link Component

| Prop | Type | Default | Description | |------|------|---------|-------------| | to | string | required | Target page name | | params | object | optional | Parameters to pass | | className | string | optional | Custom CSS class | | onClick | () => void | optional | Click handler |

<Link to="product" params={{ id: 123 }}>
  View Product
</Link>

🎨 Custom Animations

Each component can have its own enter/exit animation:

pages={{
  home: {
    components: [
      { component: Header, exitAnimation: 'fadeOut', enterAnimation: 'fadeIn' },
      { component: HomePage, exitAnimation: 'slideOutLeft', enterAnimation: 'slideInRight' },
      { component: Footer, exitAnimation: 'fadeOut', enterAnimation: 'fadeIn' }
    ]
  }
}}

Available animations:
fadeIn / fadeOut • slideInLeft / slideOutLeft • slideInRight / slideOutRight
slideInUp / slideOutUp • slideInDown / slideOutDown • zoomIn / zoomOut

💡 Real‑world Example – Starbucks‑style App

<StackFlow initialPage="home" duration={400} pages={{
  home: {
    components: [
      { component: Header },
      { component: HomePage },
      { component: Footer }
    ]
  },
  menu: {
    components: [
      { component: Header },
      { component: MenuPage },
      { component: Footer }
    ]
  },
  product: {
    components: [
      { component: Header },
      { component: ProductDetail },
      { component: Footer }
    ]
  }
}} />

See the full Starbucks demo in the GitHub repo.

🎬 Video Tutorial

Watch the complete guide on YouTube:

Channel: Hamidev – React, animations and frontend development tutorials. https://www.youtube.com/@Hamidevelop

🧩 Why Stack Flow?

| Feature | Stack Flow | React Router | Framer Motion | |---------|------------|--------------|---------------| | Animated page transitions | ✅ Built‑in | ❌ Manual | ⚠️ Partial | | Stack navigation (back button) | ✅ Automatic | ✅ Yes | ❌ No | | Link component | ✅ Yes | ✅ Yes | ❌ No | | Bundle size | ~8KB | ~10KB | ~50KB | | React Router required | ❌ No | ✅ Yes | ❌ No | | Learning curve | Very low | Medium | High |

📄 License

MIT © Hamidreza Norouzi

🔗 Links

GitHub Repository: https://github.com/hnorouzi/react-stack-flow npm Package: https://www.npmjs.com/package/react-stack-flow YouTube Channel – Hamidev: https://www.youtube.com/@Hamidevelop Report an Issue: https://github.com/hnorouzi/react-stack-flow/issues

Made with ❤️ by Hamidreza Norouzi – GitHub | YouTube