Carousel Component

Overview

The Carousel component provides a horizontal scrolling interface for displaying multiple items in a contained space. It's commonly used for image galleries, product showcases, testimonials, and feature highlights.

Basic Usage

import { Carousel } from '@/components/carousel'

export default function CarouselExample() {
  const items = [
    { id: '1', content: <div>Slide 1</div> },
    { id: '2', content: <div>Slide 2</div> },
    { id: '3', content: <div>Slide 3</div> }
  ];

  return (
    <Carousel items={items} />
  )
}

Preview:

Slide 1

Slide 2

Slide 3

Loading Button...

Props

Prop	Type	Default	Description
`items`	`Array<{id: string, content: JSX.Element}>`	`[]`	Array of carousel items
`type`	`'basic' \| 'image-gallery' \| 'product-showcase' \| 'testimonial'`	`'basic'`	Type of carousel content
`className`	`string`	`''`	Additional CSS classes for styling
`loop`	`boolean`	`true`	Whether the carousel should loop
`align`	`'start' \| 'center' \| 'end'`	`'start'`	Alignment of slides
`skipSnaps`	`boolean`	`false`	Whether to skip snap points
`showArrows`	`boolean`	`true`	Whether to show navigation arrows

Examples

Basic Carousel

const items = [
  { id: '1', content: <div className="p-8 text-center">Slide 1</div> },
  { id: '2', content: <div className="p-8 text-center">Slide 2</div> },
  { id: '3', content: <div className="p-8 text-center">Slide 3</div> }
];

<Carousel items={items} />

Preview:

Slide 1

Slide 2

Slide 3

Loading Button...

Image Gallery Carousel

const imageItems = [
  { 
    id: '1', 
    content: (
      <div className="relative">
        <img 
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800&h=400&fit=crop" 
          alt="Mountain landscape"
          className="w-full h-64 object-cover rounded-lg"
        />
        <div className="absolute bottom-0 left-0 right-0 bg-black/60 text-white p-6 rounded-b-lg">
          <h3 className="font-bold text-xl mb-2 text-white">Mountain Landscape</h3>
          <p className="text-white text-base">Beautiful mountain scenery</p>
        </div>
      </div>
    )
  },
  { 
    id: '2', 
    content: (
      <div className="relative">
        <img 
          src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=800&h=400&fit=crop" 
          alt="Forest path"
          className="w-full h-64 object-cover rounded-lg"
        />
        <div className="absolute bottom-0 left-0 right-0 bg-black/60 text-white p-6 rounded-b-lg">
          <h3 className="font-bold text-xl mb-2 text-white">Forest Path</h3>
          <p className="text-white text-base">Peaceful forest trail</p>
        </div>
      </div>
    )
  },
  { 
    id: '3', 
    content: (
      <div className="relative">
        <img 
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800&h=400&fit=crop" 
          alt="Ocean waves"
          className="w-full h-64 object-cover rounded-lg"
        />
        <div className="absolute bottom-0 left-0 right-0 bg-black/60 text-white p-6 rounded-b-lg">
          <h3 className="font-bold text-xl mb-2 text-white">Ocean Waves</h3>
          <p className="text-white text-base">Calming ocean view</p>
        </div>
      </div>
    )
  }
];

<Carousel items={imageItems} />

Preview:

Mountain Landscape

Beautiful mountain scenery

Forest Path

Peaceful forest trail

Ocean Waves

Calming ocean view

Loading Button...

Product Showcase Carousel

