react-native-reanimated-carousel 3.0.6 → 3.1.0

package/src/Carousel.tsx

@@ -48,15 +48,15 @@ const Carousel = React.forwardRef<ICarouselInstance, TCarouselProps<any>>(
         } = props;
 
         const commonVariables = useCommonVariables(props);
-        const { size, handlerOffsetX } = commonVariables;
+        const { size, handlerOffset } = commonVariables;
         const dataLength = data.length;
 
         const offsetX = useDerivedValue(() => {
             const totalSize = size * dataLength;
-            const x = handlerOffsetX.value % totalSize;
+            const x = handlerOffset.value % totalSize;
 
             if (!loop) {
-                return handlerOffsetX.value;
+                return handlerOffset.value;
             }
             return isNaN(x) ? 0 : x;
         }, [loop, size, dataLength]);
@@ -76,7 +76,7 @@ const Carousel = React.forwardRef<ICarouselInstance, TCarouselProps<any>>(
             size,
             data,
             autoFillData,
-            handlerOffsetX,
+            handlerOffset,
             withAnimation,
             defaultIndex,
             onScrollEnd: () => runOnJS(_onScrollEnd)(),
@@ -151,7 +151,7 @@ const Carousel = React.forwardRef<ICarouselInstance, TCarouselProps<any>>(
         const visibleRanges = useVisibleRanges({
             total: data.length,
             viewSize: size,
-            translation: handlerOffsetX,
+            translation: handlerOffset,
             windowSize,
         });
 
@@ -170,7 +170,7 @@ const Carousel = React.forwardRef<ICarouselInstance, TCarouselProps<any>>(
                     <BaseLayout
                         key={i}
                         index={i}
-                        handlerOffsetX={offsetX}
+                        handlerOffset={offsetX}
                         visibleRanges={visibleRanges}
                         animationStyle={customAnimation || layoutConfig}
                     >
@@ -201,7 +201,7 @@ const Carousel = React.forwardRef<ICarouselInstance, TCarouselProps<any>>(
                 <ScrollViewGesture
                     key={mode}
                     size={size}
-                    translation={handlerOffsetX}
+                    translation={handlerOffset}
                     style={[
                         styles.container,
                         {

package/src/hooks/useCarouselController.tsx

@@ -20,7 +20,7 @@ interface IOpts {
     size: number;
     data: TCarouselProps['data'];
     autoFillData: TCarouselProps['autoFillData'];
-    handlerOffsetX: Animated.SharedValue<number>;
+    handlerOffset: Animated.SharedValue<number>;
     withAnimation?: TCarouselProps['withAnimation'];
     duration?: number;
     defaultIndex?: number;
@@ -41,7 +41,7 @@ export function useCarouselController(options: IOpts): ICarouselController {
         size,
         data,
         loop,
-        handlerOffsetX,
+        handlerOffset,
         withAnimation,
         defaultIndex = 0,
         duration,
@@ -64,16 +64,16 @@ export function useCarouselController(options: IOpts): ICarouselController {
 
     const currentFixedPage = React.useCallback(() => {
         if (loop) {
-            return -Math.round(handlerOffsetX.value / size);
+            return -Math.round(handlerOffset.value / size);
         }
 
-        const fixed = (handlerOffsetX.value / size) % dataInfo.length;
+        const fixed = (handlerOffset.value / size) % dataInfo.length;
         return Math.round(
-            handlerOffsetX.value <= 0
+            handlerOffset.value <= 0
                 ? Math.abs(fixed)
                 : Math.abs(fixed > 0 ? dataInfo.length - fixed : 0)
         );
-    }, [handlerOffsetX, dataInfo, size, loop]);
+    }, [handlerOffset, dataInfo, size, loop]);
 
     function setSharedIndex(newSharedIndex: number) {
         sharedIndex.current = newSharedIndex;
@@ -81,9 +81,9 @@ export function useCarouselController(options: IOpts): ICarouselController {
 
     useAnimatedReaction(
         () => {
-            const handlerOffsetXValue = handlerOffsetX.value;
-            const toInt = round(handlerOffsetXValue / size) % dataInfo.length;
-            const isPositive = handlerOffsetXValue <= 0;
+            const handlerOffsetValue = handlerOffset.value;
+            const toInt = round(handlerOffsetValue / size) % dataInfo.length;
+            const isPositive = handlerOffsetValue <= 0;
             const i = isPositive
                 ? Math.abs(toInt)
                 : Math.abs(toInt > 0 ? dataInfo.length - toInt : 0);
@@ -112,7 +112,7 @@ export function useCarouselController(options: IOpts): ICarouselController {
             index,
             loop,
             autoFillData,
-            handlerOffsetX,
+            handlerOffset,
         ]
     );
 
@@ -169,12 +169,12 @@ export function useCarouselController(options: IOpts): ICarouselController {
             index.value = nextPage;
 
             if (animated) {
-                handlerOffsetX.value = scrollWithTiming(
+                handlerOffset.value = scrollWithTiming(
                     -nextPage * size,
                     onFinished
                 ) as any;
             } else {
-                handlerOffsetX.value = -nextPage * size;
+                handlerOffset.value = -nextPage * size;
                 onFinished?.();
             }
         },
@@ -184,7 +184,7 @@ export function useCarouselController(options: IOpts): ICarouselController {
             index,
             dataInfo,
             onScrollBegin,
-            handlerOffsetX,
+            handlerOffset,
             size,
             scrollWithTiming,
             currentFixedPage,
@@ -202,12 +202,12 @@ export function useCarouselController(options: IOpts): ICarouselController {
             index.value = prevPage;
 
             if (animated) {
-                handlerOffsetX.value = scrollWithTiming(
+                handlerOffset.value = scrollWithTiming(
                     -prevPage * size,
                     onFinished
                 );
             } else {
-                handlerOffsetX.value = -prevPage * size;
+                handlerOffset.value = -prevPage * size;
                 onFinished?.();
             }
         },
@@ -216,7 +216,7 @@ export function useCarouselController(options: IOpts): ICarouselController {
             loop,
             index,
             onScrollBegin,
-            handlerOffsetX,
+            handlerOffset,
             size,
             scrollWithTiming,
             currentFixedPage,
@@ -231,13 +231,13 @@ export function useCarouselController(options: IOpts): ICarouselController {
 
             onScrollBegin?.();
             // direction -> 1 | -1
-            const isPositiveZero = Object.is(handlerOffsetX.value, +0);
-            const isNegativeZero = Object.is(handlerOffsetX.value, -0);
+            const isPositiveZero = Object.is(handlerOffset.value, +0);
+            const isNegativeZero = Object.is(handlerOffset.value, -0);
             const direction = isPositiveZero
                 ? 1
                 : isNegativeZero
                 ? -1
-                : Math.sign(handlerOffsetX.value);
+                : Math.sign(handlerOffset.value);
 
             // target offset
             const offset = i * size * direction;
@@ -248,12 +248,12 @@ export function useCarouselController(options: IOpts): ICarouselController {
 
             if (loop) {
                 isCloseToNextLoop =
-                    Math.abs(handlerOffsetX.value % totalSize) / totalSize >=
+                    Math.abs(handlerOffset.value % totalSize) / totalSize >=
                     0.5;
             }
 
             const finalOffset =
-                (Math.floor(Math.abs(handlerOffsetX.value / totalSize)) +
+                (Math.floor(Math.abs(handlerOffset.value / totalSize)) +
                     (isCloseToNextLoop ? 1 : 0)) *
                     totalSize *
                     direction +
@@ -261,12 +261,9 @@ export function useCarouselController(options: IOpts): ICarouselController {
 
             if (animated) {
                 index.value = i;
-                handlerOffsetX.value = scrollWithTiming(
-                    finalOffset,
-                    onFinished
-                );
+                handlerOffset.value = scrollWithTiming(finalOffset, onFinished);
             } else {
-                handlerOffsetX.value = finalOffset;
+                handlerOffset.value = finalOffset;
                 index.value = i;
                 onFinished?.();
             }
@@ -275,7 +272,7 @@ export function useCarouselController(options: IOpts): ICarouselController {
             index,
             canSliding,
             onScrollBegin,
-            handlerOffsetX,
+            handlerOffset,
             size,
             dataInfo.length,
             loop,

package/src/hooks/useCommonVariables.ts

@@ -5,25 +5,33 @@ import type { TInitializeCarouselProps } from './useInitProps';
 interface ICommonVariables {
     size: number;
     validLength: number;
-    handlerOffsetX: Animated.SharedValue<number>;
+    handlerOffset: Animated.SharedValue<number>;
 }
 
 export function useCommonVariables(
     props: TInitializeCarouselProps<any>
 ): ICommonVariables {
-    const { vertical, height, width, data, defaultIndex } = props;
+    const {
+        vertical,
+        height,
+        width,
+        data,
+        defaultIndex,
+        defaultScrollOffsetValue,
+    } = props;
     const size = vertical ? height : width;
     const validLength = data.length - 1;
-    const defaultHandlerOffsetX = -Math.abs(defaultIndex * size);
-    const handlerOffsetX = useSharedValue<number>(defaultHandlerOffsetX);
+    const defaultHandlerOffsetValue = -Math.abs(defaultIndex * size);
+    const _handlerOffset = useSharedValue<number>(defaultHandlerOffsetValue);
+    const handlerOffset = defaultScrollOffsetValue ?? _handlerOffset;
 
     React.useEffect(() => {
-        handlerOffsetX.value = defaultHandlerOffsetX;
-    }, [vertical, handlerOffsetX, defaultHandlerOffsetX]);
+        handlerOffset.value = defaultHandlerOffsetValue;
+    }, [vertical, handlerOffset, defaultHandlerOffsetValue]);
 
     return {
         size,
         validLength,
-        handlerOffsetX,
+        handlerOffset,
     };
 }

package/src/hooks/useOffsetX.ts

@@ -8,7 +8,7 @@ import type { IVisibleRanges } from './useVisibleRanges';
 export interface IOpts {
     index: number;
     size: number;
-    handlerOffsetX: Animated.SharedValue<number>;
+    handlerOffset: Animated.SharedValue<number>;
     data: unknown[];
     type?: 'positive' | 'negative';
     viewCount?: number;
@@ -17,7 +17,7 @@ export interface IOpts {
 
 export const useOffsetX = (opts: IOpts, visibleRanges: IVisibleRanges) => {
     const {
-        handlerOffsetX,
+        handlerOffset,
         index,
         size,
         loop,
@@ -73,14 +73,14 @@ export const useOffsetX = (opts: IOpts, visibleRanges: IVisibleRanges) => {
             ];
 
             return interpolate(
-                handlerOffsetX.value,
+                handlerOffset.value,
                 inputRange,
                 outputRange,
                 Extrapolate.CLAMP
             );
         }
 
-        return handlerOffsetX.value + size * index;
+        return handlerOffset.value + size * index;
     }, [loop, data, viewCount, type, size, visibleRanges]);
 
     return x;

package/src/layouts/BaseLayout.tsx

@@ -18,7 +18,7 @@ export type TAnimationStyle = (value: number) => AnimatedStyleProp<ViewStyle>;
 
 export const BaseLayout: React.FC<{
     index: number;
-    handlerOffsetX: Animated.SharedValue<number>;
+    handlerOffset: Animated.SharedValue<number>;
     visibleRanges: IVisibleRanges;
     animationStyle: TAnimationStyle;
     children: (ctx: {
@@ -26,7 +26,7 @@ export const BaseLayout: React.FC<{
     }) => React.ReactElement;
 }> = (props) => {
     const mounted = useCheckMounted();
-    const { handlerOffsetX, index, children, visibleRanges, animationStyle } =
+    const { handlerOffset, index, children, visibleRanges, animationStyle } =
         props;
 
     const context = React.useContext(CTX);
@@ -45,7 +45,7 @@ export const BaseLayout: React.FC<{
     const size = vertical ? height : width;
     const [shouldUpdate, setShouldUpdate] = React.useState(false);
     let offsetXConfig: IOpts = {
-        handlerOffsetX,
+        handlerOffset: handlerOffset,
         index,
         size,
         data,
@@ -57,7 +57,7 @@ export const BaseLayout: React.FC<{
         const { snapDirection, showLength } = modeConfig as ILayoutConfig;
 
         offsetXConfig = {
-            handlerOffsetX,
+            handlerOffset: handlerOffset,
             index,
             size,
             data,

package/src/layouts/ParallaxLayout.tsx

@@ -16,7 +16,7 @@ export const ParallaxLayout: React.FC<
     IComputedDirectionTypes<
         {
             loop?: boolean;
-            handlerOffsetX: Animated.SharedValue<number>;
+            handlerOffset: Animated.SharedValue<number>;
             index: number;
             data: unknown[];
             visibleRanges: IVisibleRanges;
@@ -24,7 +24,7 @@ export const ParallaxLayout: React.FC<
     >
 > = (props) => {
     const {
-        handlerOffsetX,
+        handlerOffset,
         parallaxScrollingOffset = 100,
         parallaxScrollingScale = 0.8,
         parallaxAdjacentItemScale = Math.pow(parallaxScrollingScale, 2),
@@ -44,7 +44,7 @@ export const ParallaxLayout: React.FC<
 
     const x = useOffsetX(
         {
-            handlerOffsetX,
+            handlerOffset: handlerOffset,
             index,
             size,
             data,

package/src/types.ts

@@ -2,6 +2,7 @@ import type { StyleProp, ViewStyle } from 'react-native';
 import type { PanGestureHandlerProps } from 'react-native-gesture-handler';
 import type {
     AnimatedStyleProp,
+    SharedValue,
     WithSpringConfig,
     WithTimingConfig,
 } from 'react-native-reanimated';
@@ -60,6 +61,10 @@ export type WithAnimation = WithSpringAnimation | WithTimingAnimation;
 
 export type TCarouselProps<T = any> = {
     ref?: React.Ref<ICarouselInstance>;
+    /**
+     * The default animated value of the carousel.
+     */
+    defaultScrollOffsetValue?: SharedValue<number>;
     /**
      * Carousel loop playback.
      * @default true
@@ -162,7 +167,7 @@ export type TCarouselProps<T = any> = {
      */
     renderItem: CarouselRenderItem<T>;
     /**
-     * Callback fired when navigating to an item
+     * Callback fired when navigating to an item.
      */
     onSnapToItem?: (index: number) => void;
     /**