===============
LIBRARY RULES
===============
From library maintainers:
- Use only exports documented by src/index.tsx; v5 does not support compatibility aliases or deep imports.
- For v4-to-v5 upgrades, follow example/website/pages/migration-v5.mdx in order and run the codemod before behavioral review.
- Treat progress as a logical fractional index and scrollOffsetValue as signed pixel translation.

### Build and Run Example App

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/faq.mdx

Commands to prepare the package and launch the example application in the development environment.

```shell
yarn prepare
cd example/app
yarn install
yarn ios # or: yarn android / yarn web
```

--------------------------------

### Install dependencies

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/README.md

Commands to install the library and its required dependencies for different project types.

```bash
npx expo install react-native-reanimated-carousel react-native-reanimated react-native-worklets react-native-gesture-handler
```

```bash
yarn add react-native-reanimated-carousel react-native-reanimated react-native-worklets react-native-gesture-handler
```

--------------------------------

### Install Dependencies with Expo

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/faq.mdx

Use expo install to ensure compatible versions of the library and its native peer dependencies are installed.

```shell
npx expo install react-native-reanimated-carousel react-native-reanimated react-native-worklets react-native-gesture-handler
```

--------------------------------

### Manual Layout Migration

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v5.mdx

Example of converting v4 mode configuration to v5 layout structure.

```diff
- mode="parallax"
- modeConfig={{
-   parallaxScrollingOffset: 100,
-   parallaxScrollingScale: 0.8,
-   parallaxAdjacentItemScale: 0.64,
- }}
+ layout={{
+   type: "parallax",
+   offset: 100,
+   scale: 0.8,
+   adjacentScale: 0.64,
+ }}
```

--------------------------------

### Allowed changeset format

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/docs/changeset-style.md

Example of a correctly formatted changeset file following the summary and bullet point rules.

```md
Fix gesture blocking when `style={{ flex: 1 }}` is used.
- Preserve explicit sizing behavior.
```

--------------------------------

### Install react-native-reanimated-carousel with Expo

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/works-with-expo.mdx

Use the Expo CLI to install the carousel package into your project.

```bash
npx expo install react-native-reanimated-carousel
```

--------------------------------

### Install peer dependencies with Expo

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/works-with-expo.mdx

Install the required peer libraries through Expo to ensure version compatibility with your Expo SDK.

```bash
npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets
```

--------------------------------

### Setup CarouselRef

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Initialize a ref using CarouselRef to gain access to carousel methods.

```tsx
import * as React from "react";
import {
  Carousel,
  type CarouselRef,
} from "react-native-reanimated-carousel";

function ProductCarousel() {
  const ref = React.useRef<CarouselRef>(null);

  return (
    <Carousel
      ref={ref}
      data={products}
      keyExtractor={(product) => product.id}
      renderItem={({ item }) => <ProductCard product={item} />}
    />
  );
}
```

--------------------------------

### Basic Pagination Component

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

Example of using the basic `Pagination.Basic` component with custom dot styles.

```tsx
// Basic Pagination
<Pagination.Basic
  progress={progress}
  data={data}
  dotStyle={{ backgroundColor: "#262626" }}
  activeDotStyle={{ backgroundColor: "#f1f1f1" }}
/>
```

--------------------------------

### Configuring Carousel Animation

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/props.mdx

Examples of configuring timing and spring animations for the carousel.

```tsx
<Carousel animation={{ type: "timing", duration: 350 }} />

<Carousel
  animation={{
    type: "spring",
    damping: 18,
    stiffness: 180,
  }}
/>
```

--------------------------------

### Implement basic carousel

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/README.md

A minimal example showing how to render a carousel using the Carousel component within a GestureHandlerRootView.

```tsx
import * as React from "react";
import { Text, useWindowDimensions, View } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { Carousel } from "react-native-reanimated-carousel";

const data = ["First", "Second", "Third"];

export default function App() {
  const { width } = useWindowDimensions();

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <View style={{ flex: 1, justifyContent: "center" }}>
        <Carousel
          style={{ width, height: 200 }}
          data={data}
          renderItem={({ item }) => (
            <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
              <Text>{item}</Text>
            </View>
          )}
        />
      </View>
    </GestureHandlerRootView>
  );
}
```