const productItems = [
  {
    id: '1',
    content: (
      <div className="bg-white rounded-lg shadow-md p-6">
        <img 
          src="https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=400&h=300&fit=crop" 
          alt="Product 1"
          className="w-full h-48 object-cover rounded-lg mb-4"
        />
        <h3 className="font-semibold text-lg mb-2">Premium Headphones</h3>
        <p className="text-gray-600 text-sm mb-3">High-quality wireless headphones with noise cancellation</p>
        <div className="flex justify-between items-center">
          <span className="text-2xl font-bold text-blue-600">$299</span>
          <button className="bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700">
            Add to Cart
          </button>
        </div>
      </div>
    )
  },
  {
    id: '2',
    content: (
      <div className="bg-white rounded-lg shadow-md p-6">
        <img 
          src="https://images.unsplash.com/photo-1505740420928-5e560c06d30e?w=400&h=300&fit=crop" 
          alt="Product 2"
          className="w-full h-48 object-cover rounded-lg mb-4"
        />
        <h3 className="font-semibold text-lg mb-2">Smart Watch</h3>
        <p className="text-gray-600 text-sm mb-3">Feature-rich smartwatch with health monitoring</p>
        <div className="flex justify-between items-center">
          <span className="text-2xl font-bold text-blue-600">$199</span>
          <button className="bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700">
            Add to Cart
          </button>
        </div>
      </div>
    )
  },
  {
    id: '3',
    content: (
      <div className="bg-white rounded-lg shadow-md p-6">
        <img 
          src="https://images.unsplash.com/photo-1526170375885-4d8ecf77b99f?w=400&h=300&fit=crop" 
          alt="Product 3"
          className="w-full h-48 object-cover rounded-lg mb-4"
        />
        <h3 className="font-semibold text-lg mb-2">Wireless Speaker</h3>
        <p className="text-gray-600 text-sm mb-3">Portable Bluetooth speaker with amazing sound quality</p>
        <div className="flex justify-between items-center">
          <span className="text-2xl font-bold text-blue-600">$149</span>
          <button className="bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700">
            Add to Cart
          </button>
        </div>
      </div>
    )
  }
];

<Carousel items={productItems} />

Preview:

Premium Headphones

High-quality wireless headphones with noise cancellation

$299

Smart Watch

Feature-rich smartwatch with health monitoring

$199

Wireless Speaker

Portable Bluetooth speaker with amazing sound quality

$149

Loading Button...

Testimonial Carousel

const testimonialItems = [
  {
    id: '1',
    content: (
      <div className="bg-gradient-to-br from-blue-50 to-indigo-100 rounded-lg p-8 text-center">
        <div className="w-16 h-16 bg-blue-600 rounded-full mx-auto mb-4 flex items-center justify-center">
          <span className="text-white text-xl font-semibold">JD</span>
        </div>
        <blockquote className="text-gray-700 text-lg mb-4">
          "This product has completely transformed my workflow. The quality and features are outstanding!"
        </blockquote>
        <div>
          <h4 className="font-semibold text-gray-900">John Doe</h4>
          <p className="text-gray-600 text-sm">CEO, TechCorp</p>
        </div>
      </div>
    )
  },
  {
    id: '2',
    content: (
      <div className="bg-gradient-to-br from-green-50 to-emerald-100 rounded-lg p-8 text-center">
        <div className="w-16 h-16 bg-green-600 rounded-full mx-auto mb-4 flex items-center justify-center">
          <span className="text-white text-xl font-semibold">SJ</span>
        </div>
        <blockquote className="text-gray-700 text-lg mb-4">
          "Incredible value for money. The customer support is exceptional and the product delivers on all promises."
        </blockquote>
        <div>
          <h4 className="font-semibold text-gray-900">Sarah Johnson</h4>
          <p className="text-gray-600 text-sm">Designer, CreativeStudio</p>
        </div>
      </div>
    )
  },
  {
    id: '3',
    content: (
      <div className="bg-gradient-to-br from-purple-50 to-violet-100 rounded-lg p-8 text-center">
        <div className="w-16 h-16 bg-purple-600 rounded-full mx-auto mb-4 flex items-center justify-center">
          <span className="text-white text-xl font-semibold">MW</span>
        </div>
        <blockquote className="text-gray-700 text-lg mb-4">
          "The best investment I've made this year. Highly recommended for anyone looking for quality solutions."
        </blockquote>
        <div>
          <h4 className="font-semibold text-gray-900">Mike Wilson</h4>
          <p className="text-gray-600 text-sm">Founder, StartupXYZ</p>
        </div>
      </div>
    )
  }
];

<Carousel items={testimonialItems} />

Preview:

"This product has completely transformed my workflow. The quality and features are outstanding!"

John Doe

CEO, TechCorp

"Incredible value for money. The customer support is exceptional and the product delivers on all promises."

Sarah Johnson

Designer, CreativeStudio

"The best investment I've made this year. Highly recommended for anyone looking for quality solutions."

Mike Wilson

Founder, StartupXYZ

Loading Button...

