AwesomeCoverflowCarousel

A beautiful, interactive 3D Coverflowcarousel component for React with smooth animations, multiple themes, and flexible data handling. Perfect for showcasing products, portfolios, or any collection of items in an eye-catching carousel format.

Features

• 3D CoverflowCarousel - Visually stunning 3D perspective effects
• 4 Built-in Themes - Dark, Light, Neon, and Glass themes
• Multiple Control Methods - Mouse drag, keyboard arrows, touch & programmatic
• Auto-Rotate - Automatic carousel rotation with customizable speed
• Responsive - Works seamlessly on different screen sizes
• Smooth Physics - Realistic inertia and friction animations
• Glow Effects - Beautiful focus glow for the active item
• Highly Customizable - Full control over speed, friction, perspective, and more

Installation

npm install awesome-coverflow-carousel

Or with pnpm:

pnpm add awesome-coverflow-carousel

Or with yarn:

yarn add awesome-coverflow-carousel

Quick Start

import { AwesomeCoverflowCarousel } from 'awesome-coverflow-carousel';
import 'awesome-coverflow-carousel/dist/style.css';

const slides = [
  { title: 'Slide 1', description: 'First slide', image: 'url1.jpg' },
  { title: 'Slide 2', description: 'Second slide', image: 'url2.jpg' },
];

export default function App() {
  return (
    <div
      style={{
        minHeight: '100vh',
        padding: '48px 20px 64px',
        background:
          'radial-gradient(70% 50% at 50% 35%, rgba(0,245,255,0.18) 0%, rgba(0,0,0,0) 60%), linear-gradient(180deg, #05070f 0%, #060b1a 55%, #070b12 100%)',
        color: '#e6f0ff',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'center',
        gap: '18px',
      }}
    >
      <h1 style={{ margin: 0, fontSize: 'clamp(28px, 5vw, 56px)', letterSpacing: '-0.02em' }}>
        Explore the Universe of <span style={{ color: '#00f5ff' }}>Possibilities</span>
      </h1>
      <p style={{ margin: 0, opacity: 0.7 }}>
        Explore the full spectrum of products by clicking on any card
      </p>

      <div style={{ width: '100%', maxWidth: 980, height: '60vh', minHeight: 420 }}>
        <AwesomeCoverflowCarousel data={slides} theme="dark" />
      </div>
    </div>
  );
}

Data Format

Each item in the carousel requires the following structure:

const slide = {
  title: 'Slide 1',            // Required: Title displayed on the card
  description: 'First slide',  // Optional: Subtitle or description
  image: 'url1.jpg',           // Optional: Image URL
  tag: 'Featured',             // Optional: Tag label
  color: '#ff6b6b',            // Optional: Background color (hex)
  onClick: () => {},           // Optional: Click handler
};

For TypeScript users, this object shape maps directly to the SlideData type exported by the package.

Component Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | SlideData[] | Required | Array of slide objects to display in the carousel | | autoRotate | boolean | true | Enable automatic carousel rotation | | rotationSpeed | number | 2800 | Time in milliseconds between auto-rotations | | friction | number | 0.88 | Friction coefficient for inertia animations (0-1). Higher = more damping | | focusGlow | boolean | true | Enable glow effect on the focused card | | theme | 'dark' \| 'light' \| 'neon' \| 'glass' | 'dark' | Visual theme for the carousel | | perspective | number | 1100 | 3D perspective depth in pixels | | onFocusChange | (index: number) => void | undefined | Callback fired when the focused item changes | | className | string | undefined | Custom CSS class for the carousel container |

Available Themes

Dark Theme

Modern dark theme with cyan accents. Perfect for tech products and modern designs.

<AwesomeCoverflowCarousel data={slides} theme="dark" />

Light Theme

Clean light theme with violet accents. Great for portfolios and creative showcases.

<AwesomeCoverflowCarousel data={slides} theme="light" />

Neon Theme

Vibrant neon magenta and cyan theme. Bold and eye-catching for entertainment and gaming.

<AwesomeCoverflowCarousel data={slides} theme="neon" />

Glass Theme

