Carousel

The Carousel component is a versatile slideshow component built on top of Swiper.js. It supports manual navigation, autoplay, crossfade effects, and various customization options for creating engaging image galleries and content sliders.

Overview

The Carousel component is designed to provide flexible slideshow functionality with:

Manual and automatic navigation
Crossfade and slide transition effects
Navigation arrows and pagination dots
Progress bar for autoplay
Support for images with text overlays
Customizable styling and behavior
Responsive design with touch support

Basic Usage

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

function MyComponent() {
  const slides = [
    <img src="image1.jpg" alt="Slide 1" className="w-full h-64 object-cover rounded-xl" />,
    <img src="image2.jpg" alt="Slide 2" className="w-full h-64 object-cover rounded-xl" />,
    <img src="image3.jpg" alt="Slide 3" className="w-full h-64 object-cover rounded-xl" />
  ]

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

Props

Prop	Type	Default	Description
`slides`	`ReactNode[]`	`[]`	Array of React elements to display as slides
`slidesWithText`	`Array<{image, title, desc}>`	-	Array of objects with image, title, and description
`autoplay`	`boolean \| number`	`false`	Enable autoplay (true for default 2000ms, or specify milliseconds)
`effect`	`string`	-	Transition effect ('fade' for crossfade)
`navigation`	`boolean`	`true`	Show navigation arrows
`pagination`	`boolean`	`true`	Show pagination dots
`className`	`string`	`''`	Additional CSS classes for the carousel
`swiperProps`	`object`	`{}`	Additional props to pass to Swiper component
`showProgressBar`	`boolean`	`false`	Show progress bar for autoplay
`progressBarClassName`	`string`	`'bg-blue-500'`	CSS classes for progress bar
`progressBarPosition`	`string`	`'top'`	Position of progress bar ('top' or 'bottom')
`spaceBetween`	`number`	`16`	Space between slides in pixels
`slidesPerView`	`number`	`1`	Number of slides visible at once
`children`	`ReactNode`	-	Alternative to slides prop for child elements
`onSlideChange`	`function`	`() => {}`	Callback when slide changes
`onSwiper`	`function`	-	Callback when Swiper instance is created

Basic Carousel

<Card>
  <h2>Carousel Basic (Manual)</h2>
  <Carousel
    slides={dataSlides.map((item) => (
      <img src={item.image} alt={item.title} className='w-full h-64 object-cover rounded-xl' />
    ))}
  />
</Card>

With Children

<Carousel>
  <img src="image1.jpg" alt="Slide 1" className="w-full h-64 object-cover rounded-xl" />
  <img src="image2.jpg" alt="Slide 2" className="w-full h-64 object-cover rounded-xl" />
  <img src="image3.jpg" alt="Slide 3" className="w-full h-64 object-cover rounded-xl" />
</Carousel>

Carousel with Text Overlays

Using slidesWithText Prop

<Card>
  <h2>Carousel with Title & Description</h2>
  <Carousel slidesWithText={dataSlides} />
</Card>

Data Structure for slidesWithText

const dataSlides = [
  {
    image: 'https://images.pexels.com/photos/8004110/pexels-photo-8004110.jpeg',
    title: 'Beautiful Nature',
    desc: 'Enjoy the beauty of nature in every moment.',
  },
  {
    image: 'https://images.pexels.com/photos/3798101/pexels-photo-3798101.jpeg',
    title: 'Urban Life',
    desc: 'Experience the vibrant city atmosphere.',
  },
  {
    image: 'https://images.pexels.com/photos/3396668/pexels-photo-3396668.jpeg',
    title: 'Mountain Adventure',
    desc: 'Feel the thrill of adventure in the mountains.',
  },
]

Autoplay Carousel

Basic Autoplay

<Card>
  <h2>Carousel Interval (Autoplay)</h2>
  <Carousel
    slides={dataSlides.map((item) => (
      <img src={item.image} alt={item.title} className='w-full h-64 object-cover rounded-xl' />
    ))}
    autoplay={2000}
  />
</Card>

Autoplay with Progress Bar

<Card>
  <h2>Carousel with Progress</h2>
  <Carousel
    slides={dataSlides.map((item) => (
      <img src={item.image} alt={item.title} className='w-full h-64 object-cover rounded-xl' />
    ))}
    autoplay={3000}
    showProgressBar
    progressBarClassName='bg-blue-500 dark:bg-blue-400'
    progressBarPosition='bottom'
  />
</Card>

Transition Effects

Crossfade Effect

<Card>
  <h2>Carousel Cross Fade</h2>
  <Carousel
    slides={dataSlides.map((item) => (
      <img src={item.image} alt={item.title} className='w-full h-64 object-cover rounded-xl' />
    ))}
    effect='fade'
  />
</Card>

<Carousel
  slides={slides}
  navigation={false}
  pagination={true}
/>

Without Pagination

<Carousel
  slides={slides}
  navigation={true}
  pagination={false}
/>

Without Both

<Carousel
  slides={slides}
  navigation={false}
  pagination={false}
/>

Multiple Slides Per View

Two Slides Per View

<Carousel
  slides={slides}
  slidesPerView={2}
  spaceBetween={20}
/>

Three Slides Per View

<Carousel
  slides={slides}
  slidesPerView={3}
  spaceBetween={24}
/>

Progress Bar Customization

Top Position with Custom Color

<Carousel
  slides={slides}
  autoplay={4000}
  showProgressBar
  progressBarClassName='bg-green-500'
  progressBarPosition='top'
/>

Bottom Position with Custom Color

<Carousel
  slides={slides}
  autoplay={5000}
  showProgressBar
  progressBarClassName='bg-purple-500'
  progressBarPosition='bottom'
/>

Event Handlers

Slide Change Callback

<Carousel
  slides={slides}
  onSlideChange={(swiper) => {
    console.log('Current slide index:', swiper.activeIndex)
  }}
/>

Swiper Instance Callback

<Carousel
  slides={slides}
  onSwiper={(swiper) => {
    console.log('Swiper instance:', swiper)
  }}
/>

Advanced Configuration

Custom Swiper Props

<Carousel
  slides={slides}
  swiperProps={{
    loop: true,
    speed: 800,
    grabCursor: true,
    onAutoplayTimeLeft: (swiper, time, progress) => {
      console.log('Autoplay progress:', progress)
    }
  }}
/>

Responsive Configuration

<Carousel
  slides={slides}
  swiperProps={{
    breakpoints: {
      640: {
        slidesPerView: 1,
        spaceBetween: 16
      },
      768: {
        slidesPerView: 2,
        spaceBetween: 20
      },
      1024: {
        slidesPerView: 3,
        spaceBetween: 24
      }
    }
  }}
/>

Examples

Basic Carousel

<Card>
  <h2>Carousel Basic (Manual)</h2>
  <Carousel
    slides={dataSlides.map((item) => (
      <img src={item.image} alt={item.title} className='w-full h-64 object-cover rounded-xl' />
    ))}
  />
</Card>

Carousel with Text

<Card>
  <h2>Carousel with Title & Description</h2>
  <Carousel slidesWithText={dataSlides} />
</Card>

Autoplay Carousel

<Card>
  <h2>Carousel Interval (Autoplay)</h2>
  <Carousel
    slides={dataSlides.map((item) => (
      <img src={item.image} alt={item.title} className='w-full h-64 object-cover rounded-xl' />
    ))}
    autoplay={2000}
  />
</Card>

Crossfade Carousel

<Card>
  <h2>Carousel Cross Fade</h2>
  <Carousel
    slides={dataSlides.map((item) => (
      <img src={item.image} alt={item.title} className='w-full h-64 object-cover rounded-xl' />
    ))}
    effect='fade'
  />
</Card>

Progress Bar Carousel

<Card>
  <h2>Carousel with Progress</h2>
  <Carousel
    slides={dataSlides.map((item) => (
      <img src={item.image} alt={item.title} className='w-full h-64 object-cover rounded-xl' />
    ))}
    autoplay={3000}
    showProgressBar
    progressBarClassName='bg-blue-500 dark:bg-blue-400'
    progressBarPosition='bottom'
  />
</Card>

Data Structure

slidesWithText Array

const dataSlides = [
  {
    image: 'https://example.com/image1.jpg',
    title: 'Slide Title',
    desc: 'Slide description text'
  },
  {
    image: 'https://example.com/image2.jpg',
    title: 'Another Title',
    desc: 'Another description'
  }
]

slides Array

const slides = [
  <img src="image1.jpg" alt="Slide 1" className="w-full h-64 object-cover rounded-xl" />,
  <img src="image2.jpg" alt="Slide 2" className="w-full h-64 object-cover rounded-xl" />,
  <div className="bg-blue-500 h-64 flex items-center justify-center text-white">
    <h2>Custom Slide Content</h2>
  </div>
]

Styling

The Carousel component uses Swiper.js and includes:

Responsive Design: Works on all screen sizes
Touch Support: Swipe gestures on mobile devices
Smooth Transitions: CSS transitions for slide changes
Custom Styling: Configurable progress bars and navigation
Dark Mode Support: Automatic dark mode variants
Accessibility: Keyboard navigation and screen reader support

Accessibility

The Carousel component includes accessibility features:

Keyboard navigation support
Screen reader friendly
ARIA labels for navigation
Focus management
Touch gesture support

Best Practices

Use appropriate autoplay timing (2-5 seconds recommended)
Provide meaningful alt text for images
Consider mobile users with touch-friendly navigation
Use progress bars for longer autoplay durations
Optimize images for web performance
Test keyboard navigation for accessibility compliance

Common Use Cases

Image galleries: Photo collections and portfolios
Content sliders: Featured content and promotions
Testimonials: Customer reviews and quotes
Product showcases: Product images and features
Hero sections: Landing page banners
News feeds: Article previews and updates

Card - Often used as a container for carousel examples
Button - For custom navigation controls
NavIcon - For custom navigation icons

Overview​

Basic Usage​

Props​

Basic Carousel​

Manual Navigation​

With Children​

Carousel with Text Overlays​

Using slidesWithText Prop​

Data Structure for slidesWithText​

Autoplay Carousel​

Basic Autoplay​

Autoplay with Progress Bar​

Transition Effects​

Crossfade Effect​

Navigation Options​

Without Navigation​

Without Pagination​

Without Both​

Multiple Slides Per View​

Two Slides Per View​

Three Slides Per View​

Progress Bar Customization​

Top Position with Custom Color​

Bottom Position with Custom Color​

Event Handlers​

Slide Change Callback​

Swiper Instance Callback​

Advanced Configuration​

Custom Swiper Props​

Responsive Configuration​

Examples​

Basic Carousel​

Carousel with Text​

Autoplay Carousel​

Crossfade Carousel​

Progress Bar Carousel​

Data Structure​

slidesWithText Array​

slides Array​

Styling​

Accessibility​

Best Practices​

Common Use Cases​

Related Components​

Overview

Basic Usage

Props

Basic Carousel

Manual Navigation

With Children

Carousel with Text Overlays

Using slidesWithText Prop

Data Structure for slidesWithText

Autoplay Carousel

Basic Autoplay

Autoplay with Progress Bar

Transition Effects

Crossfade Effect

Navigation Options

Without Navigation

Without Pagination

Without Both

Multiple Slides Per View

Two Slides Per View

Three Slides Per View

Progress Bar Customization

Top Position with Custom Color

Bottom Position with Custom Color

Event Handlers

Slide Change Callback

Swiper Instance Callback

Advanced Configuration

Custom Swiper Props

Responsive Configuration

Examples

Basic Carousel

Carousel with Text

Autoplay Carousel

Crossfade Carousel

Progress Bar Carousel

Data Structure

slidesWithText Array

slides Array

Styling

Accessibility

Best Practices

Common Use Cases

Related Components