Props

Props


Basic

🙋‍♂️

Basically, each props should have a corresponding example, which is more intuitive, but due to time constraints, it has not been done for the time being. It is expected that someone can contribute to submit PR.

data

Carousel items data set

typedefaultrequired
T[]-

renderItem

Render carousel item

typedefaultrequired
(info: { item: T, index: number, animationValue: SharedValue<number> }) => React.ReactElement-

defaultScrollOffsetValue

The default animated value of the carousel.

typedefaultrequired
useSharedValue<number>(0)-

autoFillData

Auto fill data array to allow loop playback when the loop props is true.([1] => [1, 1, 1];[1, 2] => [1, 2, 1, 2])

typedefaultrequired
booleantrue

vertical

Layout items vertically instead of horizontally

typedefaultrequired
booleanfalse

width

Specified carousel item width

typedefaultrequired
number | undefined'100%'

height

Specified carousel item height

typedefaultrequired
number | undefined'100%'

mode

Carousel Animated transitions

typedefaultrequired
'horizontal-stack'|'vertical-stack'|'parallax'default

modeConfig

Different modes correspond to different configurations. For details, see below[modeConfig](#modeConfig Props)

typedefaultrequired
{moveSize?: number;stackInterval?: number;scaleInterval?: number;rotateZDeg?: number;snapDirection?: 'left' | 'right';}-

style

Carousel container style

typedefaultrequired
ViewStyle{}

defaultIndex

Default index

typedefaultrequired
number0

autoPlay

Auto play

typedefaultrequired
booleanfalse

autoPlayReverse

Auto play reverse playback

typedefaultrequired
booleanfalse

autoPlayInterval

Auto play playback interval

typedefaultrequired
number1000

scrollAnimationDuration

Time a scroll animation takes to finish

typedefaultrequired
number500

loop

Carousel loop playback

typedefaultrequired
booleantrue

testID

Used to locate this view in end-to-end tests

typedefaultrequired
string-

onSnapToItem

Callback fired when navigating to an item

typedefaultrequired
(index: number) => void-

onScrollStart

Callback fired when scroll start

typedefaultrequired
() => void-

onScrollEnd

Callback fired when scroll end

typedefaultrequired
(index: number) => void-

withAnimation

Specifies the scrolling animation effect

typedefaultrequired
{type: 'spring';config: WithSpringConfig;} | {type: 'timing';config: WithTimingConfig;}-

onConfigurePanGesture

PanGesture config

typedefaultrequired
onConfigurePanGesture?: (panGesture: PanGesture) => void-

windowSize

The maximum number of items that can respond to pan gesture events, 0 means all items will respond to pan gesture events

typedefaultrequired
number0

onProgressChange

This callback is called when the carousel is scrolled. If you want to update a shared value automatically, you can use the shared value as a parameter directly. The callback provides two parameters: offsetProgress:Total of offset distance (0 390 780 ...); absoluteProgress:Convert to index (0 1 2 ...)

typedefaultrequired
onProgressChange?: (offsetProgress: number,absoluteProgress: number) => void-

modeConfig

Stack layout animation style

typedefaultrequired
{moveSize?: number;stackInterval?: number;scaleInterval?: number;rotateZDeg?: number;snapDirection?: 'left' | 'right';}{ snapDirection: 'left',moveSize: window.width,stackInterval: 30,scaleInterval: 0.08,rotateZDeg: 135}

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling

typedefaultrequired
booleantrue

overscrollEnabled

If enabled, the item will scroll to the first placement when scrolling past the edge rather than closing to the last. (previous conditions: loop=false)

typedefaultrequired
booleantrue

snapEnabled

If enabled, releasing the touch will scroll to the nearest item, valid when pagingEnabled=false

typedefaultrequired
booleantrue

enabled

when false, Carousel will not respond to any gestures

typedefaultrequired
booleantrue

fixedDirection

If positive, the carousel will scroll to the positive direction and vice versa.

typedefaultrequired
'positive' | 'negative-

customConfig

Custom carousel config

typedefaultrequired
() => {type?: 'negative' | 'positive';viewCount?: number;}-

customAnimation

Custom animations. For details, see below[custom animation](./custom-animation.md)

typedefaultrequired
(value: number) => ViewStyle-

maxScrollDistancePerSwipe

Maximum offset value for one scroll. Carousel cannot scroll over than this value.

typedefaultrequired
number-

minScrollDistancePerSwipe

Minimum offset value for once scroll. If the translation value is less than this value, the carousel will not scroll.

typedefaultrequired
number-

Parallax Mode

<Carousel
    {...restProps}
    mode="parallax"
    modeConfig={{
        parallaxScrollingScale: 0.9,
        parallaxScrollingOffset: 50,
        parallaxAdjacentItemScale: 0.8,
    }}
/>

parallaxScrollingOffset

control prev/next item offset

typedefaultrequired
number100

parallaxScrollingScale

control prev/current/next item scale

typedefaultrequired
number0.8

parallaxAdjacentItemScale

control prev/next item scale

typedefaultrequired
numberparallaxAdjacentItemScale || Math.pow(parallaxScrollingScale, 2)

Stack Mode

<Carousel
    {...restProps}
    mode="stack"
    modeConfig={{
        moveSize: 200,
        stackInterval: 30,
        scaleInterval: 0.08,
        rotateZDeg: 135,
        snapDirection: 'left',
    }}
/>

stackInterval

The spacing of each item

typedefaultrequired
number18

moveSize

Item translate size

typedefaultrequired
numberscreen.width

scaleInterval

The scale of each item

typedefaultrequired
number0.04

opacityInterval

The opacity of each item

typedefaultrequired
number0.1

rotateZDeg

The item rotation Angle

typedefaultrequired
number30

snapDirection

Slide direction

typedefaultrequired
'left'|'right''left'

Ref

By using these methods, remember you need to reference the component using React useRef() (opens in a new tab).

JavaScript

const ref = React.useRef(null)

If you're using TypeScript:

You need to import:

import type { ICarouselInstance } from "react-native-reanimated-carousel";

and then:

const ref = React.useRef<ICarouselInstance>(null);

Now, you only need to pass the ref to the Carousel component:

<Carousel ref={ref} (...) />;

And now you can use these methods throughout your component. Here's an example of implementing a button to go to the next slide:

import React from "react";
import Carousel from "react-native-reanimated-carousel";
import type { ICarouselInstance } from "react-native-reanimated-carousel";
import { Button, Text, View } from "react-native";
 
// 1. Create a data array with the slides
const data = [
  {
    title: "Slide 1",
    content: "Slide 1 Content",
  },
  {
    title: "Slide 2",
    content: "Slide 2 Content",
  },
  {
    title: "Slide 3",
    content: "Slide 3 Content",
  },
];
 
const Example = () => {
  const ref = React.useRef<ICarouselInstance>(null); // 2. Create a ref for the Carousel component
 
  return (
    <View>
      {/* 3. Add the Carousel component with the ref */}
      <Carousel
        ref={ref}
        data={data}
        width={300} // 4. Add the required "width" prop
        renderItem={({ item }) => (
          <View>
            <Text>{item.title}</Text>
            <Text>{item.content}</Text>
          </View>
        )}
      />
      {/* 5. Add a button to trigger the next slide */}
      <Button
        title="Next"
        onPress={() => {
          ref.current?.next(); // 6. Call the "next" method on the ref
        }}
      />
    </View>
  );
};
 
export default Example;

prev

Scroll to previous item, it takes one optional argument (count), which allows you to specify how many items to cross

type
({ count: number, animated: boolean, onFinished?: () => void }) => void

next

Scroll to next item, it takes one optional argument (count), which allows you to specify how many items to cross

type
({ count: number, animated: boolean, onFinished?: () => void }) => void

scrollTo

scrollTo({ count: -2 })

Use count to scroll to a position where relative to the current position, scrollTo({count:-2}) is equivalent to prev(2), scrollTo({count:2}) is equivalent to next(2). And also can jump to specific position.

type
({ index: number, count: number, animated: boolean, onFinished?: () => void }) => void

getCurrentIndex

Get current item index

type
()=>number