Skip to content

Carousel

A Vaadin Flow add-on that provides a responsive carousel (slideshow) component with autoplay, swipe, and programmatic navigation.

Overview

Use the Carousel add-on when you need to display a sequence of content panels — images, cards, or any Vaadin component — that users can browse through by swiping, clicking navigation arrows, or navigating programmatically from the server side.

Features

  • Display any Vaadin component as a slide.
  • Autoplay with configurable slide duration.
  • Touch swipe support (can be disabled).
  • Navigation circles (can be hidden).
  • Programmatic navigation: next, previous, or jump to a specific position.
  • Server-side SlideChangeEvent with the current slide index.
  • Fluent API for concise configuration.
  • Theme and size customization via HasTheme and HasSize.

Supported versions

Add-on version Vaadin version
3.x 14–25

Installation

From the Vaadin Directory

Available in the Vaadin Directory.

Maven dependency

<dependency>
    <groupId>com.flowingcode.addons.carousel</groupId>
    <artifactId>carousel-addon</artifactId>
    <version>X.Y.Z</version>
</dependency>

Replace X.Y.Z with the latest released version. Add the Vaadin add-ons repository to your pom.xml:

<repository>
    <id>vaadin-addons</id>
    <url>https://maven.vaadin.com/vaadin-addons</url>
</repository>

For snapshot builds, see maven.flowingcode.com/snapshots.

JavaDoc is published at javadoc.flowingcode.com.

Usage

Create Slide instances wrapping any Vaadin component, then build a Carousel:

import com.flowingcode.vaadin.addons.carousel.Carousel;
import com.flowingcode.vaadin.addons.carousel.Slide;

Slide s1 = new Slide(new Span("Slide 1"));
Slide s2 = new Slide(new Span("Slide 2"));
Slide s3 = new Slide(new Span("Slide 3"));

Carousel carousel = new Carousel(s1, s2, s3);
carousel.setWidth("100%");
carousel.setHeight("180px");

Use the fluent API to configure autoplay and appearance:

Carousel carousel = new Carousel(s1, s2, s3)
    .withAutoProgress()
    .withSlideDuration(4)
    .withStartPosition(1)
    .withoutSwipe()
    .withoutNavigation();

Listen to slide changes on the server side:

carousel.addChangeListener(e ->
    Notification.show("Now on slide: " + e.getPosition()));

Navigate programmatically:

carousel.moveNext();
carousel.movePrev();
carousel.movePos(2);

Special configuration when using Spring

When running on Spring, allow-list the com.flowingcode package so Vaadin Flow can discover the add-on's components. See Common configuration for details.

API reference

Headline types exposed by the add-on:

  • Carousel — the slideshow component; implements HasSize and HasTheme.
  • Carousel(Slide... slides) — creates a carousel with the given slides.
  • setSlides(Slide[] slides) / getSlides() — replace or retrieve the current slides.
  • setAutoProgress(boolean) / isAutoProgress() — enable or disable autoplay.
  • setSlideDuration(int) / getSlideDuration() — set the slide duration in seconds (default: 2).
  • setStartPosition(int) / getStartPosition() — set the initial slide index.
  • setDisableSwipe(boolean) / isDisableSwipe() — disable touch swipe.
  • setHideNavigation(boolean) / isHideNavigation() — hide navigation circles.
  • withAutoProgress(), withSlideDuration(int), withStartPosition(int), withoutSwipe(), withoutNavigation() — fluent setters.
  • moveNext(), movePrev(), movePos(int) — programmatic navigation.

  • addChangeListener(ComponentEventListener<SlideChangeEvent>) — listen to slide changes; returns Registration.

  • Slide — a single slide; implements HasComponents.

  • Slide(Component... components) — wraps any Vaadin component(s) as a slide.

  • Carousel.SlideChangeEvent — fired when the active slide changes.

  • getPosition() — returns the index of the new active slide as a String.

For the full API surface, browse the published JavaDoc.

Demo

A live demo is available at addonsv25.flowingcode.com/carousel. To run the demo locally:

git clone https://github.com/FlowingCode/CarouselAddon.git
cd CarouselAddon
mvn clean install jetty:run

Then open http://localhost:8080/.

Source code

CarouselAddon on GitHub — distributed under Apache License 2.0.