Methods
Embla Carousel provides a set of methods that let you extend and control the carousel programmatically.
Usage
Methods require an initialized carousel instance. They remain accessible while the instance is active and are invalid after calling destroy.
Calling methods
In the following example, the slideNodes method is called and logged to the console as soon as the carousel has been initialized:
import EmblaCarousel from 'embla-carousel'
const wrapperNode = document.querySelector('.embla')const viewportNode = wrapperNode.querySelector('.embla__viewport')
const emblaApi = EmblaCarousel(viewportNode, { loop: true })
console.log(emblaApi.slideNodes())<div class="embla"> <div class="embla__viewport"> <div class="embla__container"> <div class="embla__slide">Slide 1</div> <div class="embla__slide">Slide 2</div> <div class="embla__slide">Slide 3</div> </div> </div></div>import React, { useEffect } from 'react'import useEmblaCarousel from 'embla-carousel-react'
export function EmblaCarousel() { const [emblaRef, emblaApi] = useEmblaCarousel({ loop: true })
useEffect(() => { if (!emblaApi) return console.log(emblaApi.slideNodes()) }, [emblaApi])
return ( <div className="embla"> <div className="embla__viewport" ref={emblaRef}> <div className="embla__container"> <div className="embla__slide">Slide 1</div> <div className="embla__slide">Slide 2</div> <div className="embla__slide">Slide 3</div> </div> </div> </div> )}<script setup>import { watch } from 'vue'import useEmblaCarousel from 'embla-carousel-vue'
const [emblaRef, emblaApi] = useEmblaCarousel({ loop: true })
watch( emblaApi, (api) => { if (!api) return console.log(api.slideNodes()) }, { immediate: true })</script>
<template> <div class="embla"> <div class="embla__viewport" ref="emblaRef"> <div class="embla__container"> <div class="embla__slide">Slide 1</div> <div class="embla__slide">Slide 2</div> <div class="embla__slide">Slide 3</div> </div> </div> </div></template>import { createEffect, on } from 'solid-js'import useEmblaCarousel from 'embla-carousel-solid'
export function EmblaCarousel() { const [emblaRef, emblaApi] = useEmblaCarousel(() => ({ loop: true }))
createEffect( on(emblaApi, (api) => { if (!api) return console.log(api.slideNodes()) }) )
return ( <div class="embla"> <div class="embla__viewport" ref={emblaRef}> <div class="embla__container"> <div class="embla__slide">Slide 1</div> <div class="embla__slide">Slide 2</div> <div class="embla__slide">Slide 3</div> </div> </div> </div> )}<script> import useEmblaCarousel from 'embla-carousel-svelte'
let options = { loop: true }
const onInit = (event) => { emblaApi = event.detail console.log(emblaApi.slideNodes()) }</script>
<div class="embla"> <div class="embla__viewport" on:emblainit={onInit} use:useEmblaCarousel={{ options }} > <div class="embla__container"> <div class="embla__slide">Slide 1</div> <div class="embla__slide">Slide 2</div> <div class="embla__slide">Slide 3</div> </div> </div></div>Note: Starting with Svelte 5, the on: event handlers have been
deprecated. However, on:emblainit will remain for backward
compatibility.
TypeScript
The EmblaCarouselType is obtained directly from the core package embla-carousel and used like so:
import EmblaCarousel, { EmblaCarouselType } from 'embla-carousel'
const wrapperNode = <HTMLElement>document.querySelector('.embla')const viewportNode = <HTMLElement>wrapperNode.querySelector('.embla__viewport')
const emblaApi = EmblaCarousel(viewportNode, { loop: true })
const logSelectedSnap = (emblaApi: EmblaCarouselType): void => { console.log(emblaApi.selectedScrollSnap())}
emblaApi.on('select', logSelectedSnap)<div class="embla"> <div class="embla__viewport"> <div class="embla__container"> <div class="embla__slide">Slide 1</div> <div class="embla__slide">Slide 2</div> <div class="embla__slide">Slide 3</div> </div> </div></div>import React, { useEffect } from 'react'import { EmblaCarouselType } from 'embla-carousel'import useEmblaCarousel from 'embla-carousel-react'
export function EmblaCarousel() { const [emblaRef, emblaApi] = useEmblaCarousel({ loop: true })
const logSelectedSnap = (emblaApi: EmblaCarouselType) => { console.log(emblaApi.selectedScrollSnap()) }
useEffect(() => { if (!emblaApi) return emblaApi.on('select', logSelectedSnap) }, [emblaApi])
return ( <div className="embla"> <div className="embla__viewport" ref={emblaRef}> <div className="embla__container"> <div className="embla__slide">Slide 1</div> <div className="embla__slide">Slide 2</div> <div className="embla__slide">Slide 3</div> </div> </div> </div> )}If you're using pnpm, you need to install embla-carousel as a
devDependency when importing types from it like demonstrated above.
This is because even though embla-carousel-react has embla-carousel as
a dependency, pnpm makes nested dependencies inaccessible by design.
<script setup lang="ts">import { watch } from 'vue'import { EmblaCarouselType } from 'embla-carousel'import useEmblaCarousel from 'embla-carousel-vue'
const [emblaRef, emblaApi] = useEmblaCarousel({ loop: true })
const logSelectedSnap = (emblaApi: EmblaCarouselType) => { console.log(emblaApi.selectedScrollSnap())}
watch( emblaApi, (api) => { if (!api) return api.on('select', logSelectedSnap) }, { immediate: true })</script>
<template> <div class="embla"> <div class="embla__viewport" ref="emblaRef"> <div class="embla__container"> <div class="embla__slide">Slide 1</div> <div class="embla__slide">Slide 2</div> <div class="embla__slide">Slide 3</div> </div> </div> </div></template>If you're using pnpm, you need to install embla-carousel as a
devDependency when importing types from it like demonstrated above.
This is because even though embla-carousel-vue has embla-carousel as a
dependency, pnpm makes nested dependencies inaccessible by design.
import { createEffect, on } from 'solid-js'import { EmblaCarouselType } from 'embla-carousel'import useEmblaCarousel from 'embla-carousel-solid'
export function EmblaCarousel() { const [emblaRef, emblaApi] = useEmblaCarousel(() => ({ loop: true }))
const logSelectedSnap = (emblaApi: EmblaCarouselType) => { console.log(emblaApi.selectedScrollSnap()) }
createEffect( on(emblaApi, (api) => { if (!api) return api.on('select', logSelectedSnap) }) )
return ( <div class="embla"> <div class="embla__viewport" ref={emblaRef}> <div class="embla__container"> <div class="embla__slide">Slide 1</div> <div class="embla__slide">Slide 2</div> <div class="embla__slide">Slide 3</div> </div> </div> </div> )}If you're using pnpm, you need to install embla-carousel as a
devDependency when importing types from it like demonstrated above.
This is because even though embla-carousel-solid has embla-carousel as
a dependency, pnpm makes nested dependencies inaccessible by design.
<script lang="ts"> import { EmblaCarouselType, EmblaOptionsType } from 'embla-carousel' import useEmblaCarousel from 'embla-carousel-svelte'
let emblaApi: EmblaCarouselType let options: EmblaOptionsType = { loop: true }
const logSelectedSnap = (emblaApi: EmblaCarouselType): void => { console.log(emblaApi.selectedScrollSnap()) }
const onInit = (event: CustomEvent<EmblaCarouselType>): void => { emblaApi = event.detail emblaApi.on('select', logSelectedSnap) }</script>
<div class="embla"> <div class="embla__viewport" on:emblainit={onInit} use:useEmblaCarousel={{ options }} > <div class="embla__container"> <div class="embla__slide">Slide 1</div> <div class="embla__slide">Slide 2</div> <div class="embla__slide">Slide 3</div> </div> </div></div>Note: Starting with Svelte 5, the on: event handlers have been
deprecated. However, on:emblainit will remain for backward
compatibility.
If you're using pnpm, you need to install embla-carousel as a
devDependency when importing types from it like demonstrated above.
This is because even though embla-carousel-svelte has embla-carousel
as a dependency, pnpm makes nested dependencies inaccessible by design.
Reference
Below follows an exhaustive list of all Embla Carousel methods with their respective parameters and return values.
rootNode
noneHTMLElementemblaApi.rootNode()Get the root node that holds the scroll container with slides inside. This method can be useful when you need to manipulate the root element dynamically or similar.
containerNode
noneHTMLElementemblaApi.containerNode()Get the container node that holds the slides. This method can be useful when you need to manipulate the container element dynamically or similar.
slideNodes
noneHTMLElement[]emblaApi.slideNodes()Get all the slide nodes inside the container. This method can be useful when you need to manipulate the slide elements dynamically or similar.
scrollNext
(jump?: boolean)voidemblaApi.scrollNext(true | false)Scroll to the next snap point if possible. When loop is disabled and the carousel has reached the last snap point, this method won't do anything. Set the jump parameter to true when you want to go to the next slide instantly.
scrollPrev
(jump?: boolean)voidemblaApi.scrollPrev(true | false)Scroll to the previous snap point if possible. When loop is disabled and the carousel has reached the first snap point, this method won't do anything. Set the jump parameter to true when you want to go to the previous slide instantly.
scrollTo
(index: number, jump?: boolean)voidemblaApi.scrollTo(0, true | false)Scroll to a snap point by its unique index. If loop is enabled, Embla Carousel will choose the closest way to the target snap point. Set the jump parameter to true when you want to go to the desired slide instantly.
canScrollNext
nonebooleanemblaApi.canScrollNext()Check the possiblity to scroll to a next snap point. If loop is enabled and the container holds any slides, this will always return true.
canScrollPrev
nonebooleanemblaApi.canScrollPrev()Check the possiblity to scroll to a previous snap point. If loop is enabled and the container holds any slides, this will always return true.
selectedScrollSnap
nonenumberemblaApi.selectedScrollSnap()Get the index of the selected snap point.
previousScrollSnap
nonenumberemblaApi.previousScrollSnap()Get the index of the previously selected snap point.
scrollSnapList
nonenumber[]emblaApi.scrollSnapList()Get an array containing all the snap point positions. Each position represents how far the carousel needs to progress in order to reach this position.
scrollProgress
nonenumberemblaApi.scrollProgress()Check how far the carousel has scrolled of its scrollable length from 0 - 1. For example, 0.5 equals 50%. For example, this can be useful when creating a scroll progress bar.
slidesInView
nonenumber[]emblaApi.slidesInView()Get slide indexes visible in the carousel viewport. Honors the inViewThreshold option.
slidesNotInView
nonenumber[]emblaApi.slidesNotInView()Get slide indexes not visible in the carousel viewport. Honors the inViewThreshold option.
internalEngine
noneEmblaEngineTypeemblaApi.internalEngine()Exposes almost all internal functionality used by Embla. Useful when creating plugins or similar.
Note: Please refrain from creating bug reports related to this method. If you're using this and running into problems, it's a 99.8% chance that you don't understand how this works. Use at your own risk.
reInit
(options?: EmblaOptionsType, plugins?: EmblaPluginType[])voidemblaApi.reInit({ loop: false }, [Autoplay()])Hard reset the carousel after it has been initialized. This method allows for changing options and plugins after initializing a carousel.
Note: Passed options will be merged with current options, but passed plugins will replace current plugins.
plugins
noneEmblaPluginsTypeemblaApi.plugins()Returns an object with key value pairs where the keys are the plugin names, and the plugin API:s are the values.
destroy
nonevoidemblaApi.destroy()Destroy the carousel instance permanently. This is a one way operation and is intended to be used as a cleanup measure when the carousel instance isn't needed anymore.
on
(event: EmblaEventType, callback: EmblaEventCallbackType)voidemblaApi.on('select', (emblaApi, event) => {})Subscribe to an Embla specific event with a callback. Added event listeners will persist even if reInit is called, either until the carousel is destroyed or the event is removed with the off method.
off
(event: EmblaEventType, callback: EmblaEventCallbackType)voidemblaApi.off('select', (emblaApi, event) => {})Unsubscribe from an Embla specific event . Make sure to pass the same callback reference when the callback was added with the on method.
emit
(event: EmblaEventType)voidemblaApi.emit('select')Emits an embla event. This doesn't trigger any internal Embla functionality.