--------------------------------

### Basic Carousel Implementation

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/props.mdx

A minimal example of rendering a Carousel with data and a renderItem function.

```tsx
<Carousel
  data={items}
  renderItem={({ item }) => <Slide item={item} />}
/>
```

--------------------------------

### Custom Animated Pagination Component

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

Example of using `Pagination.Custom` with a `customReanimatedStyle` function to create animated pagination dots.

```tsx
// Custom Pagination with Animation
<Pagination.Custom
  progress={progress}
  data={data}
  customReanimatedStyle={(progress, index) => {
    'worklet';
    return {
      transform: [{
        scale: interpolate(progress.value, 
          [index - 1, index, index + 1],
          [0.8, 1, 0.8]
        )
      }]
    }
  }}
/>
```

--------------------------------

### Configure Carousel Sizing

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/usage.mdx

Examples for setting fixed, responsive, and multi-item carousel dimensions using style and itemSize props.

```tsx
<Carousel
  style={{ width: 320, height: 180 }}
  data={data}
  renderItem={renderItem}
/>
```

```tsx
<View style={{ height: 220 }}>
  <Carousel
    style={{ flex: 1 }}
    data={data}
    renderItem={renderItem}
  />
</View>
```

```tsx
<Carousel
  style={{ width: 360, height: 180 }}
  itemSize={240}
  data={data}
  renderItem={renderItem}
/>
```

```tsx
<Carousel
  orientation="vertical"
  style={{ width: 240, height: 480 }}
  itemSize={180}
  data={data}
  renderItem={renderItem}
/>
```

--------------------------------

### View build output directories

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/docs/ARCHITECTURE.md

Lists the standard output directories generated by the Bob build process.

```text
lib/commonjs
lib/module
lib/typescript/commonjs
lib/typescript/module
```

--------------------------------

### Run Codemod

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v5.mdx

Commands to execute the v5 migration codemod.

```bash
npx rnrc-v5-codemod .
```

```bash
npx rnrc-v5-codemod --dry .
```

--------------------------------

### Run Repository Checks

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/faq.mdx

Commands to execute library tests, type checking, and linting from the repository root.

```shell
yarn test
yarn types
yarn lint
```

--------------------------------

### AI Agent Migration Prompt

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v5.mdx

Use this prompt to instruct an AI coding agent to perform the migration.

```text
Read https://rn-carousel.dev/migration-v5.md and upgrade react-native-reanimated-carousel to v5 in this project, then summarize what changed for my review.
```

--------------------------------

### Version Requirements for v4.x

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

Ensure your project meets these version requirements before upgrading to v4.x.

```json
{
  "react": ">=18.0.0",
  "react-native": ">=0.70.3",
  "react-native-gesture-handler": ">=2.9.0",
  "react-native-reanimated": ">=3.0.0"
}
```

--------------------------------

### Initialize Carousel with GestureHandlerRootView

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/usage.mdx

Wrap the application in GestureHandlerRootView and render the Carousel component with required data and renderItem props.

```tsx
import * as React from "react";
import { Text, useWindowDimensions, View } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { Carousel } from "react-native-reanimated-carousel";

const data = ["One", "Two", "Three"];

export default function App() {
  const { width } = useWindowDimensions();

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <View style={{ flex: 1, justifyContent: "center" }}>
        <Carousel
          data={data}
          style={{ width, height: 220 }}
          renderItem={({ item, index }) => (
            <View
              style={{
                flex: 1,
                alignItems: "center",
                justifyContent: "center",
                backgroundColor: index % 2 ? "#DCE7F7" : "#F5E7D3",
              }}
            >
              <Text>{item}</Text>
            </View>
          )}
        />
      </View>
    </GestureHandlerRootView>
  );
}
```

--------------------------------

### Run changeset validation

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/docs/changeset-style.md

Command to verify changeset formatting locally before committing.

```bash
yarn changeset:check
```

--------------------------------

### Project Dependency Requirements

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v5.mdx

Required peer dependencies for v5.

