From b95a7becad8f5ef3d975dab534fc26a29fb3d590 Mon Sep 17 00:00:00 2001
From: Petr Konecny <petr.konecny@strv.com>
Date: Wed, 26 Nov 2025 23:45:09 +0100
Subject: [PATCH 1/4] chore: introduce compound pattern

---
 example/examples/AnimatedExample.tsx          |  5 ++---
 example/examples/BasicExample.tsx             |  6 +++---
 example/examples/EnteringAnimationExample.tsx | 18 +++++++-----------
 example/examples/TimerPaginationExample.tsx   | 10 +++-------
 example/examples/VideoCarouselExample.tsx     | 10 +++-------
 example/examples/components/CarouselBase.tsx  | 10 +++-------
 src/components/HeroCarousel/index.tsx         | 11 +++++++++--
 src/components/HeroCarouselSlide/index.tsx    |  6 +++---
 src/components/index.ts                       |  3 +--
 src/context/SlideContext/index.tsx            |  4 ++--
 src/context/index.tsx                         |  2 +-
 src/utils/PausableTimeout.ts                  |  2 +-
 12 files changed, 38 insertions(+), 49 deletions(-)

diff --git a/example/examples/AnimatedExample.tsx b/example/examples/AnimatedExample.tsx
index a2b0da9..e152c34 100644
--- a/example/examples/AnimatedExample.tsx
+++ b/example/examples/AnimatedExample.tsx
@@ -3,7 +3,6 @@ import {
   interpolateInsideCarousel,
   useCarouselContext,
   useAutoCarouselSlideIndex,
-  CarouselContextProvider,
 } from '@strv/react-native-hero-carousel'
 import { SafeAreaView, StyleSheet, View, Text, Dimensions } from 'react-native'
 import { Image } from 'expo-image'
@@ -75,7 +74,7 @@ export default function AnimatedExample() {
   }, [])
 
   return (
-    <CarouselContextProvider>
+    <HeroCarousel.Provider>
       <SafeAreaView style={styles.container}>
         <View style={styles.carouselContainer}>
           <HeroCarousel>
@@ -88,7 +87,7 @@ export default function AnimatedExample() {
           <Pagination total={images.length} />
         </View>
       </SafeAreaView>
-    </CarouselContextProvider>
+    </HeroCarousel.Provider>
   )
 }
 
diff --git a/example/examples/BasicExample.tsx b/example/examples/BasicExample.tsx
index 2f31d9f..f7e0450 100644
--- a/example/examples/BasicExample.tsx
+++ b/example/examples/BasicExample.tsx
@@ -1,4 +1,4 @@
-import { HeroCarousel, CarouselContextProvider } from '@strv/react-native-hero-carousel'
+import { HeroCarousel } from '@strv/react-native-hero-carousel'
 import { SafeAreaView, StyleSheet, View, Text, Dimensions } from 'react-native'
 import { Image } from 'expo-image'
 import { LinearGradient } from 'expo-linear-gradient'
@@ -38,7 +38,7 @@ export default function BasicExample() {
   }, [])
 
   return (
-    <CarouselContextProvider>
+    <HeroCarousel.Provider>
       <SafeAreaView style={styles.container}>
         <View style={styles.container}>
           <HeroCarousel>
@@ -48,7 +48,7 @@ export default function BasicExample() {
           </HeroCarousel>
         </View>
       </SafeAreaView>
-    </CarouselContextProvider>
+    </HeroCarousel.Provider>
   )
 }
 
diff --git a/example/examples/EnteringAnimationExample.tsx b/example/examples/EnteringAnimationExample.tsx
index 0f79e7e..38aa38b 100644
--- a/example/examples/EnteringAnimationExample.tsx
+++ b/example/examples/EnteringAnimationExample.tsx
@@ -1,8 +1,4 @@
-import {
-  HeroCarousel,
-  CarouselContextProvider,
-  SlideAnimatedView,
-} from '@strv/react-native-hero-carousel'
+import { HeroCarousel } from '@strv/react-native-hero-carousel'
 import { SafeAreaView, StyleSheet, View, Text, Dimensions } from 'react-native'
 import { Image } from 'expo-image'
 import { LinearGradient } from 'expo-linear-gradient'
