[General]: v8 to v9 Migration Guide (breaking changes)

[davidjerleke]

Migration Guide (Breaking Changes Only)

This guide lists only breaking changes introduced in v9.0.0 and shows how to achieve the same behavior as in v8.6.0.

---

1. Core API

1.1 Method Renames (Breaking)

v8	v9
scrollNext()	goToNext()
scrollPrev()	goToPrev()
canScrollNext()	canGoToNext()
canScrollPrev()	canGoToPrev()
scrollTo(index, jump?, direction?)	goTo(index, instant?, direction?)
scrollSnapList()	snapList()
selectedScrollSnap()	selectedSnap()
previousScrollSnap()	previousSnap()
slidesNotInView()	❌ Removed

1.2 Updated Usage Examples

emblaApi.goToNext(/* instant?: boolean */)
emblaApi.goToPrev(/* instant?: boolean */)

emblaApi.goTo(targetIndex, /* instant?: boolean */, /* 'forward' | 'backward' */)

emblaApi.snapList()
emblaApi.selectedSnap()
emblaApi.previousSnap()

1.3 Replacement for slidesNotInView()

const inView = emblaApi.slidesInView()
const all = emblaApi.slideNodes().map((_, i) => i)
const notInView = all.filter((i) => !inView.includes(i))

Note: The instant-scroll flag remains a boolean (jump → instant).

2. Events

2.1 General Event Changes (Breaking)

• Event names are lowercase.
• The init event has been removed.
• Event callbacks now receive (api, event) with event.type and event.detail.

(api, event) => {
  event.type
  event.detail
}

2.2 v8 → v9 Event Mapping

v8	v9	Notes
pointerDown	pointerdown	Case change
pointerMove	pointermove	Case change
pointerUp	pointerup	Case change
slidesInView	slidesinview	Case change
slidesChanged	slideschanged	Case change
slideFocusStart	slidefocus	Renamed
scroll	scroll	Unchanged
select	select	Unchanged
settle	settle	Unchanged
resize	resize	Detail type changed
reInit	reinit	Case change
destroy	destroy	Unchanged
init	❌ removed	Run setup after init

2.3 Full Event List (v9)

Events marked NEW did not exist in v8.

export interface EmblaEventListType {
  pointerdown: PointerEventType
  pointermove: PointerEventType
  pointerup: PointerEventType
  slideschanged: MutationRecord[]
  slidesinview: SlidesInViewEventType
  scrolloptimize: ScrollOptimizeEventType // NEW
  select: SelectEventType
  scroll: ScrollEventType
  settle: null
  destroy: null
  reinit: null
  resize: ResizeObserverEntry[]
  slidefocus: FocusEvent
}

2.4 Event Usage Examples

emblaApi.on('pointerdown', (api, event) => {})
emblaApi.on('slidesinview', (api, event) => {})
emblaApi.on('slidefocus', (api, event) => {})
emblaApi.on('reinit', () => {})

2.5 No init Event Replacement

v8

const emblaApi = EmblaCarousel(root, options, plugins)

function mySetupFunction() {
  // run setup logic here
}

emblaApi.on('init', mySetupFunction)

v9

const emblaApi = EmblaCarousel(root, options, plugins)

function mySetupFunction() {
  // run setup logic here
}

mySetupFunction()

2.6 Cancellable Events

• Returning false from a handler cancels the event's internal handling.
• The former watchDrag callback maps to the cancellable pointerdown event.

emblaApi.on('pointerdown', (api, event) => {
  return false // cancel pointer down internal logic
})

emblaApi.on('pointerdown', (api, event) => {
  allow pointer down internal logic
  return true // allow pointer down internal logic
})

emblaApi.on('pointerdown', (api, event) => {
  // allow pointer down internal logic
})

3. Options (Breaking Renames)

v8 option	v9 option	Notes
startIndex	startSnap	Selected snap index at init.
watchDrag	draggable	Enables/disables drag interactions. v8 callback moved to cancellable pointerdown event.
watchResize	resize	Enables/disables resize observing. v8 callback moved to cancellable resize event.
watchSlides	slideChanges	Enables/disables slide mutation observing. Related event slideschanged is cancellable.
watchFocus	focus	Enables/disables focus handling. Related event slidefocus is cancellable.

Example option mapping:

// v8
const optionsV8 = {
  startIndex: 0,
  watchDrag: true,
  watchResize: true,
  watchSlides: true,
  watchFocus: true
}

// v9
const optionsV9 = {
  startSnap: 0,
  draggable: true,
  resize: true,
  slideChanges: true,
  focus: true
}

Callback migration:

v8 callback option	v9 event	How to cancel
watchDrag (fn)	pointerdown	Return false from handler to cancel pointer move/drag handling.
watchResize (fn)	resize	Return false from handler to cancel Embla's internal resize handling.
watchFocus (fn)	slidefocus	Return false from handler to cancel Embla's internal resize handling.
watchSlides (fn)	slideschanged	Return false from handler to cancel Embla's internal resize handling.

4. Plugins

4.1 Autoplay (embla-carousel-autoplay)

Breaking option changes:

• Removed: playOnInit, stopOnFocusIn, stopOnInteraction, stopOnMouseEnter
• Renamed: jump → instant
• Added: defaultInteraction: boolean

import Autoplay from 'embla-carousel-autoplay'

const autoplay = Autoplay({ instant: false })
const emblaApi = EmblaCarousel(root, options, [autoplay])

// Since playOnInit has been removed, manually start it like so:
emblaApi.plugins().autoplay.play()

// Custom interaction handling instead of the now removed `stopOnFocusIn`, `stopOnInteraction`, `stopOnMouseEnter`:
const autoplay = Autoplay({ defaultInteraction: false })

emblaApi.on('autoplay:interaction', (api, event) => {
  const { interaction, originalEvent, isMouseOver, isPointerDown } = event.detail
})

// Default interaction will stop on pointerdown and slidefocus

4.2 Auto Scroll (embla-carousel-auto-scroll)

Breaking option changes:

• Removed: playOnInit, stopOnFocusIn, stopOnInteraction, stopOnMouseEnter
• Added: defaultInteraction: boolean

import AutoScroll from 'embla-carousel-auto-scroll'

const autoScroll = AutoScroll({ defaultInteraction: true })
const emblaApi = EmblaCarousel(root, options, [autoScroll])

// Since playOnInit has been removed, manually start it like so:
emblaApi.plugins().autoScroll.play()

// Custom interaction handling instead of the now removed `stopOnFocusIn`, `stopOnInteraction`, `stopOnMouseEnter`:
const autoScroll = AutoScroll({ defaultInteraction: false })

emblaApi.on('autoscroll:interaction', (api, event) => {
  const { interaction, originalEvent, isMouseOver, isPointerDown } = event.detail
})

// Default interaction will stop on pointerdown and slidefocus

4.3 Auto Height (embla-carousel-auto-height)

Breaking change:

• Height is now applied to the root node (previously the container).
• Added option: heightEvent: 'select' | 'slidesinview' (default: select).

import AutoHeight from 'embla-carousel-auto-height'

const autoHeight = AutoHeight({ heightEvent: 'select' })
const emblaApi = EmblaCarousel(root, options, [autoHeight])

emblaApi.rootNode().style.height

4.4 Class Names (embla-carousel-class-names)

v8	v9
dragging	pointerDown

import ClassNames from 'embla-carousel-class-names'

ClassNames({ pointerDown: 'is-pointer-down' })

5. Framework Wrappers

Vue (Breaking)

import useEmblaCarousel from 'embla-carousel-vue'

const [rootNode, emblaApiRef, emblaSsrApi] = useEmblaCarousel(options, plugins)

Svelte (Breaking)

<div use:useEmblaCarousel={{ options, plugins }} on:emblainit={(e) => console.log(e.detail)}>
  <!-- slides -->
</div>

Solid (Breaking)

createEmblaCarousel → useEmblaCarousel

6. For Plugin Authors

6.1 Event Emission (Breaking)

// v8
emblaApi.emit('autoplay:play')

// v9
emblaApi.createEvent('autoplay:play', null).emit()

6.2 Internal API Changes (Breaking)

v8	v9
internalEngine().ownerWindow	internalEngine().nodeHandler.ownerWindow
internalEngine().ownerDocument	internalEngine().nodeHandler.ownerDocument
index	indexCurrent
axis.measureSize	axis.getSize
limit.reachedMin	pastMinBound
limit.reachedMax	pastMaxBound
limit.constrain	clamp

7. Version References

• v8 baseline commit: 0848932
• v9: HEAD

If additional breaking changes are found, please open an issue with code references and this guide will be updated.

[ttnbtfy]

Hello, I have some init events like this:

this.slider.on( 'init', () => this.classList.add( 'hello-world' ));

How can I change the structure in version v9?

[davidjerleke]

@ttnbtfy thanks for the question, I've updated the migration guide with a clear example now. Please see the 2.5 No init Event Replacement section.

[sarussss]

Hi @davidjerleke

Thank you for your efforts in creating Embla v9.
I have two questions:
Will the package size increase significantly with SSR support? This is a major concern for those who don't use it, like me.
My second question is, with the current V9 APIs, can we create card effects like this in Embla?

[davidjerleke]

Hi @sarussss,

Thanks for the kind words! I’m glad you’re interested in Embla v9.

Just a heads-up: v9 is currently in RC (release candidate), so some things could still change, like bundle size improvements.

Regarding SSR support and bundle size, I know many developers appreciate Embla’s slim size, and I’ll do my best to avoid adding much overhead. For example, I’m considering whether some features could be moved out of the core and offered as plugins instead. That said, Embla isn’t primarily aimed at developers who are solely focused on minimizing KB — it’s not the absolute smallest carousel library. Rather, it’s a lightweight, extensible library that prioritizes a flexible API. There are smaller carousel libs that cover very simple use cases, but developers often run into limitations as their needs grow.

As for card effects, it’s definitely possible to build them on top of Embla, similar to iOS pickers. For reference, see this example. This was also possible in v8 with emblaApi.internalEngine(), but I haven’t had the time to create a dedicated example yet, since the usage of this kind of effect is more limited than the core features.

Hope this helps clarify things!

[sarussss]

@davidjerleke Thank you for your answer, it helped me a lot.

[MartinCura]

Migrated v8 -> v9 RC.1 without any trouble, seems to be working great :)