Custom Configuration Examples

No Loop Carousel

<Carousel 
  type="basic"
  loop={false}
  showArrows={true}
/>

Preview:

Slide 1

Slide 2

Slide 3

Loading Button...

Center Aligned Carousel

<Carousel 
  type="image-gallery"
  align="center"
  showArrows={true}
/>

Preview:

Mountain Landscape

Beautiful mountain scenery

Forest Path

Peaceful forest trail

Ocean Waves

Calming ocean view

Loading Button...

No Arrows Carousel

<Carousel 
  type="product-showcase"
  showArrows={false}
  loop={true}
/>

Preview:

Premium Headphones

High-quality wireless headphones with noise cancellation

$299

Smart Watch

Feature-rich smartwatch with health monitoring

$199

Wireless Speaker

Portable Bluetooth speaker with amazing sound quality

$149

Skip Snaps Carousel

<Carousel 
  type="testimonial"
  skipSnaps={true}
  align="end"
/>

Preview:

"This product has completely transformed my workflow. The quality and features are outstanding!"

John Doe

CEO, TechCorp

"Incredible value for money. The customer support is exceptional and the product delivers on all promises."

Sarah Johnson

Designer, CreativeStudio

"The best investment I've made this year. Highly recommended for anyone looking for quality solutions."

Mike Wilson

Founder, StartupXYZ

Loading Button...

Custom Styling

<Carousel 
  type="basic"
  className="max-w-md mx-auto"
  loop={true}
  align="center"
/>

Preview:

Slide 1

Slide 2

Slide 3

Loading Button...

Common Use Cases

Image Gallery

const galleryItems = [
  { id: '1', content: <img src="/image1.jpg" alt="Gallery 1" className="w-full h-64 object-cover rounded-lg" /> },
  { id: '2', content: <img src="/image2.jpg" alt="Gallery 2" className="w-full h-64 object-cover rounded-lg" /> },
  { id: '3', content: <img src="/image3.jpg" alt="Gallery 3" className="w-full h-64 object-cover rounded-lg" /> }
];

<Carousel items={galleryItems} className="max-w-2xl" />

Feature Highlights

const featureItems = [
  {
    id: '1',
    content: (
      <div className="p-6 text-center">
        <div className="text-4xl mb-4">🚀</div>
        <h3 className="text-xl font-semibold mb-2">Fast Performance</h3>
        <p className="text-gray-600">Lightning-fast loading times</p>
      </div>
    )
  },
  {
    id: '2',
    content: (
      <div className="p-6 text-center">
        <div className="text-4xl mb-4">🔒</div>
        <h3 className="text-xl font-semibold mb-2">Secure</h3>
        <p className="text-gray-600">Enterprise-grade security</p>
      </div>
    )
  },
  {
    id: '3',
    content: (
      <div className="p-6 text-center">
        <div className="text-4xl mb-4">📱</div>
        <h3 className="text-xl font-semibold mb-2">Mobile Ready</h3>
        <p className="text-gray-600">Works on all devices</p>
      </div>
    )
  }
];

<Carousel items={featureItems} />

News/Blog Posts

const newsItems = [
  {
    id: '1',
    content: (
      <div className="p-6 border rounded-lg">
        <div className="w-full h-32 bg-gray-200 rounded mb-4"></div>
        <h3 className="font-semibold text-lg mb-2">Latest News Title</h3>
        <p className="text-gray-600 text-sm mb-2">Brief description of the news article...</p>
        <div className="text-xs text-gray-500">2 hours ago</div>
      </div>
    )
  },
  {
    id: '2',
    content: (
      <div className="p-6 border rounded-lg">
        <div className="w-full h-32 bg-gray-200 rounded mb-4"></div>
        <h3 className="font-semibold text-lg mb-2">Another News Title</h3>
        <p className="text-gray-600 text-sm mb-2">Another brief description...</p>
        <div className="text-xs text-gray-500">5 hours ago</div>
      </div>
    )
  }
];

<Carousel items={newsItems} />

Best Practices

Consistent Item Structure

Maintain consistent structure across all carousel items.