```json
{
  "react": ">=18.0.0",
  "react-native": ">=0.80.0",
  "react-native-gesture-handler": ">=2.9.0 <3.0.0",
  "react-native-reanimated": ">=4.1.0",
  "react-native-worklets": ">=0.5.0"
}
```

--------------------------------

### Configure transition animations

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/custom-animations.mdx

Define how the carousel settles into position using the animation prop with timing or spring configurations.

```tsx
<Carousel
  data={data}
  renderItem={renderItem}
  itemAnimation={itemAnimation}
  animation={{ type: "timing", duration: 350 }}
/>
```

```tsx
<Carousel
  data={data}
  renderItem={renderItem}
  itemAnimation={itemAnimation}
  animation={{
    type: "spring",
    damping: 18,
    stiffness: 180,
  }}
/>
```

--------------------------------

### Handle carousel lifecycle events

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Demonstrates usage of onScrollStart and onSnapToItem callbacks within the Carousel component.

```tsx
<Carousel
  ref={ref}
  data={products}
  renderItem={renderProduct}
  onScrollStart={() => {
    console.log("movement started");
  }}
  onSnapToItem={(index) => {
    console.log("settled on", index);
  }}
/>
```

--------------------------------

### Use built-in layouts

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/custom-animations.mdx

Apply a built-in layout configuration instead of a custom itemAnimation when applicable.

```tsx
<Carousel
  data={data}
  renderItem={renderItem}
  layout={{ type: "parallax", offset: 80, scale: 0.9 }}
/>
```

--------------------------------

### Navigate with next and prev

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Use next and prev methods on the ref to move the carousel relative to the current position.

```tsx
ref.current?.next();
ref.current?.next({ count: 3 });
ref.current?.prev({ animated: false });
ref.current?.prev({ count: 2, animated: true });
```

--------------------------------

### CarouselStepOptions Interface

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Configuration options for the next and prev navigation methods.

```ts
interface CarouselStepOptions {
  count?: number;    // positive integer, default 1
  animated?: boolean; // default true
}
```

--------------------------------

### Importing Carousel Components

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/props.mdx

Import the Carousel, Pagination, and associated types from the library.

```ts
import {
  Carousel,
  Pagination,
  type CarouselAnimation,
  type CarouselItemAnimation,
  type CarouselLayout,
  type CarouselPanGesture,
  type CarouselProgressChangeHandler,
  type CarouselProps,
  type CarouselRef,
  type CarouselRenderItem,
  type CarouselRenderItemInfo,
  type CarouselScrollToOptions,
  type CarouselStepOptions,
  type PaginationDotStyle,
  type PaginationProps,
} from "react-native-reanimated-carousel";
```

--------------------------------

### Migrate Carousel Implementation to v4.x

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

Shows the transition from v3.x to v4.x, highlighting the replacement of panGestureHandlerProps with onConfigurePanGesture and the renaming of scroll event handlers.

```tsx
// Before (v3.x)
<Carousel
  loop
  width={width}
  height={height}
  data={data}
  onScrollBegin={() => console.log('scroll started')}
  panGestureHandlerProps={{
    activeOffsetX: [-10, 10]
  }}
  enableSnap={true}
  customAnimation={(value) => ({
    opacity: value
  })}
/>

// After (v4.x)
<Carousel
  loop
  style={{ width, height }}
  data={data}
  onScrollStart={() => console.log('scroll started')}
  onConfigurePanGesture={(gesture) => {
    'worklet';
    gesture.activeOffsetX([-10, 10]);
  }}
  snapEnabled={true}
  customAnimation={(value, index) => ({
    opacity: value
  })}
  contentContainerStyle={{
    borderRadius: 8
  }}
/>
```

--------------------------------

### Exported Runtime Values

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/docs/ARCHITECTURE.md

The primary entry point exports the Carousel and Pagination components for use in applications.

```ts
export { Carousel } from "./components/Carousel";
export { Pagination } from "./components/Pagination";
```

--------------------------------

### Update Gesture Handler Configuration

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

The `panGestureHandlerProps` prop has been replaced with `onConfigurePanGesture` in v4.x. Use the new prop to configure gesture behavior.

