Skip to content

README.md

Latest commit

 

History

History
194 lines (156 loc) · 5.09 KB

README.md

File metadata and controls

194 lines (156 loc) · 5.09 KB

🧩 Stack Flow

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

npm version npm downloads license GitHub stars

✨ 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