ImageCarousel

A responsive image carousel built on Embla Carousel. Features looping navigation, dot indicators, previous/next buttons that appear on hover, and automatic fallback handling for broken images.

Import

import { ImageCarousel } from '@wavebooking/aqua-fusion';

Preview

Live PreviewOpen in Storybook

Loading preview...

Usage

<ImageCarousel
  images={['/img/photo1.jpg', '/img/photo2.jpg', '/img/photo3.jpg']}
  alt="Surf lesson"
/>

With fallback image

<ImageCarousel
  images={['/img/photo1.jpg', '/img/broken-link.jpg']}
  fallbackSrc="/images/placeholder.jpg"
  alt="Lesson photos"
/>

Fit mode

Use mode="fit" to fill the parent container instead of using an aspect ratio. The parent must have a defined height.

<div className="h-64">
  <ImageCarousel
    images={['/img/photo1.jpg', '/img/photo2.jpg']}
    mode="fit"
    alt="Full height carousel"
  />
</div>

Custom aspect ratio

<ImageCarousel
  images={['/img/photo1.jpg', '/img/photo2.jpg']}
  aspectRatio="4/3"
  alt="Square-ish carousel"
/>

Props

Prop	Type	Default	Description
`images`*	string[]	-	Array of image URLs to display in the carousel.
`mode`	'aspect' \| 'fit'	`'aspect'`	Display mode. "aspect" uses an aspect ratio container, "fit" fills the parent height.
`aspectRatio`	string	`'16/9'`	CSS aspect ratio when mode is "aspect" (e.g. "16/9", "4/3").
`fallbackSrc`	string	-	Fallback image shown when an individual image fails to load, or when the images array is empty.
`alt`	string	-	Base alt text for images. For multiple images, " - Photo N of M" is appended automatically.
`className`	string	-	Additional CSS classes for the carousel container.