Autoplay

View plugin on GitHub

This plugin is used to extend Embla Carousel with autoplay functionality.

Example

Installation

Start by installing the npm package and save it to your dependencies:

npm install embla-carousel-autoplay --save

Options

Below follows an exhaustive list of all Autoplay options and their default values.

active

Type:boolean
Default: true
{ active: false | true }

Setting this to false will not activate or deactivate the plugin. Useful when used together with the breakpoints option to toggle the plugin active/inactive depending on media queries.

breakpoints

Type:AutoplayOptionsType
Default: {}
{   delay: 4000,  '(min-width: 768px)': { delay: 2000 }}

An object with options that will be applied for a given breakpoint by overriding the options at the root level.

Note: If multiple queries match, they will be merged. And when breakpoint options clash, the last one in the list has precedence.

delay

Type:number | (snapList: number[], emblaApi: EmblaCarouselType) => number[]
Default: 4000
{ delay: 4000 | (snapList) => snapList.map((_, index) => index * 1000) }

Choose a delay between transitions in milliseconds. If you pass a number, the same delay will be applied to all transitions. If you pass a function, you can return an array of numbers based on the snapList parameter and set different delays for each scroll snap.

jump

Type:boolean
Default: false
{ jump: true | false }

When set to true true, autoplay will do instant slide transitions when advancing.

playOnInit

Type:boolean
Default: true
{ playOnInit: true | false }

If set to false, you'll have to start autoplay manually by calling the play method. It's useful to set this to false when you want full control over the timing. For example, when building an autoplay progress bar.

stopOnInteraction

Type:boolean
Default: true
{ stopOnInteraction: true | false }

If set to false, autoplay will not be disabled after drag interactions, and it will restart every time after an interaction.

stopOnMouseEnter

Type:boolean
Default: false
{ stopOnMouseEnter: true | false }

When enabled, autoplay will stop when a mouse pointer enters the Embla Carousel container. If stopOnInteraction is also false, autoplay will resume when the mouse leaves the carousel container.

stopOnFocusIn

Type:boolean
Default: true
{ stopOnFocusIn: true | false }

When enabled, autoplay will stop when a focusable element inside the carousel recieves focus. If stopOnInteraction is false, autoplay will resume when the user leaves focus.

stopOnLastSnap

Type:boolean
Default: false
{ stopOnLastSnap: true | false }

If this parameter is enabled, autoplay will stop when it reaches last slide.

rootNode

Type:(emblaRoot: HTMLElement) => HTMLElement | null
Default: null
{ rootNode: null | (emblaRoot) => emblaRoot.parentElement }

The node that should respond to user interactions like stopOnMouseEnter and stopOnInteraction. If this is omitted, the node that wraps the Embla Carousel will be used as default.

Methods

Below follows an exhaustive list of all Autoplay methods with their respective parameters and return values.

play

Parameters:(jump?: boolean)
Returns: void
emblaApi.plugins().autoplay?.play(true | false)

Start autoplay. Set the jump parameter to true when you want autoplay to do instant slide transitions when advancing. Please note that providing a value to this method vill override the jump option.

stop

Parameters:none
Returns: void
emblaApi.plugins().autoplay?.stop()

Stop autoplay.

reset

Parameters:none
Returns: void
emblaApi.plugins().autoplay?.reset()

Resets the timer and starts over. This will only take effect if autoplay is already active. If autoplay is stopped, this method won't do anything.

isPlaying

Parameters:none
Returns: boolean
emblaApi.plugins().autoplay?.isPlaying()

Returns a boolean whether autoplay is playing or not.

timeUntilNext

Parameters:none
Returns: number | null
emblaApi.plugins().autoplay?.timeUntilNext()

If the autoplay timer is active, this will return a number representing the time left until the autoplay scrolls to the next snap. If the timer is not active, this will return null. Use this together with the autoplay:timerset and autoplay:timerstopped events to create a custom progress bar for autoplay.

If you're using a reactive wrapper for Embla Carousel like embla-carousel-react and building an autoplay progress bar, you probably want to set playOnInit to false and call the play method manually to fully control the timing.


This is because the autoplay plugin will start playing as soon as it's initialized, which might not be what you want in these cases.

Events

Below follows an exhaustive list of all Autoplay events together with information about how they work.

autoplay:play

emblaApi.on('autoplay:play', (emblaApi) => {})

Fires when autoplay starts playing. When this event is triggered, the autoplay timer is active, and autoplay will select the next scroll snap and start scrolling to it when the delay has passed.

autoplay:stop

emblaApi.on('autoplay:stop', (emblaApi) => {})

Fires when autoplay stops playing. When this event is triggered, the autoplay timer is not active anymore.

autoplay:select

emblaApi.on('autoplay:select', (emblaApi) => {})

Fires directly after autoplay selects the next scroll snap and starts scrolling to it.

autoplay:timerset

emblaApi.on('autoplay:timerset', (emblaApi) => {})

Fires when the autoplay timer is set. As soon as the timer is set, countdown to autoplay to the next scroll snap will begin.

autoplay:timerstopped

emblaApi.on('autoplay:timerstopped', (emblaApi) => {})

Fires when the autoplay timer is stopped.

Edit this page on GitHub