react-native-reanimated-carousel 2.1.2 → 2.2.1

package/lib/module/hooks/useInitProps.js.map

@@ -1 +1 @@
-{"version":3,"sources":["useInitProps.ts"],"names":["React","DATA_LENGTH","useInitProps","props","defaultIndex","data","_data","loop","autoPlayInterval","style","panGestureHandlerProps","pagingEnabled","enableSnap","width","_width","height","_height","Math","round","useMemo","length","SINGLE_ITEM","DOUBLE_ITEM","mode","modeConfig","showLength"],"mappings":"AAAA,OAAOA,KAAP,MAAkB,OAAlB;AACA,SAASC,WAAT,QAA4B,cAA5B;AAUA,OAAO,SAASC,YAAT,CACHC,KADG,EAEwB;AAC3B,QAAM;AACFC,IAAAA,YAAY,GAAG,CADb;AAEFC,IAAAA,IAAI,EAAEC,KAAK,GAAG,EAFZ;AAGFC,IAAAA,IAAI,GAAG,IAHL;AAIFC,IAAAA,gBAAgB,GAAG,IAJjB;AAKFC,IAAAA,KAAK,GAAG,EALN;AAMFC,IAAAA,sBAAsB,GAAG,EANvB;AAOFC,IAAAA,aAAa,GAAG,IAPd;AAQFC,IAAAA,UAAU,GAAG,IARX;AASFC,IAAAA,KAAK,EAAEC,MATL;AAUFC,IAAAA,MAAM,EAAEC;AAVN,MAWFb,KAXJ;AAaA,QAAMU,KAAK,GAAGI,IAAI,CAACC,KAAL,CAAWJ,MAAM,IAAI,CAArB,CAAd;AACA,QAAMC,MAAM,GAAGE,IAAI,CAACC,KAAL,CAAWF,OAAO,IAAI,CAAtB,CAAf;AAEA,QAAMX,IAAI,GAAGL,KAAK,CAACmB,OAAN,CAAmB,MAAM;AAClC,QAAI,CAACZ,IAAL,EAAW,OAAOD,KAAP;;AAEX,QAAIA,KAAK,CAACc,MAAN,KAAiBnB,WAAW,CAACoB,WAAjC,EAA8C;AAC1C,aAAO,CAACf,KAAK,CAAC,CAAD,CAAN,EAAWA,KAAK,CAAC,CAAD,CAAhB,EAAqBA,KAAK,CAAC,CAAD,CAA1B,CAAP;AACH;;AAED,QAAIA,KAAK,CAACc,MAAN,KAAiBnB,WAAW,CAACqB,WAAjC,EAA8C;AAC1C,aAAO,CAAChB,KAAK,CAAC,CAAD,CAAN,EAAWA,KAAK,CAAC,CAAD,CAAhB,EAAqBA,KAAK,CAAC,CAAD,CAA1B,EAA+BA,KAAK,CAAC,CAAD,CAApC,CAAP;AACH;;AAED,WAAOA,KAAP;AACH,GAZY,EAYV,CAACA,KAAD,EAAQC,IAAR,CAZU,CAAb;;AAcA,MAAIJ,KAAK,CAACoB,IAAN,KAAe,gBAAf,IAAmCpB,KAAK,CAACoB,IAAN,KAAe,kBAAtD,EAA0E;AAAA;;AACtE,QAAI,CAACpB,KAAK,CAACqB,UAAX,EAAuB;AACnBrB,MAAAA,KAAK,CAACqB,UAAN,GAAmB,EAAnB;AACH;;AACDrB,IAAAA,KAAK,CAACqB,UAAN,CAAiBC,UAAjB,iDACItB,KAAK,CAACqB,UADV,sDACI,kBAAkBC,UADtB,yEACoCpB,IAAI,CAACe,MAAL,GAAc,CADlD;AAEH;;AACD,SAAO,EACH,GAAGjB,KADA;AAEHC,IAAAA,YAFG;AAGHC,IAAAA,IAHG;AAIHE,IAAAA,IAJG;AAKHC,IAAAA,gBALG;AAMHC,IAAAA,KANG;AAOHC,IAAAA,sBAPG;AAQHC,IAAAA,aARG;AASHC,IAAAA,UATG;AAUHC,IAAAA,KAVG;AAWHE,IAAAA;AAXG,GAAP;AAaH","sourcesContent":["import React from 'react';\nimport { DATA_LENGTH } from '../constants';\nimport type { TCarouselProps } from '../types';\n\nexport type TInitializeCarouselProps<T> = TCarouselProps<T> & {\n    defaultIndex: Required<TCarouselProps>['defaultIndex'];\n    loop: Required<TCarouselProps>['loop'];\n    width: Required<TCarouselProps>['width'];\n    height: Required<TCarouselProps>['height'];\n};\n\nexport function useInitProps<T>(\n    props: TCarouselProps<T>\n): TInitializeCarouselProps<T> {\n    const {\n        defaultIndex = 0,\n        data: _data = [],\n        loop = true,\n        autoPlayInterval = 1000,\n        style = {},\n        panGestureHandlerProps = {},\n        pagingEnabled = true,\n        enableSnap = true,\n        width: _width,\n        height: _height,\n    } = props;\n\n    const width = Math.round(_width || 0);\n    const height = Math.round(_height || 0);\n\n    const data = React.useMemo<T[]>(() => {\n        if (!loop) return _data;\n\n        if (_data.length === DATA_LENGTH.SINGLE_ITEM) {\n            return [_data[0], _data[0], _data[0]];\n        }\n\n        if (_data.length === DATA_LENGTH.DOUBLE_ITEM) {\n            return [_data[0], _data[1], _data[0], _data[1]];\n        }\n\n        return _data;\n    }, [_data, loop]);\n\n    if (props.mode === 'vertical-stack' || props.mode === 'horizontal-stack') {\n        if (!props.modeConfig) {\n            props.modeConfig = {};\n        }\n        props.modeConfig.showLength =\n            props.modeConfig?.showLength ?? data.length - 1;\n    }\n    return {\n        ...props,\n        defaultIndex,\n        data,\n        loop,\n        autoPlayInterval,\n        style,\n        panGestureHandlerProps,\n        pagingEnabled,\n        enableSnap,\n        width,\n        height,\n    };\n}\n"]}
+{"version":3,"sources":["useInitProps.ts"],"names":["React","DATA_LENGTH","useInitProps","props","defaultIndex","data","_data","loop","autoPlayInterval","_autoPlayInterval","scrollAnimationDuration","style","panGestureHandlerProps","pagingEnabled","enableSnap","width","_width","height","_height","Math","round","max","useMemo","length","SINGLE_ITEM","DOUBLE_ITEM","mode","modeConfig","showLength"],"mappings":"AAAA,OAAOA,KAAP,MAAkB,OAAlB;AACA,SAASC,WAAT,QAA4B,cAA5B;AAkBA,OAAO,SAASC,YAAT,CACHC,KADG,EAEwB;AAC3B,QAAM;AACFC,IAAAA,YAAY,GAAG,CADb;AAEFC,IAAAA,IAAI,EAAEC,KAAK,GAAG,EAFZ;AAGFC,IAAAA,IAAI,GAAG,IAHL;AAIFC,IAAAA,gBAAgB,EAAEC,iBAAiB,GAAG,IAJpC;AAKFC,IAAAA,uBAAuB,GAAG,GALxB;AAMFC,IAAAA,KAAK,GAAG,EANN;AAOFC,IAAAA,sBAAsB,GAAG,EAPvB;AAQFC,IAAAA,aAAa,GAAG,IARd;AASFC,IAAAA,UAAU,GAAG,IATX;AAUFC,IAAAA,KAAK,EAAEC,MAVL;AAWFC,IAAAA,MAAM,EAAEC;AAXN,MAYFf,KAZJ;AAcA,QAAMY,KAAK,GAAGI,IAAI,CAACC,KAAL,CAAWJ,MAAM,IAAI,CAArB,CAAd;AACA,QAAMC,MAAM,GAAGE,IAAI,CAACC,KAAL,CAAWF,OAAO,IAAI,CAAtB,CAAf;AACA,QAAMV,gBAAgB,GAAGW,IAAI,CAACE,GAAL,CAASZ,iBAAT,EAA4B,CAA5B,CAAzB;AAEA,QAAMJ,IAAI,GAAGL,KAAK,CAACsB,OAAN,CAAmB,MAAM;AAClC,QAAI,CAACf,IAAL,EAAW,OAAOD,KAAP;;AAEX,QAAIA,KAAK,CAACiB,MAAN,KAAiBtB,WAAW,CAACuB,WAAjC,EAA8C;AAC1C,aAAO,CAAClB,KAAK,CAAC,CAAD,CAAN,EAAWA,KAAK,CAAC,CAAD,CAAhB,EAAqBA,KAAK,CAAC,CAAD,CAA1B,CAAP;AACH;;AAED,QAAIA,KAAK,CAACiB,MAAN,KAAiBtB,WAAW,CAACwB,WAAjC,EAA8C;AAC1C,aAAO,CAACnB,KAAK,CAAC,CAAD,CAAN,EAAWA,KAAK,CAAC,CAAD,CAAhB,EAAqBA,KAAK,CAAC,CAAD,CAA1B,EAA+BA,KAAK,CAAC,CAAD,CAApC,CAAP;AACH;;AAED,WAAOA,KAAP;AACH,GAZY,EAYV,CAACA,KAAD,EAAQC,IAAR,CAZU,CAAb;;AAcA,MAAIJ,KAAK,CAACuB,IAAN,KAAe,gBAAf,IAAmCvB,KAAK,CAACuB,IAAN,KAAe,kBAAtD,EAA0E;AAAA;;AACtE,QAAI,CAACvB,KAAK,CAACwB,UAAX,EAAuB;AACnBxB,MAAAA,KAAK,CAACwB,UAAN,GAAmB,EAAnB;AACH;;AACDxB,IAAAA,KAAK,CAACwB,UAAN,CAAiBC,UAAjB,iDACIzB,KAAK,CAACwB,UADV,sDACI,kBAAkBC,UADtB,yEACoCvB,IAAI,CAACkB,MAAL,GAAc,CADlD;AAEH;;AACD,SAAO,EACH,GAAGpB,KADA;AAEHC,IAAAA,YAFG;AAGHC,IAAAA,IAHG;AAIHE,IAAAA,IAJG;AAKHC,IAAAA,gBALG;AAMHE,IAAAA,uBANG;AAOHC,IAAAA,KAPG;AAQHC,IAAAA,sBARG;AASHC,IAAAA,aATG;AAUHC,IAAAA,UAVG;AAWHC,IAAAA,KAXG;AAYHE,IAAAA;AAZG,GAAP;AAcH","sourcesContent":["import React from 'react';\nimport { DATA_LENGTH } from '../constants';\nimport type { TCarouselProps } from '../types';\n\ntype TGetRequiredProps<P extends keyof TCarouselProps> = Record<\n    P,\n    Required<TCarouselProps>[P]\n>;\n\nexport type TInitializeCarouselProps<T> = TCarouselProps<T> &\n    TGetRequiredProps<\n        | 'defaultIndex'\n        | 'loop'\n        | 'width'\n        | 'height'\n        | 'scrollAnimationDuration'\n        | 'autoPlayInterval'\n    >;\n\nexport function useInitProps<T>(\n    props: TCarouselProps<T>\n): TInitializeCarouselProps<T> {\n    const {\n        defaultIndex = 0,\n        data: _data = [],\n        loop = true,\n        autoPlayInterval: _autoPlayInterval = 1000,\n        scrollAnimationDuration = 500,\n        style = {},\n        panGestureHandlerProps = {},\n        pagingEnabled = true,\n        enableSnap = true,\n        width: _width,\n        height: _height,\n    } = props;\n\n    const width = Math.round(_width || 0);\n    const height = Math.round(_height || 0);\n    const autoPlayInterval = Math.max(_autoPlayInterval, 0);\n\n    const data = React.useMemo<T[]>(() => {\n        if (!loop) return _data;\n\n        if (_data.length === DATA_LENGTH.SINGLE_ITEM) {\n            return [_data[0], _data[0], _data[0]];\n        }\n\n        if (_data.length === DATA_LENGTH.DOUBLE_ITEM) {\n            return [_data[0], _data[1], _data[0], _data[1]];\n        }\n\n        return _data;\n    }, [_data, loop]);\n\n    if (props.mode === 'vertical-stack' || props.mode === 'horizontal-stack') {\n        if (!props.modeConfig) {\n            props.modeConfig = {};\n        }\n        props.modeConfig.showLength =\n            props.modeConfig?.showLength ?? data.length - 1;\n    }\n    return {\n        ...props,\n        defaultIndex,\n        data,\n        loop,\n        autoPlayInterval,\n        scrollAnimationDuration,\n        style,\n        panGestureHandlerProps,\n        pagingEnabled,\n        enableSnap,\n        width,\n        height,\n    };\n}\n"]}

