Autoplay

The Autoplay plugin for Embla Carousel allows the carousel to advance automatically at a specified interval. It is designed to be smart, providing options to pause or stop based on user interactions such as mouse entry or clicking.

Installation

To use autoplay, you first need to install the embla-carousel-autoplay package:

npm install embla-carousel-autoplay --save

Usage

Pass the Autoplay() plugin to the third argument of the Embla Carousel constructor.

Vanilla JS

import EmblaCarousel from 'embla-carousel'
import Autoplay from 'embla-carousel-autoplay'

const viewportNode = document.querySelector('.embla__viewport')
const emblaApi = EmblaCarousel(viewportNode, { loop: true }, [Autoplay()])

React

import useEmblaCarousel from 'embla-carousel-react'
import Autoplay from 'embla-carousel-autoplay'

export function EmblaCarousel() {
  const [emblaRef] = useEmblaCarousel({ loop: true }, [Autoplay()])

  return (
    <div className="embla" ref={emblaRef}>
      <div className="embla__container">
        <div className="embla__slide">Slide 1</div>
        <div className="embla__slide">Slide 2</div>
      </div>
    </div>
  )
}

Options

You can configure the behavior of the autoplay by passing an options object to the plugin: Autoplay(options).

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | delay | number | 4000 | The interval between slide changes in milliseconds. | | jump | boolean | false | If true, the carousel will jump to the next slide without animation. | | playOnInit | boolean | true | Start autoplay immediately after initialization. | | stopOnInteraction | boolean | true | Stops autoplay when the user interacts with the carousel (e.g., dragging). | | stopOnMouseEnter | boolean | false | Stops autoplay when the mouse enters the carousel viewport. | | stopOnLastSnap | boolean | false | Stops autoplay when the carousel reaches the last snap point. Only applicable if loop is false. | | rootNode | (emblaRoot: HTMLElement) => HTMLElement | null | A callback that returns the node to attach event listeners to (for interaction/mouse entry). |

Example with Options

Autoplay({
  delay: 5000,
  stopOnInteraction: false,
  stopOnMouseEnter: true,
})

API Methods

The Autoplay plugin exposes its own set of methods, accessible via the plugins() method on the Embla API.

play(resume?: boolean)

Starts autoplay. If resume is true, it will continue from the remaining time of the current interval.

stop()

Stops autoplay.

reset()

Resets the timer and starts autoplay from the beginning of the interval.

isPlaying()

Returns true if autoplay is currently active, false otherwise.

timeUntilNext()

Returns the remaining time in milliseconds until the next slide transition.

Example: Programmatic Control

const emblaApi = EmblaCarousel(viewportNode, options, [Autoplay()])

// Stop autoplay on button click
const stopButton = document.querySelector('.stop-button')
stopButton.addEventListener('click', () => {
  emblaApi.plugins().autoplay.stop()
}, false)

// Check status
console.log(emblaApi.plugins().autoplay.isPlaying())

TypeScript

The plugin provides types for its options and API:

import { AutoplayOptionsType } from 'embla-carousel-autoplay'

const options: AutoplayOptionsType = {
  delay: 3000,
  stopOnInteraction: true
}