xiel / embla-carousel-wheel-gestures

wheel interactions for Embla Carousel

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-wheel-gestures # npm install --save 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(),
  ])

  // ...
}

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

Legacy Browsers

If you need to support IE 10 & 11 you might need to install and add extra polyfills:

// Adds support old IE >= 10
import 'core-js/stable'
import 'events-polyfill/src/constructors/MouseEvent'

Thanks

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

License

MIT.

embla-carousel-wheel-gestures's Issues

Disable Scroll indication?

Since enabling this plugin, most of the times when I hover over a carousel, it indicates its scrollability by quickly dragging itself to one side and then jumping back to its default position.

I think is is done to signal to the user that a horizontal scroll is possible.
This happens without any user interaction and it is not consistent.

Is there a way to disable this?

Add E2E Test to verify functionality

• e2e tests using playwright or similar are more helpful than unit tests here

Support for embla-carousel v8

The plugin fails to initialize a carousel with the newest release candidate of embla-carousel, due to optionsHandler now being passed to the init function.

Changes need to be made similar to here: davidjerleke/embla-carousel@f3fc832

I can provide a PR if needed.

Global options

Hi @xiel,

I hope you're doing great. I just released Embla v.6.2.0 with the global options feature. Users can now set global options that will be applied to all their plugin instances as described here:

import Autoplay from 'embla-carousel-autoplay'

Autoplay.globalOptions = { delay: 4000 }

This feature is by no means mandatory for plugins, but feel free to implement it if you want. Thank you for your time!

Cheers,
David

Customize scroll axis

Hi,

thanks first of all for a very useful plugin!

I was wondering if you'd be open to add a way to customize the scrolling axis.
Example:
Given a horizontal embla carousel, I'd want to slide on vertical scroll events instead of horizontal scroll events.

I imagine something like

type WheelGesturesPluginOptions = {
  wheelDraggingClass: string,
  forceWheelAxis?: 'x' | 'y'  // defaults to undefined
}

and subsequently

    function handleWheel(state: WheelEventState) {
      const {
        axisDelta: [deltaX, deltaY],
      } = state
      const scrollAxis = foceWheelAxis ?? engine.options.axis;
      const primaryAxisDelta = scrollAxis === 'x' ? deltaX : deltaY
      const crossAxisDelta = scrollAxis === 'x' ? deltaY : deltaX

would be happy to submit a PR if you think that it'd be a fitting addition to your plugin.

Add option for smooth slide change on scroll with little strength.

Hello 👋,

Really appreciate your work on this plugin.

I was wondering if it would be possible to make the embla carousel on scroll function similar to this page when carousel is in fullscreen (smooth scrolling with little strength and no going back): https://eu.gymshark.com/products/gymshark-sport-run-pants-black-aw23

Thank you!

Lovro

Target option

Would be great if you can pass target option. Use case if there is one carousel on the non scrollable page and I want it to scroll on document.documentElement instead of carousel element

Cannot install with NPM

When installing with NPM, it complains that it cannot find the peer dependency [email protected] (it doesn't exist). NPM does not seem to recognise [email protected] as compatible with 8.0.0.

Here is the full output:

npm WARN ERESOLVE overriding peer dependency
npm WARN While resolving: [email protected]        
npm WARN Found: embla-carousel@undefined
npm WARN node_modules/embla-carousel
npm WARN
npm WARN Could not resolve dependency:
npm WARN peer embla-carousel@"^8.0.0" from [email protected]
npm WARN node_modules/embla-carousel-wheel-gestures
npm WARN   embla-carousel-wheel-gestures@"*" from the root project        
npm ERR! code ETARGET
npm ERR! notarget No matching version found for embla-carousel@^8.0.0.    
npm ERR! notarget In most cases you or one of your dependencies are requesting
npm ERR! notarget a package version that doesn't exist.

To reproduce this error, run npm install embla-carousel-react, then npm install embla-carousel-react, and the error would be shown in the terminal.

Test with RTL

Hello Felix (@xiel),

I just released RTL support for Embla Carousel (See release here), and I think we need to test if the wheel gestures work with it. I’m hoping that it’ll work out of the box but we should make sure it does. I have a lot of feature requests to work on right now so if you have any time to test it before I do, please test this 🙂.

Best,
David

Many "is not a function" errors after first scroll, after which scrolling breaks.

Not sure what's happening, because this used to work, but Im suddenly getting a lot of console errors after the first "swipe" followed by scrolling breaking all together. Any ideas?

Uncaught TypeError: engine.scrollBody.useDefaultSpeed is not a function
    at wheelGestureEnded (commons.js:13946)
    at handleWheel (commons.js:13990)
    at commons.js:83454
    at Array.forEach (<anonymous>)
    at dispatch (commons.js:83453)
    at publishWheel (commons.js:83622)
    at end (commons.js:83846)
4commons.js:13946 Uncaught TypeError: engine.scrollBody.useDefaultSpeed is not a function
    at wheelGestureEnded (commons.js:13946)
    at handleWheel (commons.js:13990)
    at commons.js:83454
    at Array.forEach (<anonymous>)
    at dispatch (commons.js:83453)
    at publishWheel (commons.js:83622)
    at processWheelEventData (commons.js:83689)
    at HTMLDivElement.feedWheel (commons.js:83584)
commons.js:13946 Uncaught TypeError: engine.scrollBody.useDefaultSpeed is not a function
    at wheelGestureEnded (commons.js:13946)
    at handleWheel (commons.js:13990)
    at commons.js:83454
    at Array.forEach (<anonymous>)
    at dispatch (commons.js:83453)
    at publishWheel (commons.js:83622)
    at end (commons.js:83846)
3commons.js:13946 Uncaught TypeError: engine.scrollBody.useDefaultSpeed is not a function
    at wheelGestureEnded (commons.js:13946)
    at handleWheel (commons.js:13990)
    at commons.js:83454
    at Array.forEach (<anonymous>)
    at dispatch (commons.js:83453)
    at publishWheel (commons.js:83622)
    at processWheelEventData (commons.js:83689)
    at HTMLDivElement.feedWheel (commons.js:83584)

NPM install dependency conflict

Similar to this earlier issue Cannot install with NPM #182
There is a dependency conflict when installing via npm with the latest embla-carousel 8.0.0-rc7.

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/embla-carousel

Suggestion
It looks like the other plugins endorsed by the docs are tagging a release with the same rc as the main embla-carousel package. Maybe using the same approach when bumping the dependancy could help prevent future confusion for integrators?

When more than 1 carousel are placed within the same page, scrolling 1 will affect the other

Environment:
OS: macOS Ventura 13.5
Device: MacBook Pro
Hardware: Apple Magic Mouse 2 (model:A1657)
Package Version: v8.0.0-rc05

Reproduce:

1. have more than 1 carousel in same page source code
2. start scrolling first carousel
3. quickly move cursor to second carousel before animation ends
4. both carousel will be moved, although the 'wheel' event only trigger on the first carousel

Screen.Recording.2024-03-04.at.3.13.18.PM.mov

Provide UMD bundle

• provide same bundles as embla for greater compatibility

Convert to Plugin

Embla has a plugin system now.

Convert this to use the new plugin API.

Remove Peer Dep

Describe the bug

After installing the embla-carousel-wheel-gestures plugin and using it successfully with embla-carousel-vue I keep getting npm warnings because embla-carousel is a peer dependency of the embla-carousel-wheel-gestures package.

Steps to reproduce

1. Install embla-carousel-vue
2. Install embla-carousel-wheel-gestures
3. See the warnings in the terminal

Expected behavior

• As the plugin functions properly I would like to see a clear terminal void of issues instead of bloating my project with unnecessary packages.

Support use in Shadow DOM

Bug Description

This plugin does not function properly when using with an instance of Embla Carousel contained in a Shadow DOM.

CodeSandbox

https://codesandbox.io/s/sleepy-wing-e8or8g

Steps to reproduce

1. Open https://codesandbox.io/s/sleepy-wing-e8or8g
2. Use mouse wheel to scroll through top carousel—carousel scrolls as expected
3. Attempt to use mouse wheel to scroll through bottom carousel—carousel does not scroll properly

Suggested Fix

1. In the createRelativeMouseEvent function, when creating the MouseEvent, add composed: true to the dictionary parameter (See https://developer.mozilla.org/en-US/docs/Web/API/Event/composed).

Scrolling Intensity

hey! Thanks so much for this awesome plug-in! you are really making lives easier

I was wondering if there is a way to make the scrolling at the beginning and end of the slider less harsh.
You could see this behavior in your example.

I tried using inViewThreshold, and containScroll from Emba, but no luck. Here's the example I'm working on so can have a better idea of the smoother expected behavior.

Would you have any suggestions? I'm happy to help.

Thank you!

Doesn't seem to be working at all.

I've tried with both demos here on the latest versions of Firefox & Chrome. Nothing happens when scrolling with a mouse wheel.

wheel-gestures not working?

Hello, I am trying to use Embla carousel with drag free, wheel-gestures and also with progress. But I am facing one problem When I am trying to integrate embla-carousel-wheel-gestures. It is not working. Here I am trying to scroll in x-axis(horizontal) with mouse wheel. Can you help me?

CodeSandBox- https://codesandbox.io/s/fast-fast-527jo

Scrolling with the trackpad is super smooth, scrolling with the mouse not so much.

Dear @xiel, thank you for this very nice extension of embla-carousel!
I have the following setup:
Vertical embla-carousel with the following options:

const options: Partial<OptionsType> = {
      loop: true,
      axis: "y",
      skipSnaps: true,
      align: "start",
      draggable: true,
    };

Scrolling with the trackpad and dragging is super smooth and responsive. But when using the scroll wheel on the mouse the slider makes the following:

1. carousel scrolls a tiny bit
2. carousel stops for a short time
3. carousel scrolls really fast in an unpredictable way

Is this something you are aware of or am I doing something wrong? Your input on the topic is greatly appreciated. :)

Add option to use both scroll axes

Hi there,

Appreciate the work you've put into this plugin, thank you!

I was wondering if there was a way to be able to include an option to use both axes to scroll?

Thank you!
James

Disable wheel gestures when scroll next and previous are both false

Hello there and thanks for this great plugin!

Is there any way to disable wheel gestures when there are not enough slides to scroll? Right now when emblaApi.canScrollPrev() and emblaApi.canScrollNext() are false, I can still drag slides with wheel gestures and it snaps back into the place.

Best,

"rtl" direction doesn't work with the images when given loading lazy property

"rtl" direction doesn't work with the images when given loading lazy property because the carousel doesn't consider the image entered the view port from the right direction but from the left direction

Code assumes the presence of `process`

Thank you for this great plugin!

embla-carousel-wheel-gestures/embla-carousel-wheel-gestures/src/WheelGesturesPlugin.ts

Line 18 in 13aef98

const __DEV__ = process.env.NODE_ENV !== 'production'

process may not be present in some environments, which causes:

Uncaught ReferenceError: process is not defined

Related: dermotduffy/frigate-hass-card#531