Carousel

Carousel is a flexible content slider for image galleries, hero banners, product showcases, onboarding flows, testimonials, and any interface that needs to cycle through multiple items inside one visual area. The component supports slide and fade modes, pointer-based swipe gestures, autoplay, controls, pager dots, thumbnails, looping, and direct JavaScript control.

Getting Started

Create a .carousel root, place every slide inside .carousel-items, and use .item for each individual slide. Use class in HTML examples and className in React examples.

import { Carousel } from 'frontalign';

const carousel = Carousel.create('#featured-carousel', {
  mode: 'slide',
  loop: true,
  controls: true,
  pager: true,
  swipe: true,
  autoplay: {
    enabled: true,
    interval: 4000,
    pauseOnHover: true,
    pauseOnSwipe: true,
  },
});

Structure

The carousel structure is intentionally predictable: one root, one list wrapper, and one .item per slide. Controls, pager dots, and thumbnails are injected by the runtime when their options are enabled.

Configuration Options

Carousel options control the transition mode, navigation UI, swipe support, autoplay behavior, and thumbnail rendering.

Fade Mode

Fade mode stacks slides and transitions by opacity. It is ideal for hero banners, marketing sections, and calm background image rotations. When fade mode is enabled, the runtime adds .is-fade to the root and toggles .is-active on the visible .item.

{
  mode: 'fade',
  autoplay: {
    enabled: true,
    interval: 5000,
    pauseOnHover: true
  }
}

Thumbnail Navigation

Thumbnails render a .thumbnails strip. Each thumbnail is generated from the <img> element inside the matching slide. Use this mode for product galleries, portfolios, and image-heavy interfaces where preview navigation is useful.

<div class="carousel" id="thumbnail-carousel">
  <ul class="carousel-items">
    <li class="item">
      <img src="/images/gallery-1.jpg" alt="Gallery item one" />
    </li>
    <li class="item">
      <img src="/images/gallery-2.jpg" alt="Gallery item two" />
    </li>
    <li class="item">
      <img src="/images/gallery-3.jpg" alt="Gallery item three" />
    </li>
  </ul>
</div>

{
  pager: false,
  thumbnails: {
    enabled: true,
    clickable: true
  }
};

Swipe Support

Carousel uses the native Pointer Events API for cross-device swipe detection. It supports touch screens, trackpads, and mouse drag interactions. A swipe is recognized when horizontal movement passes the internal threshold, the gesture is long enough, and horizontal movement is dominant over vertical movement.

{
  swipe: true,
  autoplay: {
    pauseOnSwipe: true
  }
};

Autoplay

Autoplay advances the carousel at a configured interval and pauses during user interaction when enabled. When users manually navigate with controls, pager dots, or thumbnails, autoplay restarts from the current interval so the rhythm stays consistent.

{
  autoplay: {
    enabled: true,
    interval: 5000,
    pauseOnHover: true,
    pauseOnSwipe: true
  }
};

Instance Methods

Direct instances expose lifecycle methods for initialization and cleanup.

const carousel = new Carousel('#featured-carousel', options);

carousel.build();

// Later, when the component or page is destroyed
carousel.dispose();

Static Instance Management

Every active carousel is stored in Carousel.instances, a static Map that lets you inspect or control instances globally.

import { Carousel } from 'frontalign';

const allCarousels = Carousel.instances;

Carousel.instances.forEach((instance, id) => {
  console.log(id, instance);
});

Use this for debugging, admin previews, documentation sandboxes, or global teardown logic.

Accessibility

Carousel content should remain understandable for keyboard, screen reader, and reduced-motion users. Keep slide content semantic and always provide meaningful alt text for images.

Class Reference

Use this reference when building custom carousel markup, debugging runtime output, or styling advanced carousel layouts.

Best Practices

Use slide mode for galleries and structured cards. Use fade mode for hero banners and visual storytelling. Keep autoplay slow enough for real reading, keep navigation controls available, and clean up instances in SPA environments with .dispose().

When thumbnails are enabled, disable pager intentionally so the navigation pattern stays clear and predictable.