Events
Embla Carousel exposes custom events that can be hooked on to. Listening to events allows for extending the carousel.
Usage
You need an initialized carousel in order to make use of events. Events will only be fired during the lifecycle of a carousel and added event listeners will persist even when you hard reset the carousel with the reInit method.
Adding event listeners
After initializing a carousel, we're going to subscribe to the select event in the following example:
import EmblaCarousel from 'embla-carousel'
const emblaApi = EmblaCarousel(emblaNode, { loop: true })
const onSelect = (emblaApi, eventName) => { console.log(`Embla just triggered ${eventName}!`)}
emblaApi.on('select', onSelect)
import { useCallback, useEffect } from 'react'import useEmblaCarousel from 'embla-carousel-react'
export const EmblaCarousel = () => { const [emblaRef, emblaApi] = useEmblaCarousel({ loop: true })
const onSelect = useCallback((emblaApi, eventName) => { console.log(`Embla just triggered ${eventName}!`) }, [])
useEffect(() => { if (emblaApi) emblaApi.on('select', onSelect) }, [emblaApi, onSelect])
// ...}
<script> import { watchEffect } from 'vue' import emblaCarouselVue from 'embla-carousel-vue'
export default { setup() { const [emblaNode, emblaApi] = emblaCarouselVue({ loop: true })
const onSelect = (emblaApi, eventName) => { console.log(`Embla just triggered ${eventName}!`) }
watchEffect(() => { if (emblaApi.value) emblaApi.value.on('select', onSelect) })
// ... }, }</script>
Removing event listeners
In order to remove an event listener, you'll have to call the off method and make sure to pass the same callback reference you passed to the on method:
import EmblaCarousel from 'embla-carousel'
const emblaApi = EmblaCarousel(emblaNode, { loop: true })
const onSelect = (emblaApi, eventName) => { console.log(`Embla just triggered ${eventName}!`)}
const removeOnSelectListener = () => { emblaApi.off('select', onSelect)}
emblaApi.on('select', onSelect)
import { useCallback, useEffect } from 'react'import useEmblaCarousel from 'embla-carousel-react'
export const EmblaCarousel = () => { const [emblaRef, emblaApi] = useEmblaCarousel({ loop: true })
const onSelect = useCallback((emblaApi, eventName) => { console.log(`Embla just triggered ${eventName}!`) }, [])
const removeOnSelectListener = useCallback(() => { if (emblaApi) emblaApi.off('select', onSelect) }, [emblaApi, onSelect])
useEffect(() => { if (emblaApi) emblaApi.on('select', onSelect) }, [emblaApi, onSelect])
// ...}
<script> import { watchEffect } from 'vue' import emblaCarouselVue from 'embla-carousel-vue'
export default { setup() { const [emblaNode, emblaApi] = emblaCarouselVue({ loop: true })
const onSelect = (emblaApi, eventName) => { console.log(`Embla just triggered ${eventName}!`) }
const removeOnSelectListener = () => { if (emblaApi.value) emblaApi.value.off('select', onSelect) }
watchEffect(() => { if (emblaApi.value) emblaApi.value.on('select', onSelect) })
// ... }, }</script>
Reference
Below follows an exhaustive list of all Embla Carousel events together with information about how they work.
init
Once: yes
Runs when the carousel mounts for the first time. This only fires once which means that it won't fire when the carousel is re-initialized using the reInit method.
reInit
Once: no
Runs when the reInit method is called. When the window is resized, Embla Carousel automatically calls the reInit method which will also fire this event.
destroy
Once: yes
Runs when the carousel has been destroyed using the destroy method. This only fires once and will be the last event the carousel fires.
select
Once: no
Runs when the selected scroll snap changes. The select event is triggered by drag interactions or the scrollNext, scrollPrev or scrollTo methods.
scroll
Once: no
Runs when the carousel is scrolling. It might be a good idea to throttle this if you're doing expensive stuff in your callback function.
settle
Once: no
Runs when the carousel has settled after scroll has been triggered. Please note that this can take longer than you think when dragFree is enabled or when using slow transitions.
resize
Once: no
Runs when the carousel container or the slide sizes change. It's using ResizeObserver under the hood.
slidesChanged
Once: no
Runs when slides are added to, or removed from the carousel container. It's using MutationObserver under the hood.
pointerDown
Once: no
Runs when the user has a pointer down on the carousel. It's triggered by a touchstart
or a mousedown
event.
pointerUp
Once: no
Runs when the user has released the pointer from the carousel. It's triggered by a touchend
or a mouseup
event.