Props#

import { Callout } from 'nextra/components'

Basic#

data#

Carousel items data set

renderItem#

Render carousel item

defaultScrollOffsetValue#

@deprecated Use scrollOffsetValue instead.

Legacy name for the carousel scroll offset shared value. If provided, the carousel will mutate it during gestures/animations.

scrollOffsetValue#

The carousel scroll offset shared value (recommended). If provided, the carousel will mutate it during gestures/animations.

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]

vertical#

Layout items vertically instead of horizontally

width#

@deprecated Use style prop instead. e.g. style={{ width: 300 }}

Specified carousel container width (legacy v4 API)

height#

@deprecated Use style prop instead. e.g. style={{ height: 200 }}

Specified carousel container height (legacy v4 API)

mode#

Carousel Animated transitions

modeConfig#

Mode-specific animation configuration. See the Parallax Mode and Stack Mode sections below.

style#

Style of the carousel container (recommended for sizing).

If style.width / style.height are not provided, the carousel will fall back to automatic measurement via layout — but the parent layout must still constrain the size (e.g. flex: 1, or a fixed size wrapper).

itemWidth#

Horizontal page size used for snapping and animations.

This is not the same as the container width. Use this when you want multiple items visible within a single viewport.

itemHeight#

Vertical page size used for snapping and animations.

This is not the same as the container height. Use this when you want multiple rows visible at once in vertical mode.

contentContainerStyle#

Style of the carousel content container.

defaultIndex#

Default index

autoPlay#

Auto play

autoPlayReverse#

Auto play reverse playback

autoPlayInterval#

Auto play playback interval

scrollAnimationDuration#

Time a scroll animation takes to finish

loop#

Carousel loop playback

testID#

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

onSnapToItem#

Callback fired when navigating to an item

onScrollStart#

Callback fired when scroll start

onScrollEnd#

Callback fired when scroll end

withAnimation#

Specifies the scrolling animation effect.

If provided, it takes precedence over scrollAnimationDuration.

onConfigurePanGesture#

PanGesture config

windowSize#

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

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 of offset distance $0 390 780 ...$; absoluteProgress to index $0 1 2 ...$

onLayout#

Called when the carousel content container is laid out.

pagingEnabled#

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

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)

snapEnabled#

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

enableSnap#

@deprecated Use snapEnabled instead.

Legacy name for snapEnabled.

enabled#

when false, Carousel will not respond to any gestures

fixedDirection#

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

customConfig#

Custom carousel config

customAnimation#

Custom worklet animation. See Custom Animations.

maxScrollDistancePerSwipe#

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

minScrollDistancePerSwipe#

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

Parallax Mode#

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

parallaxScrollingOffset#

control prev/next item offset

parallaxScrollingScale#

control prev/current/next item scale

parallaxAdjacentItemScale#

control prev/next item scale

Stack Mode#

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

showLength#

Maximum number of cards shown in the stack. By default, the stack can show the remaining data length.

stackInterval#

The spacing of each item

moveSize#

Item translate size

scaleInterval#

The scale of each item

opacityInterval#

The opacity of each item

rotateZDeg#

The item rotation Angle

snapDirection#

Slide direction

Ref#

By using these methods, remember you need to reference the component using React useRef().

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}
        style={{ width: 300, height: 200 }} // 4. Provide size via the style 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

next#

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

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.

getCurrentIndex#

Get the current item index. Call this from an event handler or effect, not while React is rendering.