[General]: v9 Release Notes

[davidjerleke]

🎠 Embla Carousel v9

🌍 The world may be chaotic, but at least your carousels are finally SSR-safe.

Embla v9 is a major step forward. This release introduces first-class server-side rendering, a cleaner snap-centric API, a modern typed event system, and a stronger plugin and framework ecosystem.
On top of that, the entire documentation has been fully reworked to be more practical, explicit, and framework-agnostic.

⚠️ Release Candidate (RC)
The core API is considered stable, but feedback is highly encouraged before the final release. Minor adjustments may still be made based on real-world usage.

✨ If you care about predictable rendering, long-term API consistency, and composable integrations, v9 is built for you.

🚀 What’s New at a Glance

Embla v9 focuses on correctness, composability, and long-term stability.
Here’s what you get in this release:

• 🧱 First-class SSR support
  Server-safe APIs and ssrStyles() enable an instant, layout-stable first paint—no hydration surprises, no CLS.

• 🧠 Typed, cancellable event model
  Lowercase, consistent event names with explicit payloads and a modern cancellation mechanism.

• 🎯 Unified snap-centric API
  Clearer method naming and intent, making carousel state and navigation easier to reason about.

• 🧩 Refined option model
  Explicit behavior flags and improved in-view control reduce hidden behavior and configuration guesswork.

• ⚡ Automatic scroll performance optimization
  New scrolloptimize event applies hardware acceleration only when needed for smoother scrolling.

• ♿ Improved accessibility & plugins
  Brand-new Accessibility plugin, plus major improvements to Autoplay, Auto Scroll, Auto Height, and Fade.

• 🧬 Stronger framework ecosystem
  New first-party adapters for Svelte, Solid, and Vue, alongside an improved React hook.

• 📚 Fully overhauled documentation
  Concrete examples, clearer APIs, and framework-agnostic guides across the board.

🙏 Thanks & Supporting Embla

Huge thanks to everyone who has contributed feedback, filed issues, or built plugins — your help keeps Embla alive and rolling.

A special shoutout to Syntax FM for being Embla’s first and continuous sponsor, providing crucial support that makes releases like v9 possible. ✨

Maintaining a library like Embla can feel like juggling flaming carousels while the world burns 🔥🎠 — it’s fun, but it’s also a lot of work, especially for a solo maintainer. v9 represents months of full-time effort, and there’s still more ahead:

• 📓 The documentation currently uses GatsbyJS, which introduces significant development overhead and maintenance complexity. Migrating to Next.js or an alternative modern framework would streamline development and reduce friction.
• 🏗️ The documentation site is built on styled-components, now in maintenance mode.
• ⚙️ Much of the ecosystem has moved to ESNext, making upgrades slow and tricky.
• 🎯 Fixing these issues requires dedicated focus — without support, progress can feel impossible.
• ✨ …and much more

Sponsorship makes a tangible difference. Even a single meaningful sponsor could have brought v9 to life 6–10 months earlier.

If Embla is valuable to you or your team, consider supporting the project:

• ❤️ Sponsor Embla: here
• 🧑‍💻 Contribute: here
• 🐞 Report issues / feedback: here.

With your help, we can keep Embla moving, maintain its core features, and make future upgrades less painful.

✨ New & Improved

v9 brings major improvements across SSR, events, API design, options, plugins, and framework support. Here’s what’s new:

🖥️ First-Class Server-Side Rendering (SSR)

SSR is no longer an afterthought — it’s a core feature in v9.

• 🧱 New ssr option: Define deterministic slide sizes for server rendering.
• 💻 emblaApi.ssrStyles(containerSelector, slidesSelector?): Returns critical CSS to inline during SSR, preventing layout shifts.
• ⚡ Server-safe constructor: EmblaCarousel(null, options, plugins) works without touching the DOM.
• 🌐 Framework adapters: All expose the server API so styles can be generated during pre-rendering.

Result: faster first paint, no CLS, and predictable hydration across frameworks.

import EmblaCarousel from "embla-carousel";

// Slide sizes in %
const options = { ssr: [80, 80, 80, 40] };
const emblaServerApi = EmblaCarousel(null, options);
const styles = emblaServerApi.ssrStyles(".embla__container", ".embla__slide");
// Inline `styles` in your server-rendered HTML

Read more here.

🧠 Typed & Cancellable Event Model

The event system has been redesigned for clarity, safety, and extensibility.

• ✅ Event names are lowercase and consistent.
• 📦 Most events include typed detail payloads.
• 🚫 Returning false cancels internal event logic.
• 🛠️ createEvent(type, detail) lets you define custom events with .emit() — ideal for plugins.

emblaApi.on("slidesinview", (emblaApi, event) => {
  const { slidesInView, slidesLeftView, slidesEnterView } = event.detail;
});

// Cancelling events
emblaApi.on("pointerdown", () => false);

// Allowing events
emblaApi.on("pointerdown", () => true);

// Allowing events
emblaApi.on("pointerdown", () =>{});

Read more here.

🎯 Snap-Centric API

