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.

Props Programmatic Control