⚠️ Notice: Project Temporarily Pended & Unstable

Thank you for checking out Z-Proximity-Engine!

Please note that this project is currently on hold and is not in a stable state (specifically the scroll-related features in the latest v2 commits).

I am currently focusing my time on learning computer science fundamentals and low-level software engineering. Because of this, this repository will not be actively maintained or updated for a short while.

• You are still free to explore, fork, or use the stable parts of the engine.
• I plan to return to this project and perform a complete refactor once I've completed my current learning phase.

Thank you so much for your understanding, your stars, and the amazing support! 🚀

🚀 ZProximity Engine

The Physics of Attraction for the Modern Web.

A high-performance React animation library for creating proximity-based interactions, magnetic cursor effects, and scroll-driven animations with GSAP. Perfect alternative to Framer Motion and React Spring for spatial interactions.

✨ Live Demo • 📦 NPM • 📖 Documentation • 🎮 Interactive Playground

---

🎯 Why ZProximity Engine?

Performance First

• ⚡ 120+ FPS: Runs at native refresh rates
• 📦 10.7KB Core: Minimal bundle impact
• 🚀 GSAP Powered: Industry-standard animation engine
• 🎭 Zero Re-renders: Animations bypass React's render cycle

Developer Experience

• 💪 TypeScript: Full type safety
• 🎨 30+ Presets: Scale, magnetic, blur, cipher, and more
• 🔗 Chainable: Combine unlimited effects with dash syntax
• 📱 Mobile Optimized: Smart performance on touch devices

Use Cases

• 🎯 Magnetic dock interfaces (macOS-style)
• ✨ Interactive landing pages
• 📜 Scroll-driven storytelling
• 🎮 Game-like UI interactions
• 🔮 Futuristic dashboard effects

---

📦 Installation

npm install z-proximity-engine gsap @gsap/react

Peer Dependencies

npm install react@^18.0.0 react-dom@^18.0.0 gsap@^3.15.0 @gsap/react@^2.1.2

---

🚀 Quick Start

1. Basic Hover Effect (3 lines)

import { Proximity } from 'z-proximity-engine';

export const HoverCards = () => (
  <Proximity preset="scale-blur" reach={2}>
    <div className="prox-item">Card 1</div>
    <div className="prox-item">Card 2</div>
    <div className="prox-item">Card 3</div>
  </Proximity>
);

2. Text Animations

import { ProximityText } from 'z-proximity-engine';

export const Hero = () => (
  <ProximityText 
    text="HOVER ME"
    preset="scale-opacity-cipher"
    splitBy="letter"
    reach={1.5}
  />
);

3. Scroll Reveal

export const Features = () => (
  <Proximity
    mode="scroll"
    preset="reveal-opacity"
    config={{
      scroll: { start: "top 90%", once: true },
      stagger: 0.2
    }}
  >
    <div className="prox-item">Feature 1</div>
    <div className="prox-item">Feature 2</div>
  </Proximity>
);

---

🎨 Animation Presets

Transform

scale | flexScale | x | y | rotate | skew

Appearance

opacity | blur | reveal | glow | brightness

Physics

magnetic | repel | tilt | tiltCard

Typography

weight | cipher | letterSpacing | color

Combine with Dash Syntax

preset="scale-blur-magnetic-opacity"

---

🏗️ Real-World Examples

macOS Dock Effect

<Proximity 
  nearestPreset="scale-magnetic" // Closest icon grows & pulls
  neighborPreset="repel"         // Others push away
  config={{ reach: 2.5, lockAxis: 'x' }}
>
  {icons.map(icon => (
    <div key={icon} className="prox-item dock-icon">
      {icon}
    </div>
  ))}
</Proximity>

Cipher Decryption

<ProximityText 
  text="CLASSIFIED"
  preset="cipher-scale"
  config={{ 
    cipher: [0, 1],  // Scrambled → Clear
    reach: 2 
  }}
/>

Magnetic Button

<Proximity preset="magnetic-scale" reach={1.5}>
  <button className="prox-item">Click Me</button>
</Proximity>

---

📊 Performance Benchmarks

Metric	Value
Core Bundle Size	10KB (gzipped)
First Contentful Paint	< 1s
Time to Interactive	< 1.5s
Animation FPS	120+
Supported Elements	100+ simultaneous

---

🔧 API Reference

Core Props

Prop	Type	Default	Description
preset	string	-	Chain effects with dashes
reach	number	2	Influence radius
falloff	number	2.4	Curve steepness
duration	number	0.2	Animation speed
ease	string	"power1.out"	GSAP easing
mode	"pointer" | "scroll"	"pointer"	Trigger type

📖 Full API Documentation

---

🌐 Browser Support

• ✅ Chrome 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+
• ✅ Mobile browsers (iOS Safari, Chrome Mobile)

---

🤝 Contributing

Contributions welcome! Please read our Contributing Guide.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/amazing-preset)
3. Commit your changes (git commit -m 'Add amazing preset')
4. Push to the branch (git push origin feature/amazing-preset)
5. Open a Pull Request

---

📝 License

MIT © Youssef Zidan

---

🔗 Links

• 🌐 Official Website
• 📦 NPM Package
• 💬 GitHub Discussions
• 🐛 Issue Tracker
• 👨‍💻 Author Portfolio
• 💼 LinkedIn

---

🏆 Alternatives Comparison

Feature	ZProximity	Framer Motion	React Spring
Proximity Detection	✅ Built-in	❌ Manual	❌ Manual
Bundle Size	10.7KB	~50KB	~15KB
GSAP Integration	✅ Native	⚠️ Possible	❌ No
Scroll Animations	✅ Built-in	✅ Built-in	⚠️ External
TypeScript	✅ Full	✅ Full	✅ Full
Learning Curve	⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐

---

Made with ⚡ by Youssef Zidan

If this library helped you, please ⭐ star the repo!

---

Keywords

react animation, proximity detection, magnetic cursor, hover effects, scroll animations, gsap react, motion design, interactive ui, spatial interactions, cursor effects, animation library, react gsap, framer motion alternative, react spring alternative, proximity-based animations, distance-based effects