```tsx
// Before (v3.x)
<Carousel
  panGestureHandlerProps={{
    activeOffsetX: [-10, 10],
  }}
/>

// After (v4.x)
<Carousel
  onConfigurePanGesture={(gesture) => {
    'worklet';
    gesture.activeOffsetX([-10, 10]);
  }}
/>
```

--------------------------------

### Configuring Carousel Size and Layout

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/props.mdx

Use style for the viewport and itemSize when the page distance differs from its main-axis size.

```tsx
<Carousel
  style={{ width: 360, height: 200 }}
  itemSize={240}
  data={items}
  renderItem={renderItem}
/>
```

--------------------------------

### prev()

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Moves the carousel to the previous item or set of items.

```APIDOC
## prev(options?: CarouselStepOptions)

### Description
Navigates the carousel to the previous item(s) based on the provided options.

### Parameters
- **options** (CarouselStepOptions) - Optional - Configuration for the movement.
  - **count** (number) - Optional - Number of items to move backward (default: 1).
  - **animated** (boolean) - Optional - Whether to animate the transition (default: true).
```

--------------------------------

### Default Index Handling in v4.x

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

In v4.x, `defaultIndex` is only considered on initial mount. Subsequent changes are ignored. Use the carousel ref for programmatic control.

```tsx
// Before (v3.x) - defaultIndex changes would reset the carousel
<Carousel defaultIndex={index} />

// After (v4.x) - subsequent defaultIndex changes are ignored
// Use programmatic control if you need to change the index after mount
<Carousel 
  defaultIndex={index} // Only initial value is considered
  ref={carouselRef}
/>

// To change index programmatically, use the ref:
// carouselRef.current?.scrollTo({ index: newIndex, animated: true })
// See: /programmatic-control for detailed examples
```

--------------------------------

### next()

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Moves the carousel to the next item or set of items.

```APIDOC
## next(options?: CarouselStepOptions)

### Description
Navigates the carousel to the next item(s) based on the provided options.

### Parameters
- **options** (CarouselStepOptions) - Optional - Configuration for the movement.
  - **count** (number) - Optional - Number of items to move forward (default: 1).
  - **animated** (boolean) - Optional - Whether to animate the transition (default: true).
```

--------------------------------

### Event Handler Worklets in v4.x

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

Gesture callbacks now run as worklets by default in v4.x. Use `'worklet';` directive for callbacks that should run on the UI thread.

```tsx
// Before (v3.x)
<Carousel
  onGestureStart={runOnJS(() => {
    console.log('Gesture started');
  })}
/>

// After (v4.x)
<Carousel
  onGestureStart={() => {
    'worklet';
    console.log('Gesture started');
  }}
/>
```

--------------------------------

### Handle RTL layout in custom animations

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/custom-animations.mdx

Map the sign of horizontal transformations based on I18nManager.isRTL to ensure consistent behavior.

```tsx
import { I18nManager } from "react-native";
import { interpolate } from "react-native-reanimated";
import type { CarouselItemAnimation } from "react-native-reanimated-carousel";

const rtlSign = I18nManager.isRTL ? -1 : 1;

const itemAnimation: CarouselItemAnimation = (relativeProgress) => {
  "worklet";

  const logicalX = interpolate(
    relativeProgress,
    [-1, 0, 1],
    [-80, 0, 80]
  );

  return {
    transform: [{ translateX: logicalX * rtlSign }],
  };
};
```

--------------------------------

### Update Progress Change Handling

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

In v4.x, `onProgressChange` can directly accept a SharedValue for updates, simplifying progress tracking.

```tsx
// Before (v3.x)
const progress = useSharedValue(0);
<Carousel
  onProgressChange={(offsetProgress, absoluteProgress) => {
    progress.value = absoluteProgress;
  }}
/>

// After (v4.x)
const progress = useSharedValue(0);
<Carousel
  onProgressChange={progress}
/>
```

--------------------------------

### Rename Scroll Event Handler

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

The `onScrollBegin` event handler has been renamed to `onScrollStart` in v4.x. Update your event listeners accordingly.

```tsx
// Before (v3.x)
<Carousel onScrollBegin={() => console.log('Started scrolling')} />

// After (v4.x)
<Carousel onScrollStart={() => console.log('Started scrolling')} />
```

--------------------------------

### Mechanical Rename Reference

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v5.mdx