Frosted glass effect with semi-transparent cards. Modern and elegant for premium brands.

<AwesomeCoverflowCarousel data={slides} theme="glass" />

Usage Examples

Example 1: Static Data Source

Use hardcoded data directly in your component:

import { AwesomeCoverflowCarousel } from 'awesome-coverflow-carousel';
import 'awesome-coverflow-carousel/dist/style.css';

export default function StaticDataExample() {
  const staticSlides = [
    {
      title: 'Product A',
      description: 'Premium quality product',
      image: 'https://images.unsplash.com/photo-1505740420928-5e560c06d30e?w=500&h=300&fit=crop',
      tag: 'Featured',
      onClick: () => console.log('Product A clicked')
    },
    {
      title: 'Product B',
      description: 'Best seller item',
      image: 'https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=500&h=300&fit=crop',
      tag: 'Sale',
      onClick: () => console.log('Product B clicked')
    },
    {
      title: 'Product C',
      description: 'New arrival',
      image: 'https://images.unsplash.com/photo-1505740420928-5e560c06d30e?w=500&h=300&fit=crop',
      tag: 'New',
      onClick: () => console.log('Product C clicked')
    },
    {
      title: 'Product D',
      description: 'Limited edition',
      image: 'https://images.unsplash.com/photo-1517457373614-b7152f800fd1?w=500&h=300&fit=crop',
      tag: 'Limited',
      onClick: () => console.log('Product D clicked')
    },
  ];

  return (
    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
      <h1 style={{ textAlign: 'center', padding: '20px' }}>Static Data Example</h1>
      <div style={{ flex: 1 }}>
        <AwesomeCoverflowCarousel
          data={staticSlides}
          theme="dark"
          onFocusChange={(index) => console.log('Focused item:', index)}
        />
      </div>
    </div>
  );
}

Example 2: JSON File Data Source

Load carousel data from a JSON file:

import { useEffect, useState } from 'react';
import { AwesomeCoverflowCarousel } from 'awesome-coverflow-carousel';
import 'awesome-coverflow-carousel/dist/style.css';

export default function JSONDataExample() {
  const [slides, setSlides] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    // Load slides from JSON file in public folder
    fetch('/carousel-data.json')
      .then((response) => {
        if (!response.ok) throw new Error('Failed to load data');
        return response.json();
      })
      .then((data) => {
        setSlides(data);
        setLoading(false);
      })
      .catch((err) => {
        setError(err.message);
        setLoading(false);
      });
  }, []);

  if (loading) return <div style={{ textAlign: 'center', padding: '20px' }}>Loading...</div>;
  if (error) return <div style={{ textAlign: 'center', padding: '20px', color: 'red' }}>Error: {error}</div>;

  return (
    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
      <h1 style={{ textAlign: 'center', padding: '20px' }}>JSON File Data Example</h1>
      <div style={{ flex: 1 }}>
        <AwesomeCoverflowCarousel
          data={slides}
          theme="light"
          autoRotate={true}
          rotationSpeed={3000}
          onFocusChange={(index) => console.log('Focused item:', index)}
        />
      </div>
    </div>
  );
}

Sample carousel-data.json (place in public folder):

[
  {
    "title": "Portfolio Project 1",
    "description": "Award-winning design system",
    "image": "https://images.unsplash.com/photo-1561070791-2526d30994b5?w=500&h=300&fit=crop",
    "tag": "Design",
    "color": "#1e3a8a"
  },
  {
    "title": "Portfolio Project 2",
    "description": "Enterprise web application",
    "image": "https://images.unsplash.com/photo-1517694712202-14dd9538aa97?w=500&h=300&fit=crop",
    "tag": "Development",
    "color": "#064e3b"
  },
  {
    "title": "Portfolio Project 3",
    "description": "Mobile app with 10M+ downloads",
    "image": "https://images.unsplash.com/photo-1560807707-38cc612d91b3?w=500&h=300&fit=crop",
    "tag": "Mobile",
    "color": "#5b1f39"
  },
  {
    "title": "Portfolio Project 4",
    "description": "Real-time data visualization",
    "image": "https://images.unsplash.com/photo-1516321295223-4f2d3f2cf1e1?w=500&h=300&fit=crop",
    "tag": "Analytics",
    "color": "#78350f"
  }
]

