Usage#

Here is a simple usage of the React Native Reanimated Carousel. For more scrollable usage please read Scrollables.

import * as React from "react";
import { Dimensions, Text, View } from "react-native";
import { useSharedValue } from "react-native-reanimated";
import Carousel, {
  ICarouselInstance,
  Pagination,
} from "react-native-reanimated-carousel";

const data = [...new Array(6).keys()];
const width = Dimensions.get("window").width;

function App() {
  const ref = React.useRef<ICarouselInstance>(null);
  const progress = useSharedValue<number>(0);

  const onPressPagination = (index: number) => {
    ref.current?.scrollTo({
      /**
       * Calculate the difference between the current index and the target index
       * to ensure that the carousel scrolls to the nearest index
       */
      count: index - progress.value,
      animated: true,
    });
  };

  return (
    <View style={{ flex: 1 }}>
      <Carousel
        ref={ref}
        style={{ width, height: width / 2 }}
        data={data}
        onProgressChange={progress}
        renderItem={({ index }) => (
          <View
            style={{
              flex: 1,
              borderWidth: 1,
              justifyContent: "center",
            }}
            <Text style={{ textAlign: "center", fontSize: 30 }}>{index}</Text>
          </View>
        )}
      />

      <Pagination.Basic
        progress={progress}
        data={data}
        dotStyle={{ backgroundColor: "rgba(0,0,0,0.2)", borderRadius: 50 }}
        containerStyle={{ gap: 5, marginTop: 10 }}
        onPress={onPressPagination}
      />
    </View>
  );
}

export default App;

Sizing Your Carousel#

The Carousel component supports multiple ways to define its size. Understanding these options helps you achieve the layout you need.

1. Explicit Dimensions (Recommended)#

The most straightforward approach is setting explicit width and height via the style prop:

<Carousel
  style={{ width: 300, height: 200 }}
  data={data}
  renderItem={renderItem}
/>

This gives you full control over the carousel's dimensions and is the most predictable approach.

2. Flex-based Sizing#

You can use flex layout to have the carousel fill its parent container:

<View style={{ flex: 1 }}>
  <Carousel
    style={{ flex: 1 }}
    data={data}
    renderItem={renderItem}
  />
</View>

The carousel will measure its container and adapt automatically. This is useful when you want the carousel to respond to its parent's layout.

3. Custom Snap Distance with `itemWidth` / `itemHeight`#

When you want items smaller than the container with custom snapping behavior, use itemWidth (horizontal) or itemHeight (vertical):

// Container is 400px wide, but snaps every 200px (showing ~2 items)
<Carousel
  style={{ width: 400, height: 200 }}
  itemWidth={200}
  data={data}
  renderItem={renderItem}
/>

This is particularly useful for:

Showing multiple items at once
Implementing "peek" effects where adjacent items are partially visible
Custom snap intervals independent of container size

4. Legacy Props (Deprecated)#

The width and height props are deprecated but still supported for backward compatibility:

// Deprecated - use style={{ width, height }} instead
<Carousel
  width={300}
  height={200}
  data={data}
  renderItem={renderItem}
/>

We recommend migrating to the style prop for new code.

Sizing Summary#

Scenario	Props to Use	Example
Fixed size	`style={{ width, height }}`	`style={{ width: 300, height: 200 }}`
Fill parent	`style={{ flex: 1 }}`	Parent must have defined size
Custom snap	`style` + `itemWidth`/`itemHeight`	`style={{ width: 400 }} itemWidth={200}`
Vertical	`style` + `vertical`	`style={{ height: 400 }} vertical`

Important Notes#

At least one dimension is required: The carousel needs to know its size either through explicit dimensions, flex layout, or legacy props.
For horizontal carousels: Width is the primary dimension that controls snapping.
For vertical carousels: Height is the primary dimension that controls snapping.
Performance: The carousel waits for layout measurement before rendering items. With style={{ flex: 1 }}, there may be a brief moment before items appear as the component measures its container.