package/lib/typescript/hooks/useAutoPlay.d.ts

@@ -5,6 +5,6 @@ export declare function useAutoPlay(opts: {
     autoPlayReverse?: boolean;
     carouselController: ICarouselController;
 }): {
-    run: () => void;
     pause: () => void;
+    start: () => void;
 };

package/lib/typescript/hooks/useCarouselController.d.ts

@@ -1,5 +1,6 @@
 import React from 'react';
 import type Animated from 'react-native-reanimated';
+import type { TCarouselActionOptions } from '../types';
 interface IOpts {
     loop: boolean;
     size: number;
@@ -17,11 +18,12 @@ export interface ICarouselController {
     index: Animated.SharedValue<number>;
     sharedIndex: React.MutableRefObject<number>;
     sharedPreIndex: React.MutableRefObject<number>;
-    prev: () => void;
-    next: () => void;
+    prev: (opts?: TCarouselActionOptions) => void;
+    next: (opts?: TCarouselActionOptions) => void;
     computedIndex: () => void;
     getCurrentIndex: () => number;
     to: (index: number, animated?: boolean) => void;
+    scrollTo: (opts?: TCarouselActionOptions) => void;
 }
-export declare function useCarouselController(opts: IOpts): ICarouselController;
+export declare function useCarouselController(options: IOpts): ICarouselController;
 export {};

package/lib/typescript/hooks/useInitProps.d.ts

@@ -1,8 +1,5 @@
 import type { TCarouselProps } from '../types';
-export declare type TInitializeCarouselProps<T> = TCarouselProps<T> & {
-    defaultIndex: Required<TCarouselProps>['defaultIndex'];
-    loop: Required<TCarouselProps>['loop'];
-    width: Required<TCarouselProps>['width'];
-    height: Required<TCarouselProps>['height'];
-};
+declare type TGetRequiredProps<P extends keyof TCarouselProps> = Record<P, Required<TCarouselProps>[P]>;
+export declare type TInitializeCarouselProps<T> = TCarouselProps<T> & TGetRequiredProps<'defaultIndex' | 'loop' | 'width' | 'height' | 'scrollAnimationDuration' | 'autoPlayInterval'>;
 export declare function useInitProps<T>(props: TCarouselProps<T>): TInitializeCarouselProps<T>;
+export {};

package/lib/typescript/types.d.ts

@@ -65,6 +65,11 @@ export declare type TCarouselProps<T = any> = {
      * @description playback interval
      */
     autoPlayInterval?: number;
+    /**
+     * Time a scroll animation takes to finish
+     * @default 500 (ms)
+     */
+    scrollAnimationDuration?: number;
     /**
      * Carousel container style
      */
@@ -125,21 +130,29 @@ export declare type TCarouselProps<T = any> = {
 } & (TParallaxModeProps | TStackModeProps);
 export interface ICarouselInstance {
     /**
-     * Play the last one
+     * Scroll to previous item, it takes one optional argument (count),
+     * which allows you to specify how many items to cross
      */
-    prev: () => void;
+    prev: (opts?: TCarouselActionOptions) => void;
     /**
-     * Play the next one
+     * Scroll to next item, it takes one optional argument (count),
+     * which allows you to specify how many items to cross
      */
-    next: () => void;
+    next: (opts?: TCarouselActionOptions) => void;
     /**
      * Get current item index
      */
     getCurrentIndex: () => number;
     /**
      * Go to index
+     * @deprecated use scrollTo instead
      */
     goToIndex: (index: number, animated?: boolean) => void;
+    /**
+     * Use value to scroll to a position where relative to the current position,
+     * scrollTo(-2) is equivalent to prev(2), scrollTo(2) is equivalent to next(2)
+     */
+    scrollTo: (opts?: TCarouselActionOptions) => void;
 }
 export interface CarouselRenderItemInfo<ItemT> {
     item: ItemT;
@@ -147,3 +160,8 @@ export interface CarouselRenderItemInfo<ItemT> {
     animationValue: Animated.SharedValue<number>;
 }
 export declare type CarouselRenderItem<ItemT> = (info: CarouselRenderItemInfo<ItemT>) => React.ReactElement;
+export interface TCarouselActionOptions {
+    count?: number;
+    animated?: boolean;
+    onFinished?: () => void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-native-reanimated-carousel",
-    "version": "2.1.2",
+    "version": "2.2.1",
     "description": "Simple carousel component.fully implemented using Reanimated 2.Infinitely scrolling, very smooth.",
     "main": "lib/commonjs/index",
     "module": "lib/module/index",
@@ -30,10 +30,13 @@
         "release": "release-it --no-git.requireUpstream",
         "ios": "yarn --cwd example ios",
         "ios:pretty": "yarn --cwd example ios:pretty",
+        "web": "yarn --cwd example web",
+        "web:pretty": "yarn --cwd example web:pretty",
         "android": "yarn --cwd example android",
         "android:pretty": "yarn --cwd example android:pretty",
         "pods": "cd example && pod-install --quiet",
-        "bootstrap": "yarn example && yarn && yarn pods"
+        "bootstrap": "yarn example && yarn && yarn pods",
+        "deploy": "cd example && yarn deploy"
     },
     "keywords": [
         "react-native",

package/src/Carousel.tsx

@@ -1,10 +1,12 @@
 import React, { PropsWithChildren } from 'react';
 import Animated, { runOnJS, useDerivedValue } from 'react-native-reanimated';
+
 import { useCarouselController } from './hooks/useCarouselController';
 import { useAutoPlay } from './hooks/useAutoPlay';
 import { usePropsErrorBoundary } from './hooks/usePropsErrorBoundary';
 import { ScrollViewGesture } from './ScrollViewGesture';
 import { useVisibleRanges } from './hooks/useVisibleRanges';
+
 import type { ICarouselInstance, TCarouselProps } from './types';
 import { StyleSheet, View } from 'react-native';
 import { DATA_LENGTH } from './constants';
@@ -33,6 +35,7 @@ function Carousel<T>(
         windowSize,
         autoPlayReverse,
         autoPlayInterval,
+        scrollAnimationDuration,
         renderItem,
         onScrollEnd,
         onSnapToItem,
@@ -66,8 +69,8 @@ function Carousel<T>(
         originalLength: data.length,
         onScrollEnd: () => runOnJS(_onScrollEnd)(),
         onScrollBegin: () => !!onScrollBegin && runOnJS(onScrollBegin)(),
-        onChange: (i) => onSnapToItem && runOnJS(onSnapToItem)(i),
-        duration: autoPlayInterval,
+        onChange: (i) => !!onSnapToItem && runOnJS(onSnapToItem)(i),
+        duration: scrollAnimationDuration,
     });
 
     const {
@@ -79,7 +82,7 @@ function Carousel<T>(
         getCurrentIndex,
     } = carouselController;
 
-    const { run, pause } = useAutoPlay({
+    const { start, pause } = useAutoPlay({
         autoPlay,
         autoPlayInterval,
         autoPlayReverse,
@@ -97,9 +100,9 @@ function Carousel<T>(
     }, [sharedPreIndex, sharedIndex, computedIndex, onScrollEnd]);
 
     const scrollViewGestureOnScrollEnd = React.useCallback(() => {
-        run();
+        start();
         _onScrollEnd();
-    }, [_onScrollEnd, run]);
+    }, [_onScrollEnd, start]);
 
     const goToIndex = React.useCallback(
         (i: number, animated?: boolean) => {
@@ -115,8 +118,9 @@ function Carousel<T>(
             prev,
             getCurrentIndex,
             goToIndex,
+            scrollTo: carouselController.scrollTo,
         }),
-        [getCurrentIndex, goToIndex, next, prev]
+        [getCurrentIndex, goToIndex, next, prev, carouselController.scrollTo]
     );
 
     const visibleRanges = useVisibleRanges({

package/src/ScrollViewGesture.tsx

@@ -41,7 +41,7 @@ const IScrollViewGesture: React.FC<Props> = (props) => {
             enableSnap,
             panGestureHandlerProps,
             loop: infinite,
-            autoPlayInterval,
+            scrollAnimationDuration,
         },
     } = React.useContext(CTX);
 
@@ -59,7 +59,7 @@ const IScrollViewGesture: React.FC<Props> = (props) => {
             return withTiming(
                 toValue,
                 {
-                    duration: autoPlayInterval,
+                    duration: scrollAnimationDuration,
                     easing: Easing.easeOutQuart,
                 },
                 (isFinished) => {
@@ -69,7 +69,7 @@ const IScrollViewGesture: React.FC<Props> = (props) => {
                 }
             );
         },
-        [autoPlayInterval]
+        [scrollAnimationDuration]
     );
 
     const endWithSpring = React.useCallback(

package/src/hooks/useAutoPlay.ts

@@ -15,44 +15,41 @@ export function useAutoPlay(opts: {
     } = opts;
 
     const timer = React.useRef<NodeJS.Timer>();
+    const stopped = React.useRef<boolean>(!autoPlay);
 
-    const pause = React.useCallback(() => {
-        timer.current && clearInterval(timer.current);
-    }, []);
-
-    const run = React.useCallback(() => {
-        if (timer.current) {
-            pause();
-        }
-
-        if (!autoPlay) {
+    const play = React.useCallback(() => {
+        if (stopped.current) {
             return;
         }
 
-        timer.current = setInterval(() => {
+        timer.current = setTimeout(() => {
             autoPlayReverse
-                ? carouselController.prev()
-                : carouselController.next();
+                ? carouselController.prev({ onFinished: play })
+                : carouselController.next({ onFinished: play });
         }, autoPlayInterval);
-    }, [
-        pause,
-        autoPlay,
-        autoPlayReverse,
-        autoPlayInterval,
-        carouselController,
-    ]);
+    }, [autoPlayReverse, autoPlayInterval, carouselController]);
+
+    const pause = React.useCallback(() => {
+        timer.current && clearInterval(timer.current);
+        stopped.current = true;
+    }, []);
+
+    const start = React.useCallback(() => {
+        stopped.current = false;
+        play();
+    }, [play]);
 
     React.useEffect(() => {
         if (autoPlay) {
-            run();
+            start();
         } else {
             pause();
         }
         return pause;
-    }, [run, pause, autoPlay]);
+    }, [pause, start, autoPlay]);
 
     return {
-        run,
         pause,
+        start,
     };
 }

package/src/hooks/useCarouselController.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import type Animated from 'react-native-reanimated';
 import { Easing } from '../constants';
 import { runOnJS, useSharedValue, withTiming } from 'react-native-reanimated';
+import type { TCarouselActionOptions } from '../types';
 
 interface IOpts {
     loop: boolean;
@@ -22,14 +23,15 @@ export interface ICarouselController {
     index: Animated.SharedValue<number>;
     sharedIndex: React.MutableRefObject<number>;
     sharedPreIndex: React.MutableRefObject<number>;
-    prev: () => void;
-    next: () => void;
+    prev: (opts?: TCarouselActionOptions) => void;
+    next: (opts?: TCarouselActionOptions) => void;
     computedIndex: () => void;
     getCurrentIndex: () => number;
     to: (index: number, animated?: boolean) => void;
+    scrollTo: (opts?: TCarouselActionOptions) => void;
 }
 
-export function useCarouselController(opts: IOpts): ICarouselController {
+export function useCarouselController(options: IOpts): ICarouselController {
     const {
         size,
         loop,
@@ -39,13 +41,26 @@ export function useCarouselController(opts: IOpts): ICarouselController {
         length,
         onChange,
         duration,
-    } = opts;
+    } = options;
 
     const index = useSharedValue<number>(0);
     // The Index displayed to the user
     const sharedIndex = React.useRef<number>(0);
     const sharedPreIndex = React.useRef<number>(0);
 
+    const currentFixedPage = React.useCallback(() => {
+        if (loop) {
+            return -Math.round(handlerOffsetX.value / size);
+        }
+
+        const fixed = (handlerOffsetX.value / size) % length;
+        return Math.round(
+            handlerOffsetX.value <= 0
+                ? Math.abs(fixed)
+                : Math.abs(fixed > 0 ? length - fixed : 0)
+        );
+    }, [handlerOffsetX, length, size, loop]);
+
     const convertToSharedIndex = React.useCallback(
         (i: number) => {
             if (loop) {
@@ -92,22 +107,22 @@ export function useCarouselController(opts: IOpts): ICarouselController {
     }, [disable]);
 
     const onScrollEnd = React.useCallback(() => {
-        opts.onScrollEnd?.();
-    }, [opts]);
+        options.onScrollEnd?.();
+    }, [options]);
 
     const onScrollBegin = React.useCallback(() => {
-        opts.onScrollBegin?.();
-    }, [opts]);
+        options.onScrollBegin?.();
+    }, [options]);
 
     const scrollWithTiming = React.useCallback(
-        (toValue: number, callback?: () => void) => {
+        (toValue: number, onFinished?: () => void) => {
             return withTiming(
                 toValue,
                 { duration, easing: Easing.easeOutQuart },
                 (isFinished: boolean) => {
-                    callback?.();
                     if (isFinished) {
                         runOnJS(onScrollEnd)();
+                        onFinished && runOnJS(onFinished)();
                     }
                 }
             );
@@ -115,42 +130,70 @@ export function useCarouselController(opts: IOpts): ICarouselController {
         [onScrollEnd, duration]
     );
 
-    const next = React.useCallback(() => {
-        if (!canSliding() || (!loop && index.value === length - 1)) return;
+    const next = React.useCallback(
+        (opts: TCarouselActionOptions = {}) => {
+            const { count = 1, animated = true, onFinished } = opts;
+            if (!canSliding() || (!loop && index.value >= length - 1)) return;
 
-        onScrollBegin?.();
+            onScrollBegin?.();
 
-        const currentPage = Math.round(handlerOffsetX.value / size);
+            const nextPage = currentFixedPage() + count;
+            index.value = nextPage;
 
-        handlerOffsetX.value = scrollWithTiming((currentPage - 1) * size);
-    }, [
-        canSliding,
-        loop,
-        index.value,
-        length,
-        onScrollBegin,
-        handlerOffsetX,
-        size,
-        scrollWithTiming,
-    ]);
+            if (animated) {
+                handlerOffsetX.value = scrollWithTiming(
+                    -nextPage * size,
+                    onFinished
+                );
+            } else {
+                handlerOffsetX.value = -nextPage * size;
+                onFinished?.();
+            }
+        },
+        [
+            canSliding,
+            loop,
+            index,
+            length,
+            onScrollBegin,
+            handlerOffsetX,
+            size,
+            scrollWithTiming,
+            currentFixedPage,
+        ]
+    );
 
-    const prev = React.useCallback(() => {
-        if (!canSliding() || (!loop && index.value === 0)) return;
+    const prev = React.useCallback(
+        (opts: TCarouselActionOptions = {}) => {
+            const { count = 1, animated = true, onFinished } = opts;
+            if (!canSliding() || (!loop && index.value <= 0)) return;
 
-        onScrollBegin?.();
+            onScrollBegin?.();
 
-        const currentPage = Math.round(handlerOffsetX.value / size);
+            const prevPage = currentFixedPage() - count;
+            index.value = prevPage;
 
-        handlerOffsetX.value = scrollWithTiming((currentPage + 1) * size);
-    }, [
-        canSliding,
-        loop,
-        index.value,
-        onScrollBegin,
-        handlerOffsetX,
-        size,
-        scrollWithTiming,
-    ]);
+            if (animated) {
+                handlerOffsetX.value = scrollWithTiming(
+                    -prevPage * size,
+                    onFinished
+                );
+            } else {
+                handlerOffsetX.value = -prevPage * size;
+                onFinished?.();
+            }
+        },
+        [
+            canSliding,
+            loop,
+            index,
+            onScrollBegin,
+            handlerOffsetX,
+            size,
+            scrollWithTiming,
+            currentFixedPage,
+        ]
+    );
 
     const to = React.useCallback(
         (idx: number, animated: boolean = false) => {
@@ -162,9 +205,8 @@ export function useCarouselController(opts: IOpts): ICarouselController {
             const offset = handlerOffsetX.value + (index.value - idx) * size;
 
             if (animated) {
-                handlerOffsetX.value = scrollWithTiming(offset, () => {
-                    index.value = idx;
-                });
+                index.value = idx;
+                handlerOffsetX.value = scrollWithTiming(offset);
             } else {
                 handlerOffsetX.value = offset;
                 index.value = idx;
@@ -182,10 +224,27 @@ export function useCarouselController(opts: IOpts): ICarouselController {
         ]
     );
 
+    const scrollTo = React.useCallback(
+        (opts: TCarouselActionOptions = {}) => {
+            const { count, animated = false, onFinished } = opts;
+            if (!count) {
+                return;
+            }
+            const n = Math.round(count);
+            if (n < 0) {
+                prev({ count: Math.abs(n), animated, onFinished });
+            } else {
+                next({ count: n, animated, onFinished });
+            }
+        },
+        [prev, next]
+    );
+
     return {
         next,
         prev,
         to,
+        scrollTo,
         index,
         length,
         sharedIndex,

package/src/hooks/useInitProps.ts

@@ -2,12 +2,20 @@ import React from 'react';
 import { DATA_LENGTH } from '../constants';
 import type { TCarouselProps } from '../types';
 
-export type TInitializeCarouselProps<T> = TCarouselProps<T> & {
-    defaultIndex: Required<TCarouselProps>['defaultIndex'];
-    loop: Required<TCarouselProps>['loop'];
-    width: Required<TCarouselProps>['width'];
-    height: Required<TCarouselProps>['height'];
-};
+type TGetRequiredProps<P extends keyof TCarouselProps> = Record<
+    P,
+    Required<TCarouselProps>[P]
+>;
+
+export type TInitializeCarouselProps<T> = TCarouselProps<T> &
+    TGetRequiredProps<
+        | 'defaultIndex'
+        | 'loop'
+        | 'width'
+        | 'height'
+        | 'scrollAnimationDuration'
+        | 'autoPlayInterval'
+    >;
 
 export function useInitProps<T>(
     props: TCarouselProps<T>
@@ -16,7 +24,8 @@ export function useInitProps<T>(
         defaultIndex = 0,
         data: _data = [],
         loop = true,
-        autoPlayInterval = 1000,
+        autoPlayInterval: _autoPlayInterval = 1000,
+        scrollAnimationDuration = 500,
         style = {},
         panGestureHandlerProps = {},
         pagingEnabled = true,
@@ -27,6 +36,7 @@ export function useInitProps<T>(
 
     const width = Math.round(_width || 0);
     const height = Math.round(_height || 0);
+    const autoPlayInterval = Math.max(_autoPlayInterval, 0);
 
     const data = React.useMemo<T[]>(() => {
         if (!loop) return _data;
@@ -55,6 +65,7 @@ export function useInitProps<T>(
         data,
         loop,
         autoPlayInterval,
+        scrollAnimationDuration,
         style,
         panGestureHandlerProps,
         pagingEnabled,

package/src/types.ts

@@ -71,6 +71,11 @@ export type TCarouselProps<T = any> = {
      * @description playback interval
      */
     autoPlayInterval?: number;
+    /**
+     * Time a scroll animation takes to finish
+     * @default 500 (ms)
+     */
+    scrollAnimationDuration?: number;
     /**
      * Carousel container style
      */
@@ -138,21 +143,29 @@ export type TCarouselProps<T = any> = {
 
 export interface ICarouselInstance {
     /**
-     * Play the last one
+     * Scroll to previous item, it takes one optional argument (count),
+     * which allows you to specify how many items to cross
      */
-    prev: () => void;
+    prev: (opts?: TCarouselActionOptions) => void;
     /**
-     * Play the next one
+     * Scroll to next item, it takes one optional argument (count),
+     * which allows you to specify how many items to cross
      */
-    next: () => void;
+    next: (opts?: TCarouselActionOptions) => void;
     /**
      * Get current item index
      */
     getCurrentIndex: () => number;
     /**
      * Go to index
+     * @deprecated use scrollTo instead
      */
     goToIndex: (index: number, animated?: boolean) => void;
+    /**
+     * Use value to scroll to a position where relative to the current position,
+     * scrollTo(-2) is equivalent to prev(2), scrollTo(2) is equivalent to next(2)
+     */
+    scrollTo: (opts?: TCarouselActionOptions) => void;
 }
 
 export interface CarouselRenderItemInfo<ItemT> {
@@ -164,3 +177,9 @@ export interface CarouselRenderItemInfo<ItemT> {
 export type CarouselRenderItem<ItemT> = (
     info: CarouselRenderItemInfo<ItemT>
 ) => React.ReactElement;
+
+export interface TCarouselActionOptions {
+    count?: number;
+    animated?: boolean;
+    onFinished?: () => void;
+}