Wheel Gestures for Embla Carousel

This plugin adds wheel interactions to the amazing Embla Carousel

Installation

First you need to follow the installation instructions for Embla Carousel, after that you can add wheel support:

yarn add embla-carousel embla-carousel-wheel-gestures # npm install --save embla-carousel embla-carousel-wheel-gestures

JavaScript / TypeScript

import EmblaCarousel from 'embla-carousel'
import { WheelGesturesPlugin } from 'embla-carousel-wheel-gestures'

// initialize Embla Carousel
const embla = EmblaCarousel(emblaNode, options, [WheelGesturesPlugin()])

React

import useEmblaCarousel from 'embla-carousel-react'
import { WheelGesturesPlugin } from 'embla-carousel-wheel-gestures'

const EmblaCarouselComponent = ({ children }) => {
  const [emblaRef, embla] = useEmblaCarousel({ loop: false, skipSnaps: true }, [
    WheelGesturesPlugin(),
  ])

  // ...
}

With Embla Carousel v9, this plugin safely bails during SSR and attaches wheel listeners when the client hydrates.

Examples

Get started instantly with one of the CodeSandboxes below.

  JavaScript / TypeScript

  React (embla-carousel-react)

Options

wheelDraggingClass

Type: string
Default: is-wheel-dragging

Choose a classname that will be applied to the container during a wheel gesture. Pass an empty string to opt-out.

forceWheelAxis

Type: 'x' | 'y'
Default: undefined

Force an axis on which to listen for wheel events. Useful if you want to slide horizontally when scrolling vertically or vice versa.

target

Type: Element
Default: undefined

Specify the element that should be observed for wheel events.

Global Options

You can also set global options that will be applied to all instances. This allows for overriding the default plugin options with your own:

WheelGesturesPlugin.globalOptions = {
  wheelDraggingClass: 'my-class',
}

OS & Browser Support

• Mac OS (Chrome, Firefox, Safari, Edge), Magic Mouse, Magic Trackpad
• Windows (Chrome, Firefox, Edge), Microsoft Precision Touchpads

Wheel interaction

Wheel gestures move Embla's engine directly. The plugin retains the drag friction, snap thresholds, velocity window, and momentum handoff used by Embla v9. Boundary damping follows the carousel axis and direction, including vertical and RTL layouts.

Wheel input also works with draggable: false. Real mouse/touch dragging can take over an active wheel gesture. Wheel gestures do not emit pointerdown, pointermove, or pointerup, and scroll events do not report them as pointer dragging. Use the existing wheelDraggingClass to distinguish wheel interaction. A MouseEvent constructor polyfill is no longer required.

The React demo includes drag-free, direction, mouse/touch dragging, and a second carousel control for testing these cases. Small isolated mouse-wheel ticks retain the previous snap-back behavior; the separate single-tick issue is tracked in #234.

Thanks

Kudos to David Jerleke for creating Embla Carousel with its open API 🙏

License

MIT.

Local development

Use Node 22.12 or newer and Yarn Classic. From this repository:

yarn install
yarn build
yarn start          # React SSR demo at http://localhost:5173
yarn start:vanilla  # Vanilla, UMD and Shadow DOM demos at http://localhost:1234
yarn demo:local     # React demo using all three sibling source checkouts

The React demo always loads this workspace's plugin source, with hot reload. Normally it uses the installed Embla and wheel-gestures packages. demo:local also resolves ../wheel-gestures/src and the core, React, and reactive-utils sources in ../embla-carousel/packages. Keep those sibling directories alongside this repository. No global yarn link state is needed; React is deduplicated across the source checkouts. The UMD demo uses the locally built plugin and installed Embla bundle.

Embla core and the React wrapper are pinned to 9.0.0-rc03, the newest published v9 prerelease. The npm latest tag still points to stable 8.6.0.

Run yarn test --runInBand, yarn lint, and yarn audit:dependencies to check the library, all demo types, and every dependency in the Yarn lockfile. The audit includes workspace development dependencies and fails on high/critical advisories. The Axios resolution keeps bundlewatch on the patched 0.x release.