@@ -36,17 +32,17 @@ const Slide = ({ image, title, index }: { image: string; title: string; index: n
       <Image source={{ uri: image }} style={styles.image} contentFit="cover" transition={200} />
       <LinearGradient colors={['transparent', 'rgba(0,0,0,0.8)']} style={styles.gradient}>
         <View style={styles.text}>
-          <SlideAnimatedView style={styles.textContainer} {...animationConfig}>
+          <HeroCarousel.AnimatedView style={styles.textContainer} {...animationConfig}>
             <Text style={styles.title}>{title}</Text>
-          </SlideAnimatedView>
-          <SlideAnimatedView
+          </HeroCarousel.AnimatedView>
+          <HeroCarousel.AnimatedView
             style={styles.textContainer}
             entering={FadeIn.duration(400).delay(200)}
           >
             <Text style={styles.subtitle}>
               Animation: {animationNames[index % animationNames.length]}
             </Text>
-          </SlideAnimatedView>
+          </HeroCarousel.AnimatedView>
         </View>
       </LinearGradient>
     </View>
@@ -60,7 +56,7 @@ export default function EnteringAnimationExample() {
   }, [])
 
   return (
-    <CarouselContextProvider>
+    <HeroCarousel.Provider>
       <SafeAreaView style={styles.container}>
         <View style={styles.container}>
           <HeroCarousel>
@@ -70,7 +66,7 @@ export default function EnteringAnimationExample() {
           </HeroCarousel>
         </View>
       </SafeAreaView>
-    </CarouselContextProvider>
+    </HeroCarousel.Provider>
   )
 }
 
diff --git a/example/examples/TimerPaginationExample.tsx b/example/examples/TimerPaginationExample.tsx
index db2b349..0c632e5 100644
--- a/example/examples/TimerPaginationExample.tsx
+++ b/example/examples/TimerPaginationExample.tsx
@@ -1,8 +1,4 @@
-import {
-  HeroCarousel,
-  CarouselContextProvider,
-  useAutoCarouselSlideIndex,
-} from '@strv/react-native-hero-carousel'
+import { HeroCarousel, useAutoCarouselSlideIndex } from '@strv/react-native-hero-carousel'
 import { SafeAreaView, StyleSheet, View, Text, Dimensions } from 'react-native'
 import { Image } from 'expo-image'
 import { LinearGradient } from 'expo-linear-gradient'
@@ -63,7 +59,7 @@ export default function TimerPaginationExample() {
   }
 
   return (
-    <CarouselContextProvider interval={getInterval}>
+    <HeroCarousel.Provider interval={getInterval}>
       <SafeAreaView style={styles.container}>
         <View style={styles.container}>
           <HeroCarousel>
@@ -80,7 +76,7 @@ export default function TimerPaginationExample() {
           <TimerPagination total={images.length} hideProgressOnInteraction />
         </View>
       </SafeAreaView>
-    </CarouselContextProvider>
+    </HeroCarousel.Provider>
   )
 }
 
diff --git a/example/examples/VideoCarouselExample.tsx b/example/examples/VideoCarouselExample.tsx
index 31d57a9..358355f 100644
--- a/example/examples/VideoCarouselExample.tsx
+++ b/example/examples/VideoCarouselExample.tsx
@@ -1,8 +1,4 @@
-import {
-  HeroCarousel,
-  CarouselContextProvider,
-  useAutoCarouselSlideIndex,
-} from '@strv/react-native-hero-carousel'
+import { HeroCarousel, useAutoCarouselSlideIndex } from '@strv/react-native-hero-carousel'
 import { SafeAreaView, StyleSheet, View, Text, Pressable, Dimensions, Platform } from 'react-native'
 import { useVideoPlayer, VideoView } from 'expo-video'
 import { LinearGradient } from 'expo-linear-gradient'
@@ -89,7 +85,7 @@ const Slide = ({ videoUri, title, index }: { videoUri: string; title: string; in
 
 export default function VideoCarouselExample() {
   return (
-    <CarouselContextProvider disableAutoScroll={true}>
+    <HeroCarousel.Provider disableAutoScroll={true}>
       <SafeAreaView style={styles.container}>
         <View style={styles.container}>
           <HeroCarousel>
@@ -100,7 +96,7 @@ export default function VideoCarouselExample() {
           <TimerPagination total={videos.length} hideProgressOnInteraction={false} />
         </View>
       </SafeAreaView>
-    </CarouselContextProvider>
+    </HeroCarousel.Provider>
   )
 }
 
diff --git a/example/examples/components/CarouselBase.tsx b/example/examples/components/CarouselBase.tsx
index dfbf1b3..59715b9 100644
--- a/example/examples/components/CarouselBase.tsx
+++ b/example/examples/components/CarouselBase.tsx
@@ -1,15 +1,11 @@
-import {
-  HeroCarousel,
-  HeroCarouselProps,
-  CarouselContextProvider,
-} from '@strv/react-native-hero-carousel'
+import { HeroCarousel, HeroCarouselProps } from '@strv/react-native-hero-carousel'
 import { SafeAreaView, StyleSheet, View } from 'react-native'
 import { Stack } from 'expo-router'
 import { Pagination } from '@/examples/components/Pagination'
 
 export function CarouselBase({ children }: { children: HeroCarouselProps['children'] }) {
   return (
-    <CarouselContextProvider>
+    <HeroCarousel.Provider>
       <Stack.Screen options={{ title: 'Animated Carousel' }} />
       <SafeAreaView style={styles.container}>
         <View style={styles.container}>
@@ -17,7 +13,7 @@ export function CarouselBase({ children }: { children: HeroCarouselProps['childr
           <Pagination total={children.length} />
         </View>
       </SafeAreaView>
-    </CarouselContextProvider>
+    </HeroCarousel.Provider>
   )
 }
 
diff --git a/src/components/HeroCarousel/index.tsx b/src/components/HeroCarousel/index.tsx
index 17d14a4..bd5b5e6 100644
--- a/src/components/HeroCarousel/index.tsx
+++ b/src/components/HeroCarousel/index.tsx
@@ -1,17 +1,18 @@
 import React from 'react'
 
-import { useCarouselContext } from '../../context/CarouselContext'
+import { CarouselContextProvider, useCarouselContext } from '../../context/CarouselContext'
 import { HeroCarouselSlide } from '../HeroCarouselSlide'
 import { HeroCarouselAdapter } from '../AnimatedPagedView/Adapter'
 import { useAutoScroll } from '../../hooks/useAutoScroll'
 import { useInfiniteScroll } from '../../hooks/useInfiniteScroll'
 import { DEFAULT_INTERVAL } from './index.preset'
+import { SlideAnimatedView } from 'components/SlideAnimatedView'
 
 export type HeroCarouselProps = {
   children: React.ReactNode[]
 }
 
-export const HeroCarousel = ({ children }: HeroCarouselProps) => {
+const HeroCarousel = ({ children }: HeroCarouselProps) => {
   const {
     scrollValue,
     userInteracted,
@@ -72,3 +73,9 @@ export const HeroCarousel = ({ children }: HeroCarouselProps) => {
     </>
   )
 }
+
+HeroCarousel.AnimatedView = SlideAnimatedView
+HeroCarousel.Provider = CarouselContextProvider
+HeroCarousel.Item = HeroCarouselSlide
+
+export { HeroCarousel }
diff --git a/src/components/HeroCarouselSlide/index.tsx b/src/components/HeroCarouselSlide/index.tsx
index 9277416..d756668 100644
--- a/src/components/HeroCarouselSlide/index.tsx
+++ b/src/components/HeroCarouselSlide/index.tsx
@@ -1,5 +1,5 @@
 import { View } from 'react-native'
-import { AutoCarouselSlideContext } from '../../context/SlideContext'
+import { HeroCarouselSlideContext } from '../../context/SlideContext'
 import { useAutoScroll } from '../../hooks/useAutoScroll'
 import { useMemo } from 'react'
 import { useManualScroll } from '../../hooks/useManualScroll'
@@ -21,14 +21,14 @@ export const HeroCarouselSlide = ({
 }) => {
   return (
     <View style={{ flex: 1, width, minWidth: width }}>
-      <AutoCarouselSlideContext.Provider
+      <HeroCarouselSlideContext.Provider
         value={useMemo(
           () => ({ index, total, runAutoScroll, goToPage }),
           [index, total, runAutoScroll, goToPage],
         )}
       >
         {children}
-      </AutoCarouselSlideContext.Provider>
+      </HeroCarouselSlideContext.Provider>
     </View>
   )
 }
diff --git a/src/components/index.ts b/src/components/index.ts
index cd28e97..be36b76 100644
--- a/src/components/index.ts
+++ b/src/components/index.ts
@@ -1,2 +1 @@
-export * from './HeroCarousel'
-export * from './SlideAnimatedView'
+export { HeroCarousel, HeroCarouselProps } from './HeroCarousel'
diff --git a/src/context/SlideContext/index.tsx b/src/context/SlideContext/index.tsx
index c09bc39..d2f22f6 100644
--- a/src/context/SlideContext/index.tsx
+++ b/src/context/SlideContext/index.tsx
@@ -2,7 +2,7 @@ import { createContext, useContext } from 'react'
 import { useAutoScroll } from '../../hooks/useAutoScroll'
 import { useManualScroll } from '../../hooks/useManualScroll'
 
-export const AutoCarouselSlideContext = createContext<{
+export const HeroCarouselSlideContext = createContext<{
   index: number
   total: number
   runAutoScroll: ReturnType<typeof useAutoScroll>['runAutoScroll']
@@ -10,7 +10,7 @@ export const AutoCarouselSlideContext = createContext<{
 } | null>(null)
 
 export const useAutoCarouselSlideIndex = () => {
-  const context = useContext(AutoCarouselSlideContext)
+  const context = useContext(HeroCarouselSlideContext)
   if (!context) {
     throw new Error('useAutoCarouselSlideIndex must be used within a AutoCarouselSlide')
   }
diff --git a/src/context/index.tsx b/src/context/index.tsx
index 93a6354..5b47641 100644
--- a/src/context/index.tsx
+++ b/src/context/index.tsx
@@ -1,2 +1,2 @@
-export * from './CarouselContext'
+export { useCarouselContext } from './CarouselContext'
 export * from './SlideContext'
diff --git a/src/utils/PausableTimeout.ts b/src/utils/PausableTimeout.ts
index 9c9641e..939e681 100644
--- a/src/utils/PausableTimeout.ts
+++ b/src/utils/PausableTimeout.ts
@@ -20,7 +20,7 @@ export class PausableTimeout {
   callbackStartTime: number = 0
   remaining: number = 0
   paused: boolean = false
-  timerId: NodeJS.Timeout | null = null
+  timerId: ReturnType<typeof setTimeout> | null = null
   onPause?: (remaining: number) => void = () => {}
   onResume?: (remaining: number) => void = () => {}
   _callback: () => void

From 35ebe5550d6df0c595d9ffcd0075d64f621cb04a Mon Sep 17 00:00:00 2001
From: Petr Konecny <petr.konecny@strv.com>
Date: Wed, 26 Nov 2025 23:50:03 +0100
Subject: [PATCH 2/4] chore: updated docs

---
 README.md | 191 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 154 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index 410d105..871426f 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,8 @@
 </div>
 A highly customizable, performant carousel component for React Native with advanced animations, auto-scrolling capabilities, and infinite scrolling support. Built with React Native Reanimated for smooth, native-level performance.
 
-**✨ Context-Based Configuration** - All carousel settings are configured through the context provider for a clean, centralized API.
+**✨ Compound Pattern** - Clean, intuitive API with `HeroCarousel.Provider`, `HeroCarousel.Item`, and `HeroCarousel.AnimatedView`  
+**✨ Context-Based Configuration** - All carousel settings are configured through the provider for a clean, centralized API.
 
 ## Features
 
@@ -45,7 +46,7 @@ Make sure to follow the [React Native Reanimated installation guide](https://doc
 ```tsx
 import React from 'react'
 import { View, Text, StyleSheet } from 'react-native'
-import { HeroCarousel, CarouselContextProvider } from '@strv/react-native-hero-carousel'
+import { HeroCarousel } from '@strv/react-native-hero-carousel'
 
 const slides = [
   { id: 1, title: 'Slide 1', color: '#FF6B6B' },
@@ -62,7 +63,7 @@ const Slide = ({ title, color }: { title: string; color: string }) => (
 
 export default function BasicCarousel() {
   return (
-    <CarouselContextProvider interval={4000} disableAutoScroll={false} initialIndex={0}>
+    <HeroCarousel.Provider interval={4000} disableAutoScroll={false} initialIndex={0}>
       <View style={styles.container}>
         <HeroCarousel>
           {slides.map((slide) => (
@@ -70,7 +71,7 @@ export default function BasicCarousel() {
           ))}
         </HeroCarousel>
       </View>
-    </CarouselContextProvider>
+    </HeroCarousel.Provider>
   )
 }
 
@@ -95,12 +96,22 @@ const styles = StyleSheet.create({
 
 ### Components
 
-#### `CarouselContextProvider`
+The `HeroCarousel` component uses a **compound pattern** that provides a clean, intuitive API:
+
+```tsx
+<HeroCarousel.Provider>
+  <HeroCarousel>
+    <HeroCarousel.Item>{/* Your slide content */}</HeroCarousel.Item>
+  </HeroCarousel>
+</HeroCarousel.Provider>
+```
+
+#### `HeroCarousel.Provider`
 
 The context provider that must wrap your carousel components. **All carousel configuration is passed here.**
 
 ```tsx
-<CarouselContextProvider
+<HeroCarousel.Provider
   initialIndex={0} // Initial slide index (default: 0)
   slideWidth={screenWidth} // Width of each slide (default: screen width)
   interval={3000} // Auto-scroll interval in ms
@@ -109,7 +120,7 @@ The context provider that must wrap your carousel components. **All carousel con
   autoScrollAnimation={(to, duration) => withTiming(to, { duration })} // Custom animation
 >
   {children}
-</CarouselContextProvider>
+</HeroCarousel.Provider>
 ```
 
 **Props:**
@@ -126,7 +137,7 @@ The context provider that must wrap your carousel components. **All carousel con
 
 #### `HeroCarousel`
 
-The main carousel component that renders slides. **Takes no configuration props** - all configuration is handled by the context.
+The main carousel component that renders slides. **Takes no configuration props** - all configuration is handled by the context provider.
 
 ```tsx
 <HeroCarousel>
@@ -142,6 +153,42 @@ The main carousel component that renders slides. **Takes no configuration props*
 | ---------- | ------------------- | ------------------------- |
 | `children` | `React.ReactNode[]` | Array of slide components |
 
+#### `HeroCarousel.Item`
+
+A wrapper component for individual slides. Provides slide context to child components. **Note:** This is automatically used internally when you pass children to `HeroCarousel`, but you can use it directly for more control.
+
+```tsx
+<HeroCarousel.Item>{/* Your slide content */}</HeroCarousel.Item>
+```
+
+#### `HeroCarousel.AnimatedView`
+
+A specialized animated view component that automatically handles entering/exiting animations based on carousel scroll position. Perfect for creating slide-specific animations.
+
+```tsx
+import { FadeIn, FadeOut } from 'react-native-reanimated'
+;<HeroCarousel.AnimatedView
+  entering={FadeIn.duration(400)}
+  exiting={FadeOut.duration(300)}
+  style={styles.animatedContent}
+>
+  <Text>This animates when the slide becomes active</Text>
+</HeroCarousel.AnimatedView>
+```
+
+**Props:**
+
+| Prop                      | Type                                   | Default  | Description                                              |
+| ------------------------- | -------------------------------------- | -------- | -------------------------------------------------------- |
+| `children`                | `React.ReactNode`                      | Required | Content to animate                                       |
+| `entering`                | `AnimatedProps<ViewProps>['entering']` | -        | Entering animation (from react-native-reanimated)        |
+| `exiting`                 | `AnimatedProps<ViewProps>['exiting']`  | -        | Exiting animation (from react-native-reanimated)         |
+| `layout`                  | `AnimatedProps<ViewProps>['layout']`   | -        | Layout animation (from react-native-reanimated)          |
+| `enteringThreshold`       | `number`                               | `0.99`   | Threshold (0-1) when entering animation should trigger   |
+| `exitingThreshold`        | `number`                               | `0.01`   | Threshold (0-1) when exiting animation should trigger    |
+| `keepVisibleAfterExiting` | `boolean`                              | `false`  | Keep component visible after exiting animation completes |
+| `style`                   | `AnimatedProps<ViewProps>['style']`    | -        | Additional styles                                        |
+
 ### Hooks
 
 #### `useCarouselContext()`
@@ -161,12 +208,12 @@ const { scrollValue, timeoutValue, slideWidth, userInteracted, setUserInteracted
 - `userInteracted`: Boolean indicating if user has interacted with carousel
 - `setUserInteracted`: Function to update interaction state
 
-#### `useHeroCarouselSlideIndex()`
+#### `useAutoCarouselSlideIndex()`
 
-Get the current slide information and auto-scroll controls.
+Get the current slide information and auto-scroll controls. Must be used within a slide component (inside `HeroCarousel`).
 
 ```tsx
-const { index, total, runAutoScroll, goToPage } = useHeroCarouselSlideIndex()
+const { index, total, runAutoScroll, goToPage } = useAutoCarouselSlideIndex()
 ```
 
 **Returns:**
@@ -216,23 +263,25 @@ Then scan the QR code with Expo Go or run on simulator. See the [example app REA
 
 ### 📱 Available Examples
 
-| Example                | Description                                         | Source Code                                                                       |
-| ---------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
-| **Basic Carousel**     | Simple auto-scrolling image carousel                | [`BasicExample.tsx`](./example/examples/BasicExample.tsx)                         |
-| **Animated Carousel**  | Custom animations with scale, rotation, and opacity | [`AnimatedExample.tsx`](./example/examples/AnimatedExample.tsx)                   |
-| **Video Carousel**     | Video playback with play/pause controls             | [`VideoCarouselExample.tsx`](./example/examples/VideoCarouselExample.tsx)         |
-| **Timer Pagination**   | Visual progress indicators with custom intervals    | [`TimerPaginationExample.tsx`](./example/examples/TimerPaginationExample.tsx)     |
-| **Entering Animation** | Advanced slide entrance animations                  | [`EnteringAnimationExample.tsx`](./example/examples/EnteringAnimationExample.tsx) |
-| **Offset Example**     | Custom slide positioning and spacing                | [`OffsetExample.tsx`](./example/examples/OffsetExample.tsx)                       |
+| Example                | Description                                                          | Source Code                                                                       |
+| ---------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| **Basic Carousel**     | Simple auto-scrolling image carousel                                 | [`BasicExample.tsx`](./example/examples/BasicExample.tsx)                         |
+| **Animated Carousel**  | Custom animations with scale, rotation, and opacity                  | [`AnimatedExample.tsx`](./example/examples/AnimatedExample.tsx)                   |
+| **Video Carousel**     | Video playback with play/pause controls                              | [`VideoCarouselExample.tsx`](./example/examples/VideoCarouselExample.tsx)         |
+| **Timer Pagination**   | Visual progress indicators with custom intervals                     | [`TimerPaginationExample.tsx`](./example/examples/TimerPaginationExample.tsx)     |
+| **Entering Animation** | Advanced slide entrance animations using `HeroCarousel.AnimatedView` | [`EnteringAnimationExample.tsx`](./example/examples/EnteringAnimationExample.tsx) |
+| **Offset Example**     | Custom slide positioning and spacing                                 | [`OffsetExample.tsx`](./example/examples/OffsetExample.tsx)                       |
 
 ### 🎯 Key Example Features
 
 - **Image Carousels** with smooth transitions and auto-scrolling
 - **Video Integration** with `expo-video` and playback controls
 - **Custom Animations** using `interpolateInsideCarousel` utility
+- **Entering/Exiting Animations** using `HeroCarousel.AnimatedView` component
 - **Timer-based Pagination** with visual progress bars
 - **Gesture Handling** with swipe navigation and user interaction detection
 - **Performance Optimization** with image preloading and memoization
+- **Compound Pattern** - All examples use `HeroCarousel.Provider` for configuration
 
 ### 📍 Pagination Examples
 
@@ -253,38 +302,87 @@ All pagination components automatically sync with the carousel state and support
 
 ### Configuration Examples
 
-Different carousel configurations using the context provider:
+Different carousel configurations using the compound pattern:
 
 ```tsx
 // Basic auto-scrolling carousel
-<CarouselContextProvider interval={3000}>
+<HeroCarousel.Provider interval={3000}>
   <HeroCarousel>{slides}</HeroCarousel>
-</CarouselContextProvider>
+</HeroCarousel.Provider>
 
 // Video carousel without auto-scroll
-<CarouselContextProvider disableAutoScroll>
+<HeroCarousel.Provider disableAutoScroll>
   <HeroCarousel>{videoSlides}</HeroCarousel>
-</CarouselContextProvider>
+</HeroCarousel.Provider>
 
 // Carousel with custom intervals per slide
-<CarouselContextProvider interval={(index) => (index + 1) * 2000}>
+<HeroCarousel.Provider interval={(index) => (index + 1) * 2000}>
   <HeroCarousel>{slides}</HeroCarousel>
-</CarouselContextProvider>
+</HeroCarousel.Provider>
 
 // Carousel starting from specific slide
-<CarouselContextProvider initialIndex={2} disableInfiniteScroll>
+<HeroCarousel.Provider initialIndex={2} disableInfiniteScroll>
   <HeroCarousel>{slides}</HeroCarousel>
-</CarouselContextProvider>
+</HeroCarousel.Provider>
 
 // Custom slide width and animation
-<CarouselContextProvider
+<HeroCarousel.Provider
   slideWidth={300}
   autoScrollAnimation={(to, duration) => withSpring(to, { damping: 15 })}
 >
   <HeroCarousel>{slides}</HeroCarousel>
-</CarouselContextProvider>
+</HeroCarousel.Provider>
+```
+
+### Using HeroCarousel.AnimatedView
+
+The `HeroCarousel.AnimatedView` component automatically handles entering/exiting animations based on carousel scroll position. Perfect for creating slide-specific animations:
+
+```tsx
+import { HeroCarousel } from '@strv/react-native-hero-carousel'
+import { FadeIn, FadeOut, SlideInDown } from 'react-native-reanimated'
+
+const Slide = ({ title, image }: { title: string; image: string }) => (
+  <View style={styles.slide}>
+    <Image source={{ uri: image }} style={styles.image} />
+
+    {/* Content that animates when slide becomes active */}
+    <HeroCarousel.AnimatedView
+      entering={FadeIn.duration(400)}
+      exiting={FadeOut.duration(300)}
+      style={styles.content}
+    >
+      <Text style={styles.title}>{title}</Text>
+    </HeroCarousel.AnimatedView>
+
+    {/* Multiple animated views with different timings */}
+    <HeroCarousel.AnimatedView
+      entering={SlideInDown.duration(500).delay(200)}
+      style={styles.subtitle}
+    >
+      <Text>Subtitle with delay</Text>
+    </HeroCarousel.AnimatedView>
+  </View>
+)
+
+// Usage
+<HeroCarousel.Provider>
+  <HeroCarousel>
+    {slides.map((slide) => (
+      <Slide key={slide.id} {...slide} />
+    ))}
+  </HeroCarousel>
+</HeroCarousel.Provider>
 ```
 
+**Key Features:**
+
+- Automatically triggers entering animation when slide becomes active
+- Triggers exiting animation when slide leaves view
+- Supports all Reanimated entering/exiting animations
+- Configurable thresholds for animation timing
+- Can keep content visible after exiting animation
+
 ### Programmatic Navigation
 
 Control the carousel programmatically using the context:
@@ -292,7 +390,7 @@ Control the carousel programmatically using the context:
 ```tsx
 const CarouselWithControls = () => {
   const { scrollValue, goToPage } = useCarouselContext()
-  const { runAutoScroll } = useHeroCarouselSlideIndex()
+  const { runAutoScroll } = useAutoCarouselSlideIndex()
 
   const goToNext = () => {
     runAutoScroll(0) // Immediate transition
@@ -303,7 +401,7 @@ const CarouselWithControls = () => {
   }
 
   return (
-    <CarouselContextProvider disableAutoScroll>
+    <HeroCarousel.Provider disableAutoScroll>
       <View>
         <HeroCarousel>{/* Your slides */}</HeroCarousel>
 
@@ -312,7 +410,7 @@ const CarouselWithControls = () => {
           <Button title="Next" onPress={goToNext} />
         </View>
       </View>
-    </CarouselContextProvider>
+    </HeroCarousel.Provider>
   )
 }
 ```
@@ -338,15 +436,34 @@ useEffect(() => {
 
 ## Architecture
 
+### Compound Pattern
+
+This library uses a **compound component pattern** that provides a clean, intuitive API:
+
+```tsx
+<HeroCarousel.Provider>
+  <HeroCarousel>
+    <HeroCarousel.Item>
+      <HeroCarousel.AnimatedView>{/* Your content */}</HeroCarousel.AnimatedView>
+    </HeroCarousel.Item>
+  </HeroCarousel>
+</HeroCarousel.Provider>
+```
+
 ### Context-Based Configuration
 
-This library uses a **context-based architecture** where all carousel configuration is passed to the `CarouselContextProvider` rather than individual components. This design provides several benefits:
+All carousel configuration is passed to the `HeroCarousel.Provider` rather than individual components. This design provides several benefits:
 
 ✅ **Centralized Configuration** - All settings in one place  
 ✅ **Cleaner Component API** - Components focus on rendering, not configuration  
-✅ **Easier Testing** - Mock context for isolated component testing
+✅ **Easier Testing** - Mock context for isolated component testing  
+✅ **Flexible Composition** - Components like pagination can be placed anywhere within the provider
+
+The compound pattern allows for:
 
-That allows for components like pagination to not be attached to the carousel component.
+- **Intuitive API** - Related components are grouped under `HeroCarousel.*`
+- **Better Discoverability** - All carousel-related components are accessible via autocomplete
+- **Flexible Usage** - Use `HeroCarousel.Item` and `HeroCarousel.AnimatedView` when needed, or pass children directly to `HeroCarousel`
 
 ## Troubleshooting
 
@@ -354,7 +471,7 @@ That allows for components like pagination to not be attached to the carousel co
 
 **Carousel not auto-scrolling:**
 
-- Ensure `CarouselContextProvider` wraps your carousel
+- Ensure `HeroCarousel.Provider` wraps your carousel
 - Check if `disableAutoScroll` is set to `false`
 - Verify React Native Reanimated is properly installed
 

From 891f599bffdc67003c6b3a3afe147f816568c890 Mon Sep 17 00:00:00 2001
From: Petr Konecny <petr.konecny@strv.com>
Date: Thu, 27 Nov 2025 00:57:24 +0100
Subject: [PATCH 3/4] chore: added helper hook for interpolated values

---
 README.md                                  | 48 +++++++++----
 example/components/Collapsible.tsx         | 46 ------------
 example/components/ExternalLink.tsx        | 24 -------
 example/components/HapticTab.tsx           | 18 -----
 example/components/HelloWave.tsx           | 40 -----------
 example/components/ParallaxScrollView.tsx  | 84 ----------------------
 example/examples/AnimatedExample.tsx       | 28 +++-----
 example/examples/VideoCarouselExample.tsx  | 12 ++--
 example/hooks/useActiveSlideEffect.ts      | 55 --------------
 src/components/HeroCarousel/index.tsx      |  2 +-
 src/components/SlideAnimatedView/index.tsx | 18 +++--
 src/hooks/index.tsx                        |  2 +
 src/hooks/useActiveItemEffect.ts           | 42 +++++++++++
 src/hooks/useInterpolateInsideCarousel.ts  | 16 +++++
 src/index.ts                               |  1 +
 15 files changed, 123 insertions(+), 313 deletions(-)
 delete mode 100644 example/components/Collapsible.tsx
 delete mode 100644 example/components/ExternalLink.tsx
 delete mode 100644 example/components/HapticTab.tsx
 delete mode 100644 example/components/HelloWave.tsx
 delete mode 100644 example/components/ParallaxScrollView.tsx
 delete mode 100644 example/hooks/useActiveSlideEffect.ts
 create mode 100644 src/hooks/index.tsx
 create mode 100644 src/hooks/useActiveItemEffect.ts
 create mode 100644 src/hooks/useInterpolateInsideCarousel.ts

diff --git a/README.md b/README.md
index 871426f..3a5155f 100644
--- a/README.md
+++ b/README.md
@@ -223,30 +223,52 @@ const { index, total, runAutoScroll, goToPage } = useAutoCarouselSlideIndex()
 - `runAutoScroll`: Function to manually trigger auto-scroll with custom interval
 - `goToPage`: Function to programmatically navigate to a specific slide from another slide
 
-### Utilities
+#### `useInterpolateInsideCarousel()`
 
-#### `interpolateInsideCarousel()`
-
-Advanced interpolation utility for creating custom slide animations.
+Hook for creating custom slide animations with automatic interpolation based on carousel scroll position. Must be used within a slide component (inside `HeroCarousel`). Returns a `SharedValue` that you can use in animated styles.
 
 ```tsx
-import { interpolateInsideCarousel } from '@strv/react-native-hero-carousel'
+import { useInterpolateInsideCarousel } from '@strv/react-native-hero-carousel'
+import Animated, { useAnimatedStyle, interpolate, Extrapolation } from 'react-native-reanimated'
 
-const animatedStyle = useAnimatedStyle(() => {
-  const progress = interpolateInsideCarousel(scrollValue.value, slideIndex, total, {
+const Slide = () => {
+  const progress = useInterpolateInsideCarousel({
     valueBefore: 0, // Value for slides before current
     thisValue: 1, // Value for current slide
     valueAfter: 0, // Value for slides after current
     offset: 0.2, // Animation offset (optional)
   })
 
-  return {
-    opacity: progress,
-    transform: [{ scale: progress }],
-  }
-})
+  const animatedStyle = useAnimatedStyle(() => {
+    return {
+      opacity: progress.value,
+      transform: [
+        {
+          scale: interpolate(progress.value, [0, 1], [0.8, 1], Extrapolation.CLAMP),
+        },
+      ],
+    }
+  })
+
+  return <Animated.View style={animatedStyle}>{/* Your content */}</Animated.View>
+}
 ```
 
+**Returns:**
+
+A `SharedValue` (from `useDerivedValue`) representing the interpolated progress value (0-1) based on the current slide's position in the carousel. Access the value using `.value` in animated styles or worklet functions.
+
+**Parameters:**
+
+| Parameter     | Type     | Default  | Description                                                      |
+| ------------- | -------- | -------- | ---------------------------------------------------------------- |
+| `valueBefore` | `number` | Required | Value to use for slides before the current slide                 |
+| `thisValue`   | `number` | Required | Value to use for the current slide                               |
+| `valueAfter`  | `number` | Required | Value to use for slides after the current slide                  |
+| `offset`      | `number` | `0`      | Animation offset (0-1) to control when the animation starts/ends |
+
+**Note:** The `interpolateInsideCarousel` utility function is now internal-only. Use this hook instead for all custom animations. The hook automatically handles the slide context (index, total, scrollValue) internally.
+
 ## Examples
 
 We provide a comprehensive example app showcasing all the carousel features. You can run the examples locally or view the source code:
@@ -276,7 +298,7 @@ Then scan the QR code with Expo Go or run on simulator. See the [example app REA
 
 - **Image Carousels** with smooth transitions and auto-scrolling
 - **Video Integration** with `expo-video` and playback controls
-- **Custom Animations** using `interpolateInsideCarousel` utility
+- **Custom Animations** using `useInterpolateInsideCarousel` hook
 - **Entering/Exiting Animations** using `HeroCarousel.AnimatedView` component
 - **Timer-based Pagination** with visual progress bars
 - **Gesture Handling** with swipe navigation and user interaction detection
diff --git a/example/components/Collapsible.tsx b/example/components/Collapsible.tsx
deleted file mode 100644
index 0a8c5a1..0000000
--- a/example/components/Collapsible.tsx
+++ /dev/null
@@ -1,46 +0,0 @@
-import { PropsWithChildren, useState } from 'react'
-import { StyleSheet, TouchableOpacity } from 'react-native'
-
-import { ThemedText } from '@/components/ThemedText'
-import { ThemedView } from '@/components/ThemedView'
-import { IconSymbol } from '@/components/ui/IconSymbol'
-import { Colors } from '@/constants/Colors'
-import { useColorScheme } from '@/hooks/useColorScheme'
-
-export function Collapsible({ children, title }: PropsWithChildren & { title: string }) {
-  const [isOpen, setIsOpen] = useState(false)
-  const theme = useColorScheme() ?? 'light'
-
-  return (
-    <ThemedView>
-      <TouchableOpacity
-        style={styles.heading}
-        onPress={() => setIsOpen((value) => !value)}
-        activeOpacity={0.8}
-      >
-        <IconSymbol
-          name="chevron.right"
-          size={18}
-          weight="medium"
-          color={theme === 'light' ? Colors.light.icon : Colors.dark.icon}
-          style={{ transform: [{ rotate: isOpen ? '90deg' : '0deg' }] }}
-        />
-
-        <ThemedText type="defaultSemiBold">{title}</ThemedText>
-      </TouchableOpacity>
-      {isOpen && <ThemedView style={styles.content}>{children}</ThemedView>}
-    </ThemedView>
-  )
-}
-
-const styles = StyleSheet.create({
-  heading: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: 6,
-  },
-  content: {
-    marginTop: 6,
-    marginLeft: 24,
-  },
-})
diff --git a/example/components/ExternalLink.tsx b/example/components/ExternalLink.tsx
deleted file mode 100644
index d57ab1e..0000000
--- a/example/components/ExternalLink.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import { Href, Link } from 'expo-router'
-import { openBrowserAsync } from 'expo-web-browser'
-import { type ComponentProps } from 'react'
-import { Platform } from 'react-native'
-
-type Props = Omit<ComponentProps<typeof Link>, 'href'> & { href: Href & string }
-
-export function ExternalLink({ href, ...rest }: Props) {
-  return (
-    <Link
-      target="_blank"
-      {...rest}
-      href={href}
-      onPress={async (event) => {
-        if (Platform.OS !== 'web') {
-          // Prevent the default behavior of linking to the default browser on native.
-          event.preventDefault()
-          // Open the link in an in-app browser.
-          await openBrowserAsync(href)
-        }
-      }}
-    />
-  )
-}
diff --git a/example/components/HapticTab.tsx b/example/components/HapticTab.tsx
deleted file mode 100644
index d7f0c3e..0000000
--- a/example/components/HapticTab.tsx
+++ /dev/null
@@ -1,18 +0,0 @@
-import { BottomTabBarButtonProps } from '@react-navigation/bottom-tabs'
-import { PlatformPressable } from '@react-navigation/elements'
-import * as Haptics from 'expo-haptics'
-
-export function HapticTab(props: BottomTabBarButtonProps) {
-  return (
-    <PlatformPressable
-      {...props}
-      onPressIn={(ev) => {
-        if (process.env.EXPO_OS === 'ios') {
-          // Add a soft haptic feedback when pressing down on the tabs.
-          Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light)
-        }
-        props.onPressIn?.(ev)
-      }}
-    />
-  )
-}
diff --git a/example/components/HelloWave.tsx b/example/components/HelloWave.tsx
deleted file mode 100644
index 377e1b3..0000000
--- a/example/components/HelloWave.tsx
+++ /dev/null
@@ -1,40 +0,0 @@
-import { useEffect } from 'react'
-import { StyleSheet } from 'react-native'
-import Animated, {
-  useAnimatedStyle,
-  useSharedValue,
-  withRepeat,
-  withSequence,
-  withTiming,
-} from 'react-native-reanimated'
-
-import { ThemedText } from '@/components/ThemedText'
-
-export function HelloWave() {
-  const rotationAnimation = useSharedValue(0)
-
-  useEffect(() => {
-    rotationAnimation.value = withRepeat(
-      withSequence(withTiming(25, { duration: 150 }), withTiming(0, { duration: 150 })),
-      4, // Run the animation 4 times
-    )
-  }, [rotationAnimation])
-
-  const animatedStyle = useAnimatedStyle(() => ({
-    transform: [{ rotate: `${rotationAnimation.value}deg` }],
-  }))
-
-  return (
-    <Animated.View style={animatedStyle}>
-      <ThemedText style={styles.text}>👋</ThemedText>
-    </Animated.View>
-  )
-}
-
-const styles = StyleSheet.create({
-  text: {
-    fontSize: 28,
-    lineHeight: 32,
-    marginTop: -6,
-  },
-})
diff --git a/example/components/ParallaxScrollView.tsx b/example/components/ParallaxScrollView.tsx
deleted file mode 100644
index 8283eb2..0000000
--- a/example/components/ParallaxScrollView.tsx
+++ /dev/null
@@ -1,84 +0,0 @@
-import type { PropsWithChildren, ReactElement } from 'react'
-import { StyleSheet } from 'react-native'
-import Animated, {
-  interpolate,
-  useAnimatedRef,
-  useAnimatedStyle,
-  useScrollViewOffset,
-} from 'react-native-reanimated'
-
-import { ThemedView } from '@/components/ThemedView'
-import { useBottomTabOverflow } from '@/components/ui/TabBarBackground'
-import { useColorScheme } from '@/hooks/useColorScheme'
-
-const HEADER_HEIGHT = 250
-
-type Props = PropsWithChildren<{
-  headerImage: ReactElement
-  headerBackgroundColor: { dark: string; light: string }
-}>
-
-export default function ParallaxScrollView({
-  children,
-  headerImage,
-  headerBackgroundColor,
-}: Props) {
-  const colorScheme = useColorScheme() ?? 'light'
-  const scrollRef = useAnimatedRef<Animated.ScrollView>()
-  const scrollOffset = useScrollViewOffset(scrollRef)
-  const bottom = useBottomTabOverflow()
-  const headerAnimatedStyle = useAnimatedStyle(() => {
-    return {
-      transform: [
-        {
-          translateY: interpolate(
-            scrollOffset.value,
-            [-HEADER_HEIGHT, 0, HEADER_HEIGHT],
-            [-HEADER_HEIGHT / 2, 0, HEADER_HEIGHT * 0.75],
-          ),
-        },
-        {
-          scale: interpolate(scrollOffset.value, [-HEADER_HEIGHT, 0, HEADER_HEIGHT], [2, 1, 1]),
-        },
-      ],
-    }
-  })
-
-  return (
-    <ThemedView style={styles.container}>
-      <Animated.ScrollView
-        ref={scrollRef}
-        scrollEventThrottle={16}
-        scrollIndicatorInsets={{ bottom }}
-        contentContainerStyle={{ paddingBottom: bottom }}
-      >
-        <Animated.View
-          style={[
-            styles.header,
-            { backgroundColor: headerBackgroundColor[colorScheme] },
-            headerAnimatedStyle,
-          ]}
-        >
-          {headerImage}
-        </Animated.View>
-        <ThemedView style={styles.content}>{children}</ThemedView>
-      </Animated.ScrollView>
-    </ThemedView>
-  )
-}
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-  },
-  header: {
-    height: HEADER_HEIGHT,
-    overflow: 'hidden',
-  },
-  content: {
-    flex: 1,
-    padding: 32,
-    gap: 16,
-    overflow: 'hidden',
-  },
-})
diff --git a/example/examples/AnimatedExample.tsx b/example/examples/AnimatedExample.tsx
index e152c34..8be0627 100644
--- a/example/examples/AnimatedExample.tsx
+++ b/example/examples/AnimatedExample.tsx
@@ -1,9 +1,4 @@
-import {
-  HeroCarousel,
-  interpolateInsideCarousel,
-  useCarouselContext,
-  useAutoCarouselSlideIndex,
-} from '@strv/react-native-hero-carousel'
+import { HeroCarousel, useInterpolateInsideCarousel } from '@strv/react-native-hero-carousel'
 import { SafeAreaView, StyleSheet, View, Text, Dimensions } from 'react-native'
 import { Image } from 'expo-image'
 import { LinearGradient } from 'expo-linear-gradient'
@@ -23,17 +18,14 @@ const getRandomImageUrl = () => {
 const images = Array.from({ length: 5 }, getRandomImageUrl)
 
 const Slide = ({ image, title, index }: { image: string; title: string; index: number }) => {
-  const { scrollValue } = useCarouselContext()
-  const { index: slideIndex, total } = useAutoCarouselSlideIndex()
+  const progress = useInterpolateInsideCarousel({
+    valueBefore: 0,
+    thisValue: 1,
+    valueAfter: 0,
+    offset: 0.2,
+  })
 
   const rStyle = useAnimatedStyle(() => {
-    const progress = interpolateInsideCarousel(scrollValue.value, slideIndex, total, {
-      valueBefore: 0,
-      thisValue: 1,
-      valueAfter: 0,
-      offset: 0.2,
-    })
-
     return {
       flex: 1,
       width: '100%',
@@ -43,13 +35,13 @@ const Slide = ({ image, title, index }: { image: string; title: string; index: n
       transformOrigin: 'center',
       transform: [
         {
-          scale: interpolate(progress, [0, 1], [0.8, 1], Extrapolation.CLAMP),
+          scale: interpolate(progress.value, [0, 1], [0.8, 1], Extrapolation.CLAMP),
         },
         {
-          rotate: `${interpolate(progress, [0, 1], [-15, 0], Extrapolation.CLAMP)}deg`,
+          rotate: `${interpolate(progress.value, [0, 1], [-15, 0], Extrapolation.CLAMP)}deg`,
         },
       ],
-      opacity: progress,
+      opacity: progress.value,
     }
   })
 
diff --git a/example/examples/VideoCarouselExample.tsx b/example/examples/VideoCarouselExample.tsx
index 358355f..ffe4bbf 100644
--- a/example/examples/VideoCarouselExample.tsx
+++ b/example/examples/VideoCarouselExample.tsx
@@ -1,8 +1,12 @@
-import { HeroCarousel, useAutoCarouselSlideIndex } from '@strv/react-native-hero-carousel'
+import {
+  HeroCarousel,
+  useAutoCarouselSlideIndex,
+  useActiveItemEffect,
+  useIsActiveItem,
+} from '@strv/react-native-hero-carousel'
 import { SafeAreaView, StyleSheet, View, Text, Pressable, Dimensions, Platform } from 'react-native'
 import { useVideoPlayer, VideoView } from 'expo-video'
 import { LinearGradient } from 'expo-linear-gradient'
-import { useActiveSlideEffect, useIsActiveSlide } from '@/hooks/useActiveSlideEffect'
 import { useEffect, useRef, useState } from 'react'
 import { TimerPagination } from './components/TimerPagination'
 import { useEvent, useEventListener } from 'expo'
@@ -26,9 +30,9 @@ const videoTitles = [
 const Slide = ({ videoUri, title, index }: { videoUri: string; title: string; index: number }) => {
   const player = useVideoPlayer(videoUri)
   const { runAutoScroll } = useAutoCarouselSlideIndex()
-  const isActiveSlide = useIsActiveSlide()
+  const isActiveSlide = useIsActiveItem()
   const [duration, setDuration] = useState(0)
-  useActiveSlideEffect(() => {
+  useActiveItemEffect(() => {
     player.currentTime = 0
     player.play()
     return () => {
diff --git a/example/hooks/useActiveSlideEffect.ts b/example/hooks/useActiveSlideEffect.ts
deleted file mode 100644
index f9faf47..0000000
--- a/example/hooks/useActiveSlideEffect.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-import {
-  interpolateInsideCarousel,
-  useAutoCarouselSlideIndex,
-  useCarouselContext,
-} from '@strv/react-native-hero-carousel'
-import { useState } from 'react'
-import { runOnJS, useAnimatedReaction, useDerivedValue } from 'react-native-reanimated'
-
-export const useIsActiveSlide = () => {
-  const { index, total } = useAutoCarouselSlideIndex()
-  const { scrollValue } = useCarouselContext()
-  const [isActive, setIsActive] = useState(false)
-  useAnimatedReaction(
-    () => scrollValue.value,
-    (value) => {
-      const result = interpolateInsideCarousel(value, index, total, {
-        valueBefore: 0,
-        thisValue: 1,
-        valueAfter: 0,
-      })
-      if (result === 1) {
-        runOnJS(setIsActive)(true)
-      } else {
-        runOnJS(setIsActive)(false)
-      }
-    },
-    [index, total],
-  )
-  return isActive
-}
-
-export const useActiveSlideEffect = (
-  effectFunc: () => () => void | undefined,
-  deps: any[] = [],
-) => {
-  const { index, total } = useAutoCarouselSlideIndex()
-  const { scrollValue } = useCarouselContext()
-  const value = useDerivedValue(() => {
-    return interpolateInsideCarousel(scrollValue.value, index, total, {
-      valueBefore: 0,
-      thisValue: 1,
-      valueAfter: 0,
-    })
-  })
-
-  useAnimatedReaction(
-    () => value.value,
-    (value) => {
-      if (value === 1) {
-        runOnJS(effectFunc)()
-      }
-    },
-    deps,
-  )
-}
diff --git a/src/components/HeroCarousel/index.tsx b/src/components/HeroCarousel/index.tsx
index bd5b5e6..d4cc003 100644
--- a/src/components/HeroCarousel/index.tsx
+++ b/src/components/HeroCarousel/index.tsx
@@ -6,7 +6,7 @@ import { HeroCarouselAdapter } from '../AnimatedPagedView/Adapter'
 import { useAutoScroll } from '../../hooks/useAutoScroll'
 import { useInfiniteScroll } from '../../hooks/useInfiniteScroll'
 import { DEFAULT_INTERVAL } from './index.preset'
-import { SlideAnimatedView } from 'components/SlideAnimatedView'
+import { SlideAnimatedView } from '../SlideAnimatedView'
 
 export type HeroCarouselProps = {
   children: React.ReactNode[]
diff --git a/src/components/SlideAnimatedView/index.tsx b/src/components/SlideAnimatedView/index.tsx
index ef701b0..fadaf41 100644
--- a/src/components/SlideAnimatedView/index.tsx
+++ b/src/components/SlideAnimatedView/index.tsx
@@ -1,13 +1,12 @@
-import { useAutoCarouselSlideIndex, useCarouselContext } from '../../context'
 import Animated, {
   useDerivedValue,
   useAnimatedReaction,
   runOnJS,
   AnimatedProps,
 } from 'react-native-reanimated'
-import { interpolateInsideCarousel } from '../../utils'
 import { useState } from 'react'
 import { ViewProps } from 'react-native'
+import { useInterpolateInsideCarousel } from '../../hooks/useInterpolateInsideCarousel'
 
 type SlideAnimatedViewProps = {
   children: React.ReactNode
@@ -30,17 +29,16 @@ export const SlideAnimatedView = ({
   keepVisibleAfterExiting = false,
   style,
 }: SlideAnimatedViewProps) => {
-  const { index, total } = useAutoCarouselSlideIndex()
-  const { scrollValue } = useCarouselContext()
+  const progress = useInterpolateInsideCarousel({
+    valueBefore: 0,
+    thisValue: 1,
+    valueAfter: 0,
+  })
   const [shouldShow, setShouldShow] = useState(false)
 
   const value = useDerivedValue(() => {
-    return interpolateInsideCarousel(scrollValue.value, index, total, {
-      valueBefore: 0,
-      thisValue: 1,
-      valueAfter: 0,
-    })
-  }, [index, total, scrollValue])
+    return progress.value
+  }, [progress])
 
   // Track when value becomes 1 to trigger entering animation
   useAnimatedReaction(
diff --git a/src/hooks/index.tsx b/src/hooks/index.tsx
new file mode 100644
index 0000000..921c2be
--- /dev/null
+++ b/src/hooks/index.tsx
@@ -0,0 +1,2 @@
+export { useInterpolateInsideCarousel } from './useInterpolateInsideCarousel'
+export * from './useActiveItemEffect'
diff --git a/src/hooks/useActiveItemEffect.ts b/src/hooks/useActiveItemEffect.ts
new file mode 100644
index 0000000..572bb4a
--- /dev/null
+++ b/src/hooks/useActiveItemEffect.ts
@@ -0,0 +1,42 @@
+import { useInterpolateInsideCarousel } from './useInterpolateInsideCarousel'
+import { useState } from 'react'
+import { runOnJS, useAnimatedReaction } from 'react-native-reanimated'
+
+export const useIsActiveItem = () => {
+  const progress = useInterpolateInsideCarousel({
+    valueBefore: 0,
+    thisValue: 1,
+    valueAfter: 0,
+  })
+  const [isActive, setIsActive] = useState(false)
+  useAnimatedReaction(
+    () => progress.value,
+    (value) => {
+      if (value === 1) {
+        runOnJS(setIsActive)(true)
+      } else {
+        runOnJS(setIsActive)(false)
+      }
+    },
+    [],
+  )
+  return isActive
+}
+
+export const useActiveItemEffect = (effectFunc: () => () => void | undefined, deps: any[] = []) => {
+  const progress = useInterpolateInsideCarousel({
+    valueBefore: 0,
+    thisValue: 1,
+    valueAfter: 0,
+  })
+
+  useAnimatedReaction(
+    () => progress.value,
+    (value) => {
+      if (value === 1) {
+        runOnJS(effectFunc)()
+      }
+    },
+    deps,
+  )
+}
diff --git a/src/hooks/useInterpolateInsideCarousel.ts b/src/hooks/useInterpolateInsideCarousel.ts
new file mode 100644
index 0000000..5fe154b
--- /dev/null
+++ b/src/hooks/useInterpolateInsideCarousel.ts
@@ -0,0 +1,16 @@
+import { useAutoCarouselSlideIndex, useCarouselContext } from '../context'
+import { interpolateInsideCarousel } from '../utils'
+import { useDerivedValue } from 'react-native-reanimated'
+
+export const useInterpolateInsideCarousel = (values: {
+  valueBefore: number
+  thisValue: number
+  valueAfter: number
+  offset?: number
+}) => {
+  const { scrollValue } = useCarouselContext()
+  const { index, total } = useAutoCarouselSlideIndex()
+  return useDerivedValue(() => {
+    return interpolateInsideCarousel(scrollValue.value, index, total, values)
+  }, [scrollValue, values])
+}
diff --git a/src/index.ts b/src/index.ts
index 1710fbf..dd9fb23 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,3 +1,4 @@
 export * from './components'
 export * from './context'
 export * from './utils'
+export * from './hooks'

From b9c13bae6c461d8c5be5d5f9fa219e207eef8f24 Mon Sep 17 00:00:00 2001
From: Petr Konecny <petr.konecny@strv.com>
Date: Thu, 27 Nov 2025 01:01:01 +0100
Subject: [PATCH 4/4] chore: rename slide to item

---
 README.md                                                   | 2 +-
 src/components/HeroCarousel/index.tsx                       | 4 ++--
 src/components/HeroCarouselSlide/index.tsx                  | 6 +++---
 .../{SlideAnimatedView => ItemAnimatedView}/index.tsx       | 6 +++---
 src/context/{SlideContext => ItemContext}/index.tsx         | 4 ++--
 src/context/index.tsx                                       | 2 +-
 6 files changed, 12 insertions(+), 12 deletions(-)
 rename src/components/{SlideAnimatedView => ItemAnimatedView}/index.tsx (95%)
 rename src/context/{SlideContext => ItemContext}/index.tsx (82%)

diff --git a/README.md b/README.md
index 3a5155f..5c027ac 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ npm install @strv/react-native-hero-carousel
 # or
 yarn add @strv/react-native-hero-carousel
 # or
-yarn add @strv/react-native-hero-carousel
+pnpm add @strv/react-native-hero-carousel
 ```
 
 ### Peer Dependencies
diff --git a/src/components/HeroCarousel/index.tsx b/src/components/HeroCarousel/index.tsx
index d4cc003..8665fca 100644
--- a/src/components/HeroCarousel/index.tsx
+++ b/src/components/HeroCarousel/index.tsx
@@ -6,7 +6,7 @@ import { HeroCarouselAdapter } from '../AnimatedPagedView/Adapter'
 import { useAutoScroll } from '../../hooks/useAutoScroll'
 import { useInfiniteScroll } from '../../hooks/useInfiniteScroll'
 import { DEFAULT_INTERVAL } from './index.preset'
-import { SlideAnimatedView } from '../SlideAnimatedView'
+import { ItemAnimatedView } from '../ItemAnimatedView'
 
 export type HeroCarouselProps = {
   children: React.ReactNode[]
@@ -74,7 +74,7 @@ const HeroCarousel = ({ children }: HeroCarouselProps) => {
   )
 }
 
-HeroCarousel.AnimatedView = SlideAnimatedView
+HeroCarousel.AnimatedView = ItemAnimatedView
 HeroCarousel.Provider = CarouselContextProvider
 HeroCarousel.Item = HeroCarouselSlide
 
diff --git a/src/components/HeroCarouselSlide/index.tsx b/src/components/HeroCarouselSlide/index.tsx
index d756668..0a6d09c 100644
--- a/src/components/HeroCarouselSlide/index.tsx
+++ b/src/components/HeroCarouselSlide/index.tsx
@@ -1,5 +1,5 @@
 import { View } from 'react-native'
-import { HeroCarouselSlideContext } from '../../context/SlideContext'
+import { ItemContext } from '../../context/ItemContext'
 import { useAutoScroll } from '../../hooks/useAutoScroll'
 import { useMemo } from 'react'
 import { useManualScroll } from '../../hooks/useManualScroll'
@@ -21,14 +21,14 @@ export const HeroCarouselSlide = ({
 }) => {
   return (
     <View style={{ flex: 1, width, minWidth: width }}>
-      <HeroCarouselSlideContext.Provider
+      <ItemContext.Provider
         value={useMemo(
           () => ({ index, total, runAutoScroll, goToPage }),
           [index, total, runAutoScroll, goToPage],
         )}
       >
         {children}
-      </HeroCarouselSlideContext.Provider>
+      </ItemContext.Provider>
     </View>
   )
 }
diff --git a/src/components/SlideAnimatedView/index.tsx b/src/components/ItemAnimatedView/index.tsx
similarity index 95%
rename from src/components/SlideAnimatedView/index.tsx
rename to src/components/ItemAnimatedView/index.tsx
index fadaf41..fae86d6 100644
--- a/src/components/SlideAnimatedView/index.tsx
+++ b/src/components/ItemAnimatedView/index.tsx
@@ -8,7 +8,7 @@ import { useState } from 'react'
 import { ViewProps } from 'react-native'
 import { useInterpolateInsideCarousel } from '../../hooks/useInterpolateInsideCarousel'
 
-type SlideAnimatedViewProps = {
+type ItemAnimatedViewProps = {
   children: React.ReactNode
   entering?: AnimatedProps<ViewProps>['entering']
   exiting?: AnimatedProps<ViewProps>['exiting']
@@ -19,7 +19,7 @@ type SlideAnimatedViewProps = {
   keepVisibleAfterExiting?: boolean
 }
 
-export const SlideAnimatedView = ({
+export const ItemAnimatedView = ({
   children,
   entering,
   exiting,
@@ -28,7 +28,7 @@ export const SlideAnimatedView = ({
   exitingThreshold = 0.01,
   keepVisibleAfterExiting = false,
   style,
-}: SlideAnimatedViewProps) => {
+}: ItemAnimatedViewProps) => {
   const progress = useInterpolateInsideCarousel({
     valueBefore: 0,
     thisValue: 1,
diff --git a/src/context/SlideContext/index.tsx b/src/context/ItemContext/index.tsx
similarity index 82%
rename from src/context/SlideContext/index.tsx
rename to src/context/ItemContext/index.tsx
index d2f22f6..623865c 100644
--- a/src/context/SlideContext/index.tsx
+++ b/src/context/ItemContext/index.tsx
@@ -2,7 +2,7 @@ import { createContext, useContext } from 'react'
 import { useAutoScroll } from '../../hooks/useAutoScroll'
 import { useManualScroll } from '../../hooks/useManualScroll'
 
-export const HeroCarouselSlideContext = createContext<{
+export const ItemContext = createContext<{
   index: number
   total: number
   runAutoScroll: ReturnType<typeof useAutoScroll>['runAutoScroll']
@@ -10,7 +10,7 @@ export const HeroCarouselSlideContext = createContext<{
 } | null>(null)
 
 export const useAutoCarouselSlideIndex = () => {
-  const context = useContext(HeroCarouselSlideContext)
+  const context = useContext(ItemContext)
   if (!context) {
     throw new Error('useAutoCarouselSlideIndex must be used within a AutoCarouselSlide')
   }
diff --git a/src/context/index.tsx b/src/context/index.tsx
index 5b47641..1d12d3c 100644
--- a/src/context/index.tsx
+++ b/src/context/index.tsx
@@ -1,2 +1,2 @@
 export { useCarouselContext } from './CarouselContext'
-export * from './SlideContext'
+export * from './ItemContext'