Example 3: REST API Data Source

Fetch carousel data from a REST API:

import { useEffect, useState } from 'react';
import { AwesomeCoverflowCarousel } from 'awesome-coverflow-carousel';
import 'awesome-coverflow-carousel/dist/style.css';

export default function RESTAPIExample() {
  const [slides, setSlides] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  const [focusedItem, setFocusedItem] = useState(null);

  useEffect(() => {
    // Fetch from a REST API endpoint
    fetch('https://api.example.com/carousel-items')
      .then((response) => {
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return response.json();
      })
      .then((data) => {
        // Transform API response to match SlideData format
        const transformedData = data.map((item) => ({
          title: item.name || item.title,
          description: item.summary || item.description,
          image: item.thumbnail || item.image,
          tag: item.category || item.type,
          color: item.accentColor,
          onClick: () => console.log(`Clicked: ${item.id}`)
        }));
        setSlides(transformedData);
        setLoading(false);
      })
      .catch((err) => {
        setError(err.message);
        setLoading(false);
      });
  }, []);

  const handleFocusChange = (index) => {
    setFocusedItem(slides[index] || null);
    console.log(`Focused on: ${slides[index]?.title}`);
  };

  if (loading) {
    return (
      <div style={{ textAlign: 'center', padding: '20px', color: '#999' }}>
        Loading carousel data...
      </div>
    );
  }

  if (error) {
    return (
      <div style={{ textAlign: 'center', padding: '20px', color: 'red' }}>
        Error loading data: {error}
      </div>
    );
  }

  return (
    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
      <h1 style={{ textAlign: 'center', padding: '20px' }}>REST API Data Example</h1>
      
      {focusedItem && (
        <div style={{
          textAlign: 'center',
          padding: '10px 20px',
          backgroundColor: 'rgba(0, 245, 255, 0.1)',
          borderBottom: '1px solid rgba(0, 245, 255, 0.2)',
        }}>
          <p>Currently viewing: <strong>{focusedItem.title}</strong></p>
          {focusedItem.description && <p style={{ fontSize: '0.9em', color: '#aaa' }}>{focusedItem.description}</p>}
        </div>
      )}

      <div style={{ flex: 1 }}>
        <AwesomeCoverflowCarousel
          data={slides}
          theme="neon"
          autoRotate={false}
          friction={0.85}
          perspective={1200}
          focusGlow={true}
          onFocusChange={handleFocusChange}
        />
      </div>

      <div style={{
        textAlign: 'center',
        padding: '15px',
        fontSize: '0.85em',
        color: '#888',
        borderTop: '1px solid rgba(255, 255, 255, 0.1)',
      }}>
        Use arrow keys or drag to navigate • Current count: {slides.length} items
      </div>
    </div>
  );
}

Interaction Methods

Mouse Interactions

• Drag: Click and drag left/right to rotate the carousel
• Click: Click on a side item to bring it to center

Keyboard Interactions

• Arrow Left: Rotate to previous item
• Arrow Right: Rotate to next item

Mouse Events

• Hover: Pauses auto-rotation when hovering over the carousel
• Leave: Resumes auto-rotation when mouse leaves

Performance Tips

1. Optimize Images: Use optimized image URLs for better performance
2. Lazy Loading: Load large datasets progressively
3. Memoize Callbacks: Use useCallback for onFocusChange handlers
4. Responsive Container: Set appropriate dimensions for different screen sizes

// Example with responsive sizing
<div style={{
  width: '100%',
  height: window.innerWidth < 768 ? '60vh' : '100vh'
}}>
  <AwesomeCoverflowCarousel data={slides} />
</div>

Styling

The component comes with built-in styles. Import the CSS file:

import 'awesome-coverflow-carousel/dist/style.css';

All theme colors and styles are defined in the included CSS. You can override default styles with custom CSS classes:

/* Override carousel styles */
.custom-carousel {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

<AwesomeCoverflowCarousel
  data={slides}
  className="custom-carousel"
/>