Carousel

Overview

Carousels display rotating images or content with navigation arrows, indicators, and optional autoplay.

Key Features

• Autoplay - Automatic slide advancement with configurable interval
• Navigation - Arrow buttons and dot indicators
• Animations - Slide or fade transitions
• Loop Mode - Continuous cycling through slides

const carousel = Domma.elements.carousel('#carousel', {
    autoplay: true,
    interval: 5000,
    loop: true
});

Getting Started

Add a carousel to your page in three simple steps

Step 1: Add HTML Structure

Create the carousel HTML with .carousel container and slides:

<div id="my-carousel" class="carousel">
    <div class="carousel-track">
        <div class="carousel-slide">
            <img src="slide1.jpg" alt="Slide 1">
        </div>
        <div class="carousel-slide">
            <img src="slide2.jpg" alt="Slide 2">
        </div>
        <div class="carousel-slide">
            <img src="slide3.jpg" alt="Slide 3">
        </div>
    </div>
</div>

Step 2: Include Domma

Add Domma CSS and JavaScript to your page:

<!-- CSS -->
<link rel="stylesheet" href="dist/domma.css">
<link rel="stylesheet" href="dist/elements.css">

<!-- JavaScript -->
<script src="dist/domma.min.js"></script>

Step 3: Initialize the Carousel

Call Domma.elements.carousel() to activate the carousel:

Domma.elements.carousel('#my-carousel', {
    autoplay: true,      // Auto-advance slides
    interval: 5000,      // 5 seconds between slides
    loop: true,          // Loop back to start
    showArrows: true,    // Show navigation arrows
    showIndicators: true // Show dot indicators
});

Note: The carousel requires the HTML structure above. The JavaScript adds navigation controls (arrows and indicators), autoplay functionality, and smooth transitions between slides.

Quick Start

<div id="quick-carousel" class="carousel">
    <div class="carousel-track">
        <div class="carousel-slide">
            Slide 1
        </div>
        <div class="carousel-slide">
            Slide 2
        </div>
        <div class="carousel-slide">
            Slide 3
        </div>
    </div>
</div>

/**
 * Quick Start - from public/showcase/elements/carousel.
 */
export function mount(root) {
    E.carousel(root.querySelector('#quick-carousel'), {autoplay: false, showArrows: true, showIndicators: true});
}

Examples

With Autoplay

<div id="autoplay-carousel" class="carousel">
    <div class="carousel-track">
        <div class="carousel-slide">
            Auto 1
        </div>
        <div class="carousel-slide">
            Auto 2
        </div>
        <div class="carousel-slide">
            Auto 3
        </div>
    </div>
</div>

/**
 * With Autoplay - from public/showcase/elements/carousel.
 */
export function mount(root) {
    E.carousel(root.querySelector('#autoplay-carousel'), {autoplay: true, interval: 3000, pauseOnHover: true});
}

Transitions

Three transition modes are available via the animation option, and any CSS timing function can be supplied via animationEasing.

Fade

Active slide opacity drops to zero before the incoming slide fades in - a clean swap with no overlap.

<div id="fade-carousel" class="carousel transition-demo">
    <div class="carousel-track">
        <div class="carousel-slide demo-gradient-aurora-1">
            <div class="slide-eyebrow">Chapter one</div>
            <h3 class="slide-title">Aurora Rising</h3>
            <p class="slide-sub">Deep amethyst meets electric blue. A clean fade lets each composition breathe.</p>
        </div>
        <div class="carousel-slide demo-gradient-aurora-2">
            <div class="slide-eyebrow">Chapter two</div>
            <h3 class="slide-title">Ember Bloom</h3>
            <p class="slide-sub">Magenta sun bleeding into molten orange - no motion to compete with the colour.</p>
        </div>
        <div class="carousel-slide demo-gradient-aurora-3">
            <div class="slide-eyebrow">Chapter three</div>
            <h3 class="slide-title">Glacier Spring</h3>
            <p class="slide-sub">Arctic teal washing into fresh moss. The swap is decisive, not gradual.</p>
        </div>
    </div>
</div>

/**
 * Fade - from public/showcase/elements/carousel.
 */
export function mount(root) {
    E.carousel(root.querySelector('#fade-carousel'), {animation: 'fade', animationDuration: 900, autoplay: true, interval: 4000, pauseOnHover: true});
}

Domma.elements.carousel('#fade-carousel', {
    animation: 'fade',
    animationDuration: 900,
    autoplay: true,
    interval: 4000,
    pauseOnHover: true
});

Crossfade

Outgoing and incoming slides transition opacity at the same time, briefly overlapping. Softer, more cinematic - particularly good for hero imagery and feature reels.