// ✅ Good - Consistent structure
const items = [
  { 
    id: '1', 
    content: (
      <div className="p-6 border rounded-lg">
        <img src="/image1.jpg" className="w-full h-48 object-cover rounded mb-4" />
        <h3 className="font-semibold">Title 1</h3>
        <p className="text-gray-600">Description 1</p>
      </div>
    )
  },
  { 
    id: '2', 
    content: (
      <div className="p-6 border rounded-lg">
        <img src="/image2.jpg" className="w-full h-48 object-cover rounded mb-4" />
        <h3 className="font-semibold">Title 2</h3>
        <p className="text-gray-600">Description 2</p>
      </div>
    )
  }
];

Appropriate Sizing

Use appropriate sizing for different content types.

// ✅ Good - Appropriate sizing
<Carousel 
  items={items} 
  className="max-w-md" // For small content
/>

<Carousel 
  items={items} 
  className="max-w-4xl" // For large content
/>

Ensure carousel navigation is accessible.

// ✅ Good - Accessible carousel
<Carousel 
  items={items}
  className="carousel-accessible"
/>

Responsive Design

Make carousels responsive for different screen sizes.

// ✅ Good - Responsive carousel
<Carousel 
  items={items}
  className="w-full max-w-sm md:max-w-md lg:max-w-lg"
/>

Performance Optimization

Optimize carousel performance for large datasets.

// ✅ Good - Optimized for performance
const items = useMemo(() => 
  data.map(item => ({
    id: item.id,
    content: <ItemComponent item={item} />
  })), [data]
);

<Carousel items={items} />

Customization

Custom Styling

You can customize the carousel appearance using CSS classes:

<Carousel 
  items={items}
  className="border-2 border-blue-500 rounded-xl shadow-lg"
/>

Different Sizes

Use different sizes for different contexts:

// Small carousel
<Carousel 
  items={items}
  className="max-w-xs"
/>

// Large carousel
<Carousel 
  items={items}
  className="max-w-4xl"
/>

Customize navigation buttons:

<Carousel 
  items={items}
  className="carousel-custom-nav"
/>

Advanced Usage

Dynamic Content

Create dynamic carousels with changing content:

const [currentItems, setCurrentItems] = useState(initialItems);

const addItem = (newItem) => {
  setCurrentItems(prev => [...prev, newItem]);
};

<Carousel items={currentItems} />

Auto-play Carousel

Implement auto-playing carousels:

const [currentIndex, setCurrentIndex] = useState(0);

useEffect(() => {
  const interval = setInterval(() => {
    setCurrentIndex(prev => (prev + 1) % items.length);
  }, 3000);

  return () => clearInterval(interval);
}, [items.length]);

Carousel with Indicators

Add indicators to show current position:

const [currentIndex, setCurrentIndex] = useState(0);

<div className="space-y-4">
  <Carousel items={items} />
  <div className="flex justify-center space-x-2">
    {items.map((_, index) => (
      <button
        key={index}
        className={`w-2 h-2 rounded-full ${
          index === currentIndex ? 'bg-blue-500' : 'bg-gray-300'
        }`}
        onClick={() => setCurrentIndex(index)}
      />
    ))}
  </div>
</div>

Slider: For range selection
Tabs: For tabbed content
Accordion: For collapsible content
Modal: For overlay content
Image: For image display

API Reference

For the complete API reference and advanced usage patterns, see the Carousel API documentation.

Overview

Basic Usage

Props

Examples

Basic Carousel

Image Gallery Carousel

Mountain Landscape

Forest Path

Ocean Waves

Product Showcase Carousel

Premium Headphones

Smart Watch

Wireless Speaker

Testimonial Carousel

John Doe

Sarah Johnson

Mike Wilson

Custom Configuration Examples

No Loop Carousel

Center Aligned Carousel

Mountain Landscape

Forest Path

Ocean Waves

No Arrows Carousel

Premium Headphones

Smart Watch

Wireless Speaker

Skip Snaps Carousel

John Doe

Sarah Johnson

Mike Wilson

Custom Styling

Common Use Cases

Image Gallery

Feature Highlights

News/Blog Posts

Best Practices

Consistent Item Structure

Appropriate Sizing

Accessible Navigation

Responsive Design

Performance Optimization

Customization

Custom Styling

Different Sizes

Custom Navigation

Advanced Usage

Dynamic Content

Auto-play Carousel

Carousel with Indicators

Related Components

API Reference