React Image Stack Carousel

⚠️ Beta Version - This package is currently in beta. API may change in future releases.

A beautiful React component for displaying images in a stacked carousel with smooth slide animations. Features a unique stacked effect where images appear layered behind each other, creating an elegant visual experience.

✨ Features

• 🎨 Beautiful Stacked Effect - Displays 3 images at once with a layered appearance
• 🎬 Smooth Animations - Images slide smoothly to the right when transitioning
• ⚙️ Highly Customizable - Control sizes, timing, styling, and behavior
• 📱 Responsive - Works well on all screen sizes
• ♿ Accessible - Proper alt text support for screen readers
• 🎯 TypeScript Support - Full TypeScript definitions included
• 📦 Zero Dependencies - Only requires React (no external dependencies)
• 🎨 CSS-in-JS Ready - Import styles separately or customize with your own

📦 Installation

npm install react-image-stack-carousel

or

yarn add react-image-stack-carousel

or

pnpm add react-image-stack-carousel

🚀 Quick Start

import { ImageStackCarousel } from 'react-image-stack-carousel';
import 'react-image-stack-carousel/dist/index.css';

const images = [
  'https://example.com/image1.jpg',
  'https://example.com/image2.jpg',
  'https://example.com/image3.jpg',
];

function App() {
  return (
    <ImageStackCarousel
      images={images}
      autoPlay={true}
      interval={4000}
    />
  );
}

📖 API Reference

Props

Prop	Type	Default	Required	Description
images	string[]	-	✅	Array of image URLs to display
autoPlay	boolean	true	❌	Enable automatic image rotation
interval	number	4000	❌	Time between transitions in milliseconds
width	number	455	❌	Width of the front image in pixels
height	number	550	❌	Height of the front image in pixels
borderRadius	number	8	❌	Border radius for images in pixels
onImageChange	(index: number) => void	-	❌	Callback function called when image changes
showIndicators	boolean	false	❌	Show indicator dots below the carousel
className	string	''	❌	Custom class name for the container
altTextPrefix	string	'Image'	❌	Prefix for image alt text (e.g., "Image 1", "Image 2")

💡 Examples

Basic Usage

import { ImageStackCarousel } from 'react-image-stack-carousel';
import 'react-image-stack-carousel/dist/index.css';

function App() {
  const images = [
    '/path/to/image1.jpg',
    '/path/to/image2.jpg',
    '/path/to/image3.jpg',
  ];

  return <ImageStackCarousel images={images} />;
}

Custom Sizes and Styling

<ImageStackCarousel
  images={images}
  width={600}
  height={800}
  borderRadius={16}
/>

With Indicators

<ImageStackCarousel
  images={images}
  showIndicators={true}
/>

Manual Control (No Auto-play)

<ImageStackCarousel
  images={images}
  autoPlay={false}
  onImageChange={(index) => {
    console.log('Current image index:', index);
  }}
/>

Custom Styling with className

<ImageStackCarousel
  images={images}
  className="my-custom-carousel"
/>

Custom Alt Text

<ImageStackCarousel
  images={images}
  altTextPrefix="Product"
  // Results in: "Product 1", "Product 2", etc.
/>

🎨 How It Works

The component displays up to 3 images simultaneously in a stacked arrangement:

• Front Image: Full size (100%), fully visible and active
• Back Image 1: 90% scale, partially visible on the left side
• Back Image 2: 80% scale, further left, behind back-1

Transition Animation

When transitioning to the next image:

1. The current front image slides to the right and fades out
2. Back-1 smoothly moves forward to become the new front image
3. Back-2 moves to the back-1 position
4. The next image in the array appears as the new back-2
5. The cycle continues seamlessly

🔧 Development

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Run development server (with example)
npm run dev

# Build for production
npm run build

📋 Requirements

• React >= 16.8.0 (hooks support required)
• React DOM >= 16.8.0

🤝 Contributing

This is a beta version. Feedback and contributions are welcome! Please feel free to:

• Report bugs
• Suggest new features
• Submit pull requests

📝 License

MIT © [Your Name]

🔮 Roadmap

• Touch/swipe gesture support
• Keyboard navigation
• Custom transition animations
• Lazy loading support
• More customization options

---

Note: This is a beta release. The API is stable but may receive minor updates based on feedback. For production use, please test thoroughly in your environment.