<div id="crossfade-carousel" class="carousel transition-demo">
    <div class="carousel-track">
        <div class="carousel-slide demo-gradient-dusk-1">
            <div class="slide-eyebrow">Reel · 01</div>
            <h3 class="slide-title">Midnight Coast</h3>
            <p class="slide-sub">Indigo dissolving into slate - the overlap reads as the camera blinking.</p>
        </div>
        <div class="carousel-slide demo-gradient-dusk-2">
            <div class="slide-eyebrow">Reel · 02</div>
            <h3 class="slide-title">Royal Saffron</h3>
            <p class="slide-sub">Imperial purple bleeding into pollen gold. Watch both gradients share the frame.</p>
        </div>
        <div class="carousel-slide demo-gradient-dusk-3">
            <div class="slide-eyebrow">Reel · 03</div>
            <h3 class="slide-title">Sunset Bazaar</h3>
            <p class="slide-sub">Cinnamon flame fading through to deep ruby. Slow easing makes the overlap luxurious.</p>
        </div>
    </div>
</div>

/**
 * Crossfade - from public/showcase/elements/carousel.
 */
export function mount(root) {
    E.carousel(root.querySelector('#crossfade-carousel'), {animation: 'crossfade', animationDuration: 1400, animationEasing: 'ease-in-out', autoplay: true, interval: 4500, pauseOnHover: true});
}

Domma.elements.carousel('#crossfade-carousel', {
    animation: 'crossfade',
    animationDuration: 1400,
    animationEasing: 'ease-in-out',
    autoplay: true,
    interval: 4500,
    pauseOnHover: true
});

Custom Easing

Any CSS timing function works - 'linear', 'ease-in-out', 'cubic-bezier(...)'. Here the slide overshoots then settles, courtesy of a bouncy cubic-bezier.

<div id="easing-carousel" class="carousel easing-demo">
    <div class="carousel-track">
        <div class="carousel-slide demo-gradient-pop-1">Bounce in</div>
        <div class="carousel-slide demo-gradient-pop-2">Overshoot</div>
        <div class="carousel-slide demo-gradient-pop-3">Settle</div>
    </div>
</div>

/**
 * Custom Easing - from public/showcase/elements/carousel.
 */
export function mount(root) {
    E.carousel(root.querySelector('#easing-carousel'), {animation: 'slide', animationDuration: 900, animationEasing: 'cubic-bezier(0.68, -0.55, 0.27, 1.55)'});
}

Domma.elements.carousel('#easing-carousel', {
    animation: 'slide',
    animationDuration: 900,
    animationEasing: 'cubic-bezier(0.68, -0.55, 0.27, 1.55)'
});

When to choose what: slide for photo galleries where motion implies sequence; fade for content slides where motion would distract; crossfade for hero imagery where the overlap reads as polish.

Best Practices

• Accessibility - Provide alt text for images, pause controls
• Performance - Optimize images, lazy load off-screen slides
• Mobile - Ensure touch swipe gestures work properly

API Reference

Methods

Declarative Configuration

Configure carousels declaratively with $.setup() for cleaner, more maintainable code.

Basic Carousel Setup

$.setup({
    '#hero-carousel': {
        component: 'carousel',
        options: {
            autoplay: true,
            interval: 5000,
            loop: true,
            animation: 'slide'
        }
    }
});

Product Gallery with Events

$.setup({
    '.product-gallery': {
        component: 'carousel',
        options: {
            showArrows: true,
            showIndicators: true,
            pauseOnHover: true,
            onChange: (index, instance) => {
                // Update product URL
                history.replaceState(null, '', `?slide=${index}`);

                // Track view
                analytics.track('Product Image Viewed', {
                    imageIndex: index
                });
            }
        }
    }
});

Side-by-Side: Programmatic vs Declarative

Programmatic

const carousel = Domma.elements.carousel(
    '#carousel',
    {
        autoplay: true,
        interval: 5000
    }
);

carousel.play();

Declarative (Recommended)

$.setup({
    '#carousel': {
        component: 'carousel',
        options: {
            autoplay: true,
            interval: 5000
        }
    }
});

CSS Customisation

Override these CSS variables to customise Carousel appearance and match your design system.

Example Override

/* Custom control colour - target via CSS */
.carousel-controls button {
    background: rgba(0,0,0,0.5);
    color: white;
}

Full CSS Customisation Cheat-Sheet →

Related Elements

<a href="/showcase/elements/modal" class="card card-hover">
    <div class="card-body">
        <h3 class="card-title">Modal</h3>
        <p class="card-text">Display carousel in modal lightbox</p>
    </div>
</a>