The API is now snap-first, making it easier to reason about navigation and state.

Navigation Methods:

• goTo(index, instant?, direction?)
• goToNext(instant?)
• goToPrev(instant?)

State Methods:

• selectedSnap()
• previousSnap()

Capabilities:

• canGoToNext()
• canGoToPrev()

Snap Data:

• snapList() (progress values)
• snapIndex(offset)

Read more here.

⚙️ Options: Clearer, Explicit, More Composable

The option model has been refined to reduce hidden behavior and make intent clear:

New Options:

• startSnap (replaces startIndex)
• inViewMargin (works with inViewThreshold)

Explicit Behavior Toggles:

• draggable 🖐️
• resize 📏
• focus 🎯
• slideChanges 🔄
• ssr 🖥️

Refined:

• inViewThreshold now supports fine-grained thresholds with inViewMargin.

Renamed Options:

• watchDrag → draggable
• watchResize → resize
• watchFocus → focus
• watchSlides → slideChanges

Read more here.

🧩 Plugins

♿ Accessibility (New)

A turnkey accessibility layer for Embla:

• ARIA attributes
• Live regions
• Helpers for prev/next buttons and dot navigation
• Framework-agnostic and easy to adopt

Read more here.

⏯️ Autoplay

• New pause() API
• New events: autoplay:play, autoplay:stop, autoplay:interaction, autoplay:select, autoplay:timerset, autoplay:timerstopped
• Fully SSR-aware lifecycle
• Customizable interaction handling (pointer, mouse, focus)

Read more here.

🌀 Auto Scroll

• New events: autoscroll:play, autoscroll:stop, autoscroll:interaction
• Interaction handling customizable via autoscroll:interaction
• Simplified behavior and SSR awareness

Read more here.

📏 Auto Height

• Automatically watches for slide height changes
• Configurable update triggers (select or slidesinview)
• Robust root height management for dynamic content

Read more here.

🌫️ Fade

• SSR support via fade.ssrStyles(...)
• Integrated option handling for seamless transitions

Read more here.

🛠️ Framework Adapters

All framework adapters in v9 now expose both client and server APIs, making SSR integration seamless.

• ⚛️ React
  useEmblaCarousel() returns [emblaRef, clientApi, serverApi]

• 🟩 Svelte (new)
  Action or direct API; returns server API when no node is provided

• 🟦 Solid (new)
  [emblaRef, clientApi, serverApi]

• 🟪 Vue (new)
  [emblaRef, clientApiRef, serverApi]

Read more here.

📚 Documentation Improvements

The documentation has been fully rewritten to be more action-oriented, explicit, and developer-friendly.

Every API entry now includes:

• 🔹 Exact method signatures — know exactly what to call and how to use it
• 🔹 Option usage & combination — see how each option interacts
• 🔹 Event details — including event.detail payloads
• 🔹 Runnable examples — copy, paste, and try

Additional updates:

• 🖥️ SSR guide with examples for React, Vue, Svelte, and Solid
• 🧩 Plugin docs covering new events and SSR usage
• ♿ Accessibility plugin documentation
• 🔄 Unified framework tabs across guides and sandboxes

Read more here.

⚠️ Breaking Changes & Migration

v9 introduces renamed methods, options, and events for a clearer, snap-centric API. Here’s what you need to know:

🔄 Method Renames

• scrollNext → goToNext
• scrollPrev → goToPrev
• canScrollNext → canGoToNext
• canScrollPrev → canGoToPrev
• scrollTo(index, jump?) → goTo(index, instant?, direction?)
• selectedScrollSnap() → selectedSnap()
• previousScrollSnap() → previousSnap()
• scrollSnapList() → snapList()

⚙️ Option Renames

• startIndex → startSnap
• watchDrag → draggable 🖐️
• watchResize → resize 📏
• watchFocus → focus 🎯
• watchSlides → slideChanges 🔄

🧠 Event Changes

• All event names are lowercase
• Many events now include typed payloads

Common mappings:

• pointerDown → pointerdown
• pointerUp → pointerup
• slidesChanged → slideschanged
• slidesInView → slidesinview
• reInit → reinit
• slideFocus → slidefocus

New cancellable event:

• scrolloptimize — automatically manages hardware acceleration for slides entering/leaving view ⚡

⚡ Quick Migration Examples

Methods:

// v8
emblaApi.scrollNext();
emblaApi.selectedScrollSnap();

// v9
emblaApi.goToNext();
emblaApi.selectedSnap();

Events:

// v8
emblaApi.on("slidesInView", () => {});

// v9
emblaApi.on("slidesinview", (api, event) => {
  const { slidesInView, slidesLeftView, slidesEnterView } = event.detail;
});

See the full migration guide here: #1080.

🐛 Issues Addressed

This release includes fixes and improvements for the following issues:

