Carousel

The Carousel component provides a flexible, smooth, and accessible slideshow built using Embla Carousel. It supports autoplay, fading transitions, customizable alignment, and full control over navigation UI (dots and arrows).

import { Carousel } from "tawuniya/components";

👉 View in Storybook

---

Props

Prop	Type	Default	Description
slides	SlideItem[]	—	Array of slides containing image, title, and description.
title	string	—	Default title used if a slide doesn’t provide one.
description	string	—	Default description used if a slide doesn’t provide one.
alignContent	{ x?: "start" | "center" | "end"; y?: "start" | "center" | "end"; }	{ x: "start", y: "end" }	Controls horizontal and vertical alignment of slide content.
nextIcon	React.ReactNode	<ChevronRight />	Custom icon for the next button.
prevIcon	React.ReactNode	<ChevronLeft />	Custom icon for the previous button.
options	{ loop?: boolean; fade?: boolean; autoPlay?: boolean; delay?: number; startIndex?: number; hideDots?: boolean; hideArrows?: boolean; }	{ loop: true, fade: true, autoPlay: true, delay: 3000 }	Carousel behavior configuration.
classNames	ClassNames	—	Object for overriding internal Tailwind class names.
children	React.ReactNode	—	Optional React nodes to render within each slide (e.g., CTA buttons).
onClick	(slideId: string, slide: SlideItem) => void	—	Callback function to handle slide clicks.

---

Subtypes

SlideItem

Property	Type	Description
id	string	Unique identifier for the slide.
title	string	Slide title.
description	string	Slide description text.
image	string	Background image URL.

ClassNames

Property	Description
className	Root container classes.
containerClassName	Flex container for all slides.
backdropClassName	Background overlay (e.g., black/25).
slideWrapperClassName	Wrapper for each slide.
slideClassName	Inner slide content container.
titleClassName	Title typography classes.
descriptionClassName	Description typography classes.
actionWrapperClassName	Navigation wrapper (arrows and dots).
actionButtonClassName	Navigation button classes.

---

Basic Example

import Carousel from "tawuniya/components/carousel";

const slides = [
  {
    id: "1",
    title: "Discover the Future",
    description: "Explore innovations that redefine tomorrow.",
    image: "/images/slide1.jpg",
  },
  {
    id: "2",
    title: "Smart Solutions",
    description: "Building a connected, intelligent world.",
    image: "/images/slide2.jpg",
  },
];

export default function BasicCarousel() {
  return <Carousel slides={slides} />;
}

---

Center Aligned Content

<Carousel
  slides={slides}
  alignContent={{ x: "center", y: "center" }}
/>

Content is centered both vertically and horizontally.

---

End Aligned (Bottom-Right)

<Carousel
  slides={slides}
  alignContent={{ x: "end", y: "end" }}
/>

Perfect for captions positioned at the bottom-right corner of the slide.

---

With Custom Action Button Inside Slide

<Carousel slides={slides} alignContent={{ x: "start", y: "center" }}>
  <Button variant="primary">Learn More</Button>
</Carousel>

Each slide renders the same children component (here, a CTA button).

---

Fade Transition + Autoplay Disabled

<Carousel
  slides={slides}
  options={{
    fade: true,
    autoPlay: false,
    loop: true,
  }}
/>

Ideal for controlled or manual navigation use cases.

---

Hide Dots and Arrows

<Carousel
  slides={slides}
  options={{
    hideDots: true,
    hideArrows: true,
  }}
/>

Use this when you want a clean, minimal carousel without navigation UI.

---

Custom Icons & Delay

import { ArrowLeft, ArrowRight } from "lucide-react";

<Carousel
  slides={slides}
  nextIcon={<ArrowRight />}
  prevIcon={<ArrowLeft />}
  options={{
    autoPlay: true,
    delay: 5000,
  }}
/>

Customizes icons and increases autoplay delay to 5 seconds.

Styling Example

<Carousel
  slides={slides}
  classNames={{
    containerClassName: "w-[800px]",
    slideClassName: "h-[400px]",
    titleClassName: "text-2xl font-bold",
    descriptionClassName: "text-lg",
    actionButtonClassName: "mt-4",
  }}
/>

Notes

• The component automatically re-initializes when slides or options change.
• Background images should be optimized for better performance.
• Use the classNames prop to adapt the carousel to different layouts or themes.
• For best performance, keep the number of slides reasonable when using fade transitions.

Features

• Fade Transitions: Smooth fade between slides for a polished look.
• Autoplay: Automatically advance slides with configurable delay.
• Navigation Controls: Built-in arrows and pagination dots, customizable or hidable.
• Content Alignment: Align titles, descriptions, and children (x: start/center/end, y: start/center/end).
• Custom Children: Inject React elements like buttons or links into slides.
• Styling Flexibility: Override classes via classNames prop for full theming.
• Responsive: Automatically scales for desktop, tablet, and mobile.
• Accessible: Works with screen readers and keyboard navigation.
• Dynamic Updates: Reinitializes when slides change.