https://github.com/poyrazavsever/reactive-image
reactive-image is a lightweight and flexible image component library for React and Next.js. It introduces a variant-based system that makes it easy to add interactive visual behaviors such as hover transitions, zoom effects, click-to-expand modals, and motion-based animations.
https://github.com/poyrazavsever/reactive-image
animation component image image-animation image-component motion nextjs react react-image reactive-image
Last synced: 10 days ago
JSON representation
reactive-image is a lightweight and flexible image component library for React and Next.js. It introduces a variant-based system that makes it easy to add interactive visual behaviors such as hover transitions, zoom effects, click-to-expand modals, and motion-based animations.
- Host: GitHub
- URL: https://github.com/poyrazavsever/reactive-image
- Owner: poyrazavsever
- Created: 2025-11-06T08:46:09.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-12-18T09:45:54.000Z (6 months ago)
- Last Synced: 2025-12-21T16:58:33.644Z (6 months ago)
- Topics: animation, component, image, image-animation, image-component, motion, nextjs, react, react-image, reactive-image
- Language: TypeScript
- Homepage: https://reactive-image.vercel.app
- Size: 734 KB
- Stars: 11
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Reactive Image
**Reactive Image** - A powerful, interactive, and customizable visual component collection for React applications. Delivers stunning animations and smooth transitions to enhance user experience.
## Features
### **8 Powerful Interactive Variants**
- **HoverSwitch** - Image switching on mouse hover
- **ZoomOnHover** - Mouse-driven zoom effects
- **TiltOnHover** - 3D tilt and perspective effects
- **ClickExpand** - Click-to-expand modal viewing
- **PanReveal** - Cinematic slide, mask, and spotlight reveals
- **KenBurnsSequence** - Cinematic zoom/pan storyboards for hero blocks
- **PolaroidStack** - Fan-out polaroid stacks that lift on hover/touch
- **ScrollReactive** - Scroll-driven fades, parallax, scale, and tilt transforms
### **Performance Focused**
- Optimized animations with modern CSS transforms
- RequestAnimationFrame-based smooth motion
- Lazy loading support
- Minimal bundle size (~15kb)
### **Fully Customizable**
- 42+ different animation types
- CSS-in-JS or external stylesheet support
- Custom timing and easing functions
- Flexible sizing for responsive design
### **Multi-Platform Support**
- Special optimization for touch devices
- Gyroscope support (mobile devices)
- Keyboard navigation (accessibility)
- Compatible with all modern browsers
### **Developer Friendly**
- **Full TypeScript** support and type safety
- Comprehensive API reference and documentation
- React 18+ and Next.js compatibility
- ESM and CommonJS export support
### **Accessibility**
- ARIA labels and roles
- Screen reader compatibility
- Keyboard navigation support
- `prefers-reduced-motion` support
## Quick Start
### Installation
```bash
# npm
npm install reactive-image
# yarn
yarn add reactive-image
# pnpm
pnpm add reactive-image
# bun
bun add reactive-image
```
### Basic Usage
```jsx
import { ReactiveImage } from "reactive-image";
function App() {
return (
);
}
```
## Variants and Examples
### 1. HoverSwitch - Image Switching
Transitions between different images when mouse hovers over the element.
```jsx
// Slide animation
// 3D rotation effect
// Crossfade transition
```
**Available Animations:**
- `slide` - Horizontal/vertical sliding
- `crossfade` - Smooth transition
- `zoom` - Zoom-in transition
- `blur` - Blur effect
- `rotateY` - 3D rotation
- `slideUp/slideDown` - Vertical sliding
- `scaleRotate` - Scaling + rotation
### 2. ZoomOnHover - Zoom Effects
Various zoom animations and customizations.
```jsx
// Basic zoom
// Mouse-following zoom
// Elastic bounce effect
// 3D perspective zoom
```
**Zoom Types:**
- `scale` - Simple scaling
- `scaleRotate` - Scaling with rotation
- `scaleBlur` - With blur effect
- `scaleFade` - With opacity change
- `perspective` - 3D perspective
- `elastic` - Elastic bounce
- `bounce` - Bounce effect
- `pulse` - Pulse effect
### 3. TiltOnHover - 3D Tilt Effects
Realistic 3D tilt and perspective animations.
```jsx
// Basic tilt effect
// Tilt with light reflection
// Magnetic attraction effect
// Gyroscope support (mobile)
```
**Tilt Animations:**
- `basic` - Basic 3D tilt
- `glare` - Light reflection effect
- `scale` - Scaling with tilt
- `perspective` - Advanced 3D depth
- `magnetic` - Magnetic attraction
- `float` - Floating effect + shadow
- `parallax` - Multi-layer movement
- `bounce/elastic` - Flexible return
### 4. ClickExpand - Modal Expansion
Click-to-expand modal viewing.
```jsx
// Spring pop animation
// Glassmorphism effect
// 3D flip entrance animation
```
**Modal Animations:**
- `scaleFade` - Scaling + fade
- `slideUp/slideDown` - Up/down sliding
- `springPop` - Spring bounce
- `zoomBounce` - Zoom + bounce
- `rotateIn` - Rotate entrance
- `flipIn` - 3D flip
### 5. PanReveal - Cinematic Reveals
Layer two visuals and reveal them with directional slides, masks, or spotlight focus.
```jsx
// Slide reveal
// Spotlight tour
```
**PanReveal Controls**
- `animation`: `slide`, `mask`, `spotlight`
- `direction`: `left`, `right`, `up`, `down`, `diagonal` (slide only)
- `secondarySrc`: optional alternate asset
- `panAmount`, `maskShape`, `maskSize`, `followCursor`, `timing`
### 6. KenBurnsSequence - Cinematic Hero Sequences
Play curated zoom + pan timelines that make hero sections feel alive.
```jsx
// Dramatic preset
// Custom frame stack
const canyonFrames = [
{ zoom: 1.12, panX: -12, panY: 8, duration: 4800 },
{ zoom: 1.22, panX: 6, panY: -4, rotate: 0.8, duration: 5200 },
{ zoom: 1.15, panX: 2, panY: 10, rotate: -0.5, duration: 5000 },
];
```
**KenBurns Controls**
- Presets: `classic`, `slowPan`, `dramatic`
- `frames`: custom timeline overrides
- `crossfadeDuration`, `pauseOnHover`, `autoplay`, `loop`, `overlayGradient`, `enableTouch`
### 7. PolaroidStack - Fan-Out Photo Stacks
Layered polaroid-style cards that spread apart on hover or touch.
```jsx
```
**PolaroidStack Controls**
- `stack`: additional cards under the primary `src`
- `stackDepth`: limit how many cards render
- `spreadAngle`, `offsetStep`, `lift`, `rotationJitter`
- `shadow`: `soft | medium | strong`
- `aspectRatio`, `enableTouch`, `onStackEnter/Leave`
### 8. ScrollReactive - Scroll-Tied Motion
Drive parallax, fades, scales, or tilt with scroll progress (exposed as `--ri-scroll-progress` for theming).
```jsx
```
**ScrollReactive Controls**
- `animation`: `fadeIn`, `parallax`, `scale`, `tilt`
- `parallaxOffset`, `scaleFrom`, `rotate`, `opacityFrom`
- `triggerOffset`, `once`, `enableTouch`
- Lifecycle: `onEnter`, `onExit`, `onProgress`
## Advanced Customization
### Custom Timing Settings
```jsx
```
### CSS Customization
```jsx
// With Tailwind CSS
;
// With Styled Components
const StyledImage = styled(ReactiveImage)`
border-radius: 16px;
overflow: hidden;
&:hover {
box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
}
`;
```
### Event Callbacks
```jsx
{
console.log('Animation started');
// Analytics tracking
gtag('event', 'image_hover', { image_id: 'hero-image' });
}}
onAnimationEnd={() => {
console.log('Animation completed');
}}
/>
// Custom callbacks for tilt
{
console.log('Tilt started:', { tiltX, tiltY });
}}
onTiltMove={({ mouseX, mouseY, tiltX, tiltY }) => {
// Real-time mouse tracking
updateParallaxLayers(mouseX, mouseY);
}}
/>
```
## Mobile and Touch Support
```jsx
// Optimization for touch devices
// Gyroscope support
```
## Framework Integrations
### Next.js App Router
```jsx
// app/components/Gallery.tsx
import { ReactiveImage } from "reactive-image";
export default function Gallery() {
return (
);
}
```
### Vite + React
```jsx
// src/components/ProductShowcase.jsx
import { ReactiveImage } from "reactive-image";
export function ProductShowcase({ products }) {
return (
{products.map((product) => (
))}
);
}
```
## Performance Tips
### 1. **Image Optimization**
```jsx
// Use WebP and modern formats
```
### 2. **Preloading Strategies**
```jsx
// Preload for critical images
```
### 3. **Animation Optimization**
```jsx
// Optimal settings for performance
```
## Browser Compatibility
| Browser | Minimum Version | Feature Support |
| -------------------- | --------------- | ---------------------------------- |
| **Chrome** | 80+ | Full support (including gyroscope) |
| **Firefox** | 75+ | Full support (limited gyroscope) |
| **Safari** | 13+ | iOS gyroscope support |
| **Edge** | 80+ | Full support |
| **Samsung Internet** | 13+ | Mobile optimization |
### Progressive Enhancement
```jsx
// Fallback for older browsers
```
## API Reference
### General Props
| Prop | Type | Default | Description |
| -------------- | ----------------------------- | -------- | -------------------------------------- |
| `src` | `string` | - | **Required.** Image URL |
| `alt` | `string` | - | **Required.** Alt text (accessibility) |
| `variant` | `VariantName` | - | Animation type |
| `className` | `string` | - | Container CSS class |
| `imgClassName` | `string` | - | Image CSS class |
| `style` | `CSSProperties` | - | Inline styles |
| `loading` | `"eager" \| "lazy"` | `"lazy"` | Loading strategy |
| `decoding` | `"auto" \| "sync" \| "async"` | `"auto"` | Decode strategy |
### HoverSwitch Props
| Prop | Type | Default | Description |
| ---------------- | ------------------------------------- | ------------- | ------------------------- |
| `hoverSrc` | `string` | - | Image to show on hover |
| `animation` | `HoverSwitchAnimation` | `"crossfade"` | Transition animation type |
| `slideDirection` | `"left" \| "right" \| "up" \| "down"` | `"right"` | Slide direction |
| `timing` | `TimingConfig` | `{}` | Animation timing |
| `preloadHover` | `boolean` | `true` | Preload hover image |
| `enableTouch` | `boolean` | `false` | Touch support |
### ZoomOnHover Props
| Prop | Type | Default | Description |
| -------------- | --------------- | ---------- | ---------------------- |
| `zoomScale` | `number` | `1.15` | Zoom ratio |
| `animation` | `ZoomAnimation` | `"scale"` | Zoom animation type |
| `origin` | `ZoomOrigin` | `"center"` | Transform origin point |
| `followCursor` | `boolean` | `false` | Follow mouse cursor |
| `containZoom` | `boolean` | `false` | Prevent overflow |
### TiltOnHover Props
| Prop | Type | Default | Description |
| ----------- | ---------------------- | --------- | ---------------------------- |
| `tiltMax` | `number` | `10` | Maximum tilt angle (degrees) |
| `animation` | `TiltAnimation` | `"basic"` | Tilt animation type |
| `axis` | `"both" \| "x" \| "y"` | `"both"` | Tilt axis |
| `glare` | `GlareConfig` | `{}` | Light reflection settings |
| `gyroscope` | `boolean` | `false` | Gyroscope support |
### ClickExpand Props
| Prop | Type | Default | Description |
| ----------------- | ---------------- | ------------- | ------------------------ |
| `modalAnimation` | `ModalAnimation` | `"scaleFade"` | Modal entrance animation |
| `backdrop` | `BackdropType` | `"dim"` | Background effect |
| `modalSize` | `ModalSize` | `"auto"` | Modal size |
| `caption` | `string` | - | Image caption |
| `closeOnEsc` | `boolean` | `true` | Close on ESC key |
| `closeOnBackdrop` | `boolean` | `true` | Close on backdrop click |
## Development and Contributing
### Local Development Environment
```bash
# Clone the repository
git clone https://github.com/poyrazavsever/reactive-image.git
cd reactive-image
# Install dependencies
npm install
# Start development server
npm run dev
# Build package
npm run build:package
# Build entire project
npm run build
```
### Project Structure
```
reactive-image/
├── packages/
│ └── reactive-image/ # Main library
│ ├── src/
│ │ ├── variants/ # Animation variants
│ │ │ ├── HoverSwitch/
│ │ │ ├── ZoomOnHover/
│ │ │ ├── TiltOnHover/
│ │ │ └── ClickExpand/
│ │ ├── types.ts # TypeScript types
│ │ └── index.ts
│ └── package.json
├── apps/
│ └── docs/ # Documentation site
└── app/ # Demo application
```
### Adding New Variants
1. **Create new folder:** `packages/reactive-image/src/variants/NewVariant/`
2. **Required files:**
```
NewVariant/
├── index.ts # Exports
├── types.ts # TypeScript types
├── NewVariant.tsx # Main component
├── hooks.ts # React hooks
├── animations.ts # CSS animations
└── README.md # Documentation
```
3. **Add to main files:** `ReactiveImage.tsx` and `types.ts`
### Testing
```bash
# Run all tests
npm test
# Type checking
npm run tsc:check
# Linting
npm run lint
```
### Contributing Guidelines
- **Clean Code:** Follow ESLint and Prettier rules
- **TypeScript:** Ensure full type safety
- **Performance:** Animations should run at 60fps
- **Accessibility:** Include ARIA labels and keyboard support
- **Documentation:** Add documentation for new features
- **Tests:** Write tests for critical functions
## Community and Support
### Bug Reports
Report bugs through [GitHub Issues](https://github.com/poyrazavsever/reactive-image/issues).
### Feature Requests
Use [Discussions](https://github.com/poyrazavsever/reactive-image/discussions) for new feature suggestions.
### Documentation
Visit the [documentation site](https://reactive-image-docs.vercel.app) for detailed API reference and examples.
### Showcase
If you're using Reactive Image in your project, share it in the [showcase](https://github.com/poyrazavsever/reactive-image/discussions/categories/showcase) section!
## License
This project is licensed under **ISC License**. See [LICENSE](LICENSE) file for details.
## Acknowledgments
- **Framer Motion** - For animation inspiration
- **React Spring** - For physics-based animations
- **Tailwind CSS** - For styling system examples
- **React Community** - For continuous growth and support
---
**If you like this project, don't forget to star it on GitHub!**
[Star on GitHub](https://github.com/poyrazavsever/reactive-image) • [Documentation](https://reactive-image-docs.vercel.app) • [Demo](https://reactive-image-demo.vercel.app)
**Developer:** [Poyraz Avsever](https://github.com/poyrazavsever)
**License:** ISC • **Version:** 1.0.0