• [Feat]: Accessibility #6 ⚡
• [Feat]: SSR support #202 🔧
• [Feat]: Autoplay - Add pause autoplay method #1021 🛠️
• [Feat]: Scroll to snap that holds a specific slide #1043 🐞
• [Feat]: Refactor watch options to watch handlers #1078 🔹
• [Feat]: Refactor events to lowercase #1083 ✅
• [Feat]: Rename snap index options and methods to achieve consistent naming #1087 🔄
• [Feat]: Add direction parameter to scrollToSnap & scrollToSlide #1091 📏
• [Feat]: Add interaction events to Autoplay & AutoScroll #1175 ♿
• [Bug]: Scroll offset issue with vertical axis and focusable elements #1192 ⚙️
• [Feat]: Add option to base AutoHeight on slides in view #1215 🖥️
• [Feat]: Auto-height plugin should automatically pick up slide height changes #1216 🎯
• [Feat]: Enhanced Event System with Context and Cancellable Events #1217 ⏯️
• [Feat]: Add custom scrollbar example to documentation #1218 🌫️

Thanks to everyone who reported, tested, and contributed fixes! 🙏

[juanpablob]

May I ask where the v8 docs are now? 😅

[davidjerleke]

• @juanpablob please see my response here [Docs]: Where are the docs from v8? #1274 (comment).

[patricekaufmann]

I discovered embla-carousel in December 2025 and it's a perfect fit for the way I like to implement sliders in combination with Neos CMS. One of the most important features was the low bundle size, only delivering what is really essential to the slide functionality.

Going from v8 to v9: The webpack chunk that contains the embla-carousel increases in size, from 17.9kb to 21.5kb. Now while 3.6kb does not seem much, that's a 20% increase in size. Any estimate on how much of that would be due to the new SSR support?

Other than that this version contains a lot of improvements, nice to see 👍

[patricekaufmann]

Thanks a lot for taking your time to compose that answer! It helped me understand the situation a bit more.

As for v9, I am not sure whether it's worth creating an issue for this but there is something I noticed when going to v9:

Some slider items now have an transform: translate3d(0px, 0px, 0px); style applied to them. In my scenario, this actually breaks the styles since this will force the browser to create its own depth layer for that element. This is probably the new "scrolloptimize"-feature being applied, correct?

[davidjerleke]

@patricekaufmann no worries, and thanks for supporting the project 👍.

Some slider items now have a transform: translate3d(0px, 0px, 0px); style applied to them. In my scenario, this actually breaks the styles since this will force the browser to create its own depth layer for that element. This is probably the new "scrolloptimize" feature being applied, correct?

You’re absolutely right — scrolloptimize automatically manages hardware acceleration for slides entering and leaving the viewport. It’s explained here in the docs.

When you say it “breaks” styles, could you clarify what behavior you’re seeing?

In versions prior to 9, Embla already applies transform: translate3d(__some-value__px, 0px, 0px); when loop: true is enabled to create the looping effect. Are you trying to apply custom transforms to the slides?

If you want to opt out of this behavior, you can disable it like this:

emblaApi.on('scrolloptimize', () => {
  return false // Disables the behavior
})

[patricekaufmann]

Great coverage in the docs on that topic 👍

---

As for the issue that occurs in my scenario I attached a video that highlights the problem:

msedge_fb5mwvsdlM.mp4

The inline transform styles are applied to elements 2, 3 and 4. The white bubble / marker is rendered via a ::before pseudo tag on the same level as the items. The grey background is part of the slider items aswell. Here we make use of static position to have all the elements be part of the same depth layer (bubble, background, text) so what the white bubble can appear above the background but below the label. When the translate3d style is applied, that setup breaks.

Furthermore in case you wonder why the background is defined on the labels and not on the wrapper: If no overflow is found, the items are centered. The orange border is an outline on the items wrapper.

---

As for the change you suggested:

I tried the code you suggested, and while the function itself is being called, returning false does not stop the inline transform rules being applied to the items initially. By manually removing the inline style after setup I verified that this code stops the slider from re-applying the style attribute when slides change or when the window resizes, etc.

[davidjerleke]

@patricekaufmann Thank you for the feedback.

About SSR support

Thanks @sarussss and @patricekaufmann for raising this. I’ll explore whether the SSR feature can be moved into a separate plugin instead, which could help keep the core lighter and more flexible.

About scroll optimization

@patricekaufmann Thanks for pointing this out. I’ll review the implementation and see if it can be made less intrusive. Since I don’t have access to your codebase, I can’t determine whether a CSS-only solution would address the issue you demonstrated.

[patricekaufmann]

I applied "transform: none !important;" to the label items as a (maybe temporary) workaround. I don't really like making use of !important rules, but in this case it allowed me to upgrade to the v9 rc1 already 👍

I also wonder.. do you think the inline style on the slide items is neccessary or could it also be solved by setting a class and applying the transform: translate3d(__some-value__px, 0px, 0px); via css? From what I have seen the value of __some-value__px never changes and is (always?) 0. It would be less specific that way, you could even use a :where(.embla-item.intersecting) selector for low specificity. There's probably quite a lot of use cases where there's a slide-in animation being applied to individual slide items that make use of transform styles without additional html wrapping, e.g. when the slider scrolls into view, animate in the slide items from right to left.