feat: add throttleTime option to mouseWheel configuration and improve wheel event handling in Carousel

Author: ismail9k

docs/config.md

@@ -58,16 +58,17 @@ Both `mouseDrag` and `touchDrag` properties accept either a boolean value or a `
 
 The `mouseWheel` property accepts either a boolean value or a `WheelConfig` object with the following properties:
 
-| Property    | Type     | Default | Description                                                                                |
-|-------------|----------|---------|--------------------------------------------------------------------------------------------|
-| `threshold` | `number` | 10      | Controls the wheel movement threshold required to trigger a slide transition. Higher values require more scrolling to trigger a slide change. |
+| Property      | Type     | Default | Description                                                                                |
+|---------------|----------|---------|--------------------------------------------------------------------------------------------|
+| `threshold`   | `number` | 10      | Controls the wheel movement threshold required to trigger a slide transition. Higher values require more scrolling to trigger a slide change. |
+| `throttleTime` | `number` | 100     | Controls how quickly wheel events are processed in milliseconds. Lower values make scrolling more responsive but may cause performance issues. By default, uses either this value or 1/3 of the transition time, whichever is smaller. |
 
 ### Example
 
 ```vue
 <template>
   <Carousel 
-    :mouseWheel="{ threshold: 20 }"
+    :mouseWheel="{ threshold: 20, throttleTime: 50 }"
   >
     <!-- Slides -->
   </Carousel>

playground/App.vue

@@ -41,7 +41,7 @@ const defaultConfig = {
   autoplay: null,
   wrapAround: true,
   height: '200',
-  mouseScroll: true,
+  mouseWheel: true,
   dir: 'left-to-right',
   breakpointMode: 'carousel',
   gap: 10,

src/components/Carousel/Carousel.ts

@@ -22,6 +22,7 @@ import {
   CarouselConfig,
   createSlideRegistry,
   DEFAULT_CONFIG,
+  DEFAULT_DRAG_THRESHOLD,
   DIR_MAP,
   injectCarousel,
   NonNormalizedDir,
@@ -418,11 +419,11 @@ export const Carousel = defineComponent({
     }) => {
       const threshold = isTouch
         ? typeof config.touchDrag === 'object'
-          ? (config.touchDrag?.threshold ?? 0.3)
-          : 0.3
+          ? (config.touchDrag?.threshold ?? DEFAULT_DRAG_THRESHOLD)
+          : DEFAULT_DRAG_THRESHOLD
         : typeof config.mouseDrag === 'object'
-          ? (config.mouseDrag?.threshold ?? 0.3)
-          : 0.3
+          ? (config.mouseDrag?.threshold ?? DEFAULT_DRAG_THRESHOLD)
+          : DEFAULT_DRAG_THRESHOLD
 
       const draggedSlides = getDraggedSlidesCount({
         isVertical: isVertical.value,

src/composables/useWheel.ts

@@ -1,6 +1,10 @@
 import { ComputedRef, Ref, computed } from 'vue'
 
 import { CarouselConfig } from '@/shared'
+import {
+  DEFAULT_MOUSE_WHEEL_THRESHOLD,
+  DEFAULT_WHEEL_THROTTLE_TIME,
+} from '@/shared/constants'
 import { throttle } from '@/utils'
 
 interface UseWheelOptions {
@@ -28,6 +32,20 @@ export function useWheel(options: UseWheelOptions) {
     return typeof isSliding === 'boolean' ? isSliding : isSliding.value
   })
 
+  // Use a shorter throttle duration for wheel events to improve responsiveness
+  // Use either a custom wheel throttle time or 1/3 of the transition time
+  const wheelThrottleTime = computed(() => {
+    // If mouseWheel is an object with a throttleTime property, use that
+    if (typeof config.mouseWheel === 'object' && config.mouseWheel.throttleTime) {
+      return config.mouseWheel.throttleTime
+    }
+    // Otherwise use a fraction of the transition time for better responsiveness
+    return Math.min(
+      DEFAULT_WHEEL_THROTTLE_TIME,
+      config.transition ? Math.floor(config.transition / 3) : DEFAULT_WHEEL_THROTTLE_TIME
+    )
+  })
+
   const handleScroll = throttle((event: Event): void => {
     if (!config.mouseWheel || sliding.value) {
       return
@@ -40,7 +58,9 @@ export function useWheel(options: UseWheelOptions) {
 
     // Add sensitivity threshold to prevent small movements from triggering navigation
     const threshold =
-      typeof config.mouseWheel === 'object' ? (config.mouseWheel.threshold ?? 10) : 10
+      typeof config.mouseWheel === 'object'
+        ? (config.mouseWheel.threshold ?? DEFAULT_MOUSE_WHEEL_THRESHOLD)
+        : DEFAULT_MOUSE_WHEEL_THRESHOLD
 
     // Determine scroll direction
     const deltaY = Math.abs(wheelEvent.deltaY) > threshold ? wheelEvent.deltaY : 0
@@ -51,24 +71,33 @@ export function useWheel(options: UseWheelOptions) {
       return
     }
 
-    const isScrollingDown = deltaY > 0
-    const isScrollingRight = deltaX > 0
+    // Determine primary delta based on carousel orientation
+    const primaryDelta = vertical.value ? deltaY : deltaX
+
+    // If primaryDelta is 0, use the other delta as fallback
+    const effectiveDelta =
+      primaryDelta !== 0 ? primaryDelta : vertical.value ? deltaX : deltaY
+
+    // Positive delta means scrolling down/right
+    const isScrollingForward = effectiveDelta > 0
 
-    // Determine direction based on carousel orientation and scroll direction
-    if ((vertical.value && isScrollingDown) || (!vertical.value && isScrollingRight)) {
+    // Apply navigation based on scroll direction and carousel configuration
+    if (isScrollingForward) {
+      // Scrolling down/right
       if (reversed.value) {
         prev()
       } else {
         next()
       }
     } else {
+      // Scrolling up/left
       if (reversed.value) {
         next()
       } else {
         prev()
       }
     }
-  }, 16)
+  }, wheelThrottleTime.value) // Use the computed throttle time
 
   return {
     handleScroll,

src/shared/constants.ts

@@ -45,6 +45,10 @@ export const SNAP_ALIGN_OPTIONS = [
   'center-odd',
 ] as const
 
+export const DEFAULT_MOUSE_WHEEL_THRESHOLD = 10
+export const DEFAULT_WHEEL_THROTTLE_TIME = 100
+export const DEFAULT_DRAG_THRESHOLD = 0.3
+
 export const DEFAULT_CONFIG: CarouselConfig = {
   autoplay: 0,
   breakpointMode: BREAKPOINT_MODE_OPTIONS[0],
@@ -60,7 +64,6 @@ export const DEFAULT_CONFIG: CarouselConfig = {
   modelValue: 0,
   mouseDrag: true,
   mouseWheel: false,
-  mouseScrollThreshold: 10,
   pauseAutoplayOnHover: false,
   preventExcessiveDragging: false,
   slideEffect: SLIDE_EFFECTS[0],

src/shared/types.ts

@@ -33,6 +33,7 @@ export type DragConfig = {
 }
 export type WheelConfig = {
   threshold?: number
+  throttleTime?: number
 }
 
 export type CarouselConfig = {