Common import and type changes performed by the codemod.

```diff
- import Carousel, { ICarouselInstance } from "react-native-reanimated-carousel";
+ import { Carousel, type CarouselRef } from "react-native-reanimated-carousel";

- const ref = React.useRef<ICarouselInstance>(null);
+ const ref = React.useRef<CarouselRef>(null);
```

--------------------------------

### CarouselScrollToOptions interface

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Defines the configuration options for the scrollTo method.

```ts
interface CarouselScrollToOptions {
  index: number;      // required in-range raw-data index
  animated?: boolean; // default true
}
```

--------------------------------

### Configure Pan Gesture for Nested ScrollView

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/faq.mdx

Use onConfigurePanGesture to prevent the carousel from capturing parent scroll gestures by setting activeOffsetX.

```tsx
<Carousel
  {...}
  onConfigurePanGesture={(gesture) => {
    gesture.activeOffsetX([-10, 10]);
  }}
/>
```

--------------------------------

### Navigate to specific index with scrollTo

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Performs absolute index navigation. In loop mode, it automatically selects the shortest route.

```tsx
ref.current?.scrollTo({ index: 3 });
ref.current?.scrollTo({ index: 0, animated: false });
```

--------------------------------

### scrollTo

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Performs absolute raw-data index navigation to a specific item in the carousel.

```APIDOC
## scrollTo

### Description
Performs absolute raw-data index navigation. In loop mode, the command chooses the shortest route.

### Signature
`ref.current?.scrollTo({ index: number, animated?: boolean })`

### Parameters
- **index** (number) - Required - The in-range raw-data index to scroll to.
- **animated** (boolean) - Optional - Whether to animate the transition. Defaults to true.
```

--------------------------------

### Define Carousel Viewport Size

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/concepts.mdx

Sets the viewport dimensions using the style prop, which defaults to the page distance.

```tsx
<Carousel
  style={{ width: 360, height: 200 }}
  data={data}
  renderItem={renderItem}
/>
```

--------------------------------

### Update Custom Animation API

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

The `customAnimation` function in v4.x now receives the item index as a second parameter, allowing for index-based animations.

```tsx
// Before (v3.x)
<Carousel
  customAnimation={(value) => ({
    opacity: value
  })}
/>

// After (v4.x)
<Carousel
  customAnimation={(value, index) => ({
    opacity: value,
    transform: [{ 
      scale: index % 2 ? 1 : 1.1 
    }]
  })}
/>
```

--------------------------------

### CarouselItemAnimation type signature

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/custom-animations.mdx

The callback signature for defining item animations.

```ts
type CarouselItemAnimation = (
  relativeProgress: number,
  index: number
) => ViewStyle;
```

--------------------------------

### getCurrentIndex

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Retrieves the last settled raw-data index of the carousel.

```APIDOC
## getCurrentIndex

### Description
Returns the last settled raw-data index. Note that this should be read from an event handler or effect, not during render.

### Signature
`ref.current?.getCurrentIndex()`

### Returns
- **index** (number) - The current settled index, or 0 if data is empty.
```

--------------------------------

### Set Minimum Scroll Distance

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

The `minScrollDistancePerSwipe` prop in v4.x helps prevent unintended item switches by setting a minimum scroll distance required for a swipe to register.

```tsx
<Carousel
  minScrollDistancePerSwipe={15}
/>
```

--------------------------------

### Retrieve current index with getCurrentIndex

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/programmatic-control.mdx

Returns the last settled raw-data index. Avoid calling this during render as it does not trigger React updates.

```tsx
const index = ref.current?.getCurrentIndex();
```

--------------------------------

### Animate content inside a slide

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/custom-animations.mdx

Use the relativeProgress SharedValue within a Reanimated worklet to animate internal slide components.

```tsx
import Animated, {
  interpolate,
  useAnimatedStyle,
} from "react-native-reanimated";
import type { SharedValue } from "react-native-reanimated";

function AnimatedCaption({
  relativeProgress,
  title,
}: {
  relativeProgress: SharedValue<number>;
  title: string;
}) {
  const style = useAnimatedStyle(() => ({
    opacity: interpolate(
      Math.abs(relativeProgress.value),
      [0, 1],
      [1, 0]
    ),
    transform: [
      {
        translateY: interpolate(
          relativeProgress.value,
          [-1, 0, 1],
          [24, 0, -24]
        ),
      },
    ],
  }));

  return <Animated.Text style={style}>{title}</Animated.Text>;
}

<Carousel
  data={data}
  renderItem={({ item, relativeProgress }) => (
    <AnimatedCaption title={item.title} relativeProgress={relativeProgress} />
  )}
/>;
```

--------------------------------

### Carousel Component

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/props.mdx

The Carousel component is the primary interface for rendering a carousel. It accepts various props to control data, layout, and interaction.

```APIDOC
## Carousel Component

### Description
The Carousel component is the main entry point for creating carousels. It manages data rendering, layout, and user interactions.

### Parameters
#### Data and Selection
- **data** (Item[]) - Required - Raw application data.
- **renderItem** (CarouselRenderItem<Item>) - Required - JS-thread renderer for each mounted slide.
- **keyExtractor** ((item, index) => string) - Optional - Stable identity used to preserve selection.
- **defaultIndex** (number) - Optional - Mount-only initial raw-data index.
- **loop** (boolean) - Optional - Enables infinite logical wrapping.

#### Size, Orientation, and Rendering
- **orientation** ("horizontal" | "vertical") - Optional - Logical main axis.
- **itemSize** (number) - Optional - Page distance used by snapping and progress.
- **renderWindowSize** (number) - Optional - Maximum mounted slides including the current slide.
- **style** (StyleProp<ViewStyle>) - Optional - Root viewport style.
- **contentContainerStyle** (StyleProp<ViewStyle>) - Optional - Inner content layer style.
- **testID** (string) - Optional - Applied to the root viewport.
- **onLayout** ((event: LayoutChangeEvent) => void) - Optional - Root viewport layout callback.

#### Scrolling and Snapping
- **scrollEnabled** (boolean) - Optional - Enables user pan gestures.
- **snapMode** ("page" | "nearest" | "none") - Optional - Snapping behavior.
- **overscrollEnabled** (boolean) - Optional - Enables resisted overdrag and rebound.
- **animation** (CarouselAnimation) - Optional - Transition config for snapping and autoplay.
- **onConfigurePanGesture** ((gesture: CarouselPanGesture) => void) - Optional - Configures pan gesture thresholds and observers.
```

--------------------------------

### Style Carousel Content Container

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

Use the `contentContainerStyle` prop to apply styles directly to the scrollable content area of the carousel.

```tsx
<Carousel
  contentContainerStyle={{
    backgroundColor: 'white',
    borderRadius: 8,
  }}
/>
```

--------------------------------

### Define Carousel Page Size

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/concepts.mdx

Overrides the default page distance by specifying an explicit itemSize.

```tsx
<Carousel
  style={{ width: 360, height: 200 }}
  itemSize={240}
  data={data}
  renderItem={renderItem}
/>
```

--------------------------------

### Define a custom itemAnimation

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/custom-animations.mdx

Use the CarouselItemAnimation type to define a worklet-compatible function that returns a ViewStyle based on relativeProgress.

```tsx
import { interpolate } from "react-native-reanimated";
import {
  Carousel,
  type CarouselItemAnimation,
} from "react-native-reanimated-carousel";

const itemAnimation: CarouselItemAnimation = (relativeProgress) => {
  "worklet";

  return {
    opacity: interpolate(relativeProgress, [-1, 0, 1], [0.4, 1, 0.4]),
    transform: [
      {
        scale: interpolate(relativeProgress, [-1, 0, 1], [0.85, 1, 0.85]),
      },
    ],
  };
};

<Carousel
  data={data}
  renderItem={({ item }) => <Slide item={item} />}
  itemAnimation={itemAnimation}
/>;
```

--------------------------------

### Control Scroll Direction

Source: https://github.com/dohooo/react-native-reanimated-carousel/blob/main/example/website/pages/migration-v4.mdx

The `fixedDirection` prop allows you to enforce a specific scrolling direction ('positive' or 'negative') for the carousel.

```tsx
<Carousel
  fixedDirection="positive"  // or "negative"
/>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.