react-native-header-motion 0.1.1 → 0.3.0

package/README.md

@@ -407,6 +407,15 @@ Supports `scrollId?: string` for multi-scroll scenarios.
 
 Render-prop API for custom scrollables (pager pages, 3rd party lists, etc.).
 
+If you use `HeaderMotion.ScrollManager` directly for custom integrations, pass refresh-related props to `ScrollManager` (instead of your inner scrollable):
+
+- `refreshControl`
+- `refreshing`
+- `onRefresh`
+- optional `progressViewOffset` if you want to force your offset.
+
+This is required, as the positioning of scrollables is affecting Refresh Control and has to be coupled with the header heights.
+
 ```tsx
 <HeaderMotion.ScrollManager scrollId="A">
   {(
@@ -424,6 +433,31 @@ Render-prop API for custom scrollables (pager pages, 3rd party lists, etc.).
 </HeaderMotion.ScrollManager>
 ```
 
+Refresh example with explicit props on `ScrollManager`:
+
+```tsx
+<HeaderMotion.ScrollManager
+  scrollId="A"
+  refreshing={refreshing}
+  onRefresh={onRefresh}
+>
+  {(
+    { onScroll, refreshControl: managedRefreshControl, ...scrollableProps },
+    { originalHeaderHeight, minHeightContentContainerStyle }
+  ) => (
+    <Animated.ScrollView
+      {...scrollableProps}
+      onScroll={onScroll}
+      refreshControl={managedRefreshControl}
+      contentContainerStyle={[
+        minHeightContentContainerStyle,
+        { paddingTop: originalHeaderHeight },
+      ]}
+    />
+  )}
+</HeaderMotion.ScrollManager>
+```
+
 ### Hooks
 
 #### `useMotionProgress()`
@@ -469,6 +503,30 @@ Reanimated-powered, absolutely positioned header base.
 - `WithCollapsibleHeaderProps` – convenience type for headers using motion progress props.
 - `WithCollapsiblePagedHeaderProps` – like above, plus `activeTab` and `onTabChange`.
 
+## Additional notes
+
+### Refresh Control (v.0.3.0+)
+
+Refresh control support was improved in `v0.3.0+`.
+
+- If you use `HeaderMotion.ScrollView` or `HeaderMotion.FlatList`, your refresh-control usage stays the same as in React Native.
+- If you use `HeaderMotion.ScrollManager` directly for custom integrations, pass refresh-related props to `ScrollManager`:
+  - `refreshControl`
+  - `refreshing`
+  - `onRefresh`
+  - optional `progressViewOffset`
+
+This is important because scrollable positioning affects refresh-control behavior and needs to stay coupled with measured header height.
+
+#### Platform support note:
+
+- Support for Refresh Control is currently partial.
+- Android works well with the current implementation.
+- iOS behavior is still not fully deterministic.
+- `progressViewOffset` does not seem to be reliable on iOS in all scenarios.
+- Other iOS approaches tried so far introduced different issues.
+- Additional iOS support improvements are planned for future releases.
+
 ## Contributing
 
 - Development workflow: see [CONTRIBUTING.md](CONTRIBUTING.md)

package/lib/module/components/FlatList.js

@@ -23,13 +23,20 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 export function HeaderMotionFlatList({
   scrollId,
+  animatedRef,
   contentContainerStyle,
   ...props
 }) {
   return /*#__PURE__*/_jsx(HeaderMotionScrollManager, {
     scrollId: scrollId,
+    animatedRef: animatedRef,
+    refreshControl: props.refreshControl,
+    refreshing: props.refreshing,
+    onRefresh: props.onRefresh,
+    progressViewOffset: props.progressViewOffset,
     children: ({
       onScroll,
+      refreshControl: managedRefreshControl,
       ...scrollViewProps
     }, {
       originalHeaderHeight,
@@ -38,8 +45,11 @@ export function HeaderMotionFlatList({
       ...scrollViewProps,
       ...props,
       onScroll: onScroll,
-      renderScrollComponent: propsz => /*#__PURE__*/_jsx(AnimatedScrollContainer, {
-        ...propsz,
+      ...(managedRefreshControl && {
+        refreshControl: managedRefreshControl
+      }),
+      renderScrollComponent: scrollComponentProps => /*#__PURE__*/_jsx(AnimatedScrollContainer, {
+        ...scrollComponentProps,
         contentContainerStyle: [minHeightContentContainerStyle, {
           paddingTop: originalHeaderHeight
         }, contentContainerStyle]

package/lib/module/components/FlatList.js.map

@@ -1 +1 @@
-{"version":3,"names":["forwardRef","Animated","HeaderMotionScrollManager","jsx","_jsx","HeaderMotionFlatList","scrollId","contentContainerStyle","props","children","onScroll","scrollViewProps","originalHeaderHeight","minHeightContentContainerStyle","FlatList","renderScrollComponent","propsz","AnimatedScrollContainer","paddingTop","rest","ref","ScrollView","View","style"],"sourceRoot":"../../../src","sources":["components/FlatList.tsx"],"mappings":";;AAAA,SAASA,UAAU,QAAgD,OAAO;AAC1E,OAAOC,QAAQ,MAAM,yBAAyB;AAC9C,SAASC,yBAAyB,QAAQ,oBAAiB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAgB5D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,oBAAoBA,CAAU;EAC5CC,QAAQ;EACRC,qBAAqB;EACrB,GAAGC;AACyB,CAAC,EAAE;EAC/B,oBACEJ,IAAA,CAACF,yBAAyB;IAACI,QAAQ,EAAEA,QAAS;IAAAG,QAAA,EAC3CA,CACC;MAAEC,QAAQ;MAAE,GAAGC;IAAgB,CAAC,EAChC;MAAEC,oBAAoB;MAAEC;IAA+B,CAAC,kBAExDT,IAAA,CAACH,QAAQ,CAACa,QAAQ;MAAA,GACZH,eAAe;MAAA,GACfH,KAAK;MACTE,QAAQ,EAAEA,QAAS;MACnBK,qBAAqB,EAAGC,MAAM,iBAC5BZ,IAAA,CAACa,uBAAuB;QAAA,GAClBD,MAAM;QACVT,qBAAqB,EAAE,CACrBM,8BAA8B,EAC9B;UAAEK,UAAU,EAAEN;QAAqB,CAAC,EACpCL,qBAAqB;MACrB,CACH;IACD,CACH;EACF,CACwB,CAAC;AAEhC;AAEA,MAAMU,uBAAuB,gBAAGjB,UAAU,CAGxC,CAAC;EAAES,QAAQ;EAAEF,qBAAqB;EAAE,GAAGY;AAAK,CAAC,EAAEC,GAAG,KAAK;EACvD,oBACEhB,IAAA,CAACH,QAAQ,CAACoB,UAAU;IAAA,GAAKF,IAAI;IAAEC,GAAG,EAAEA,GAAI;IAAAX,QAAA,eACtCL,IAAA,CAACH,QAAQ,CAACqB,IAAI;MAACC,KAAK,EAAEhB,qBAAsB;MAAAE,QAAA,EAAEA;IAAQ,CAAgB;EAAC,CACpD,CAAC;AAE1B,CAAC,CAAC","ignoreList":[]}
+{"version":3,"names":["forwardRef","Animated","HeaderMotionScrollManager","jsx","_jsx","HeaderMotionFlatList","scrollId","animatedRef","contentContainerStyle","props","refreshControl","refreshing","onRefresh","progressViewOffset","children","onScroll","managedRefreshControl","scrollViewProps","originalHeaderHeight","minHeightContentContainerStyle","FlatList","renderScrollComponent","scrollComponentProps","AnimatedScrollContainer","paddingTop","rest","ref","ScrollView","View","style"],"sourceRoot":"../../../src","sources":["components/FlatList.tsx"],"mappings":";;AAAA,SAASA,UAAU,QAAgD,OAAO;AAC1E,OAAOC,QAAQ,MAA4B,yBAAyB;AACpE,SAASC,yBAAyB,QAAQ,oBAAiB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAmB5D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,oBAAoBA,CAAU;EAC5CC,QAAQ;EACRC,WAAW;EACXC,qBAAqB;EACrB,GAAGC;AACyB,CAAC,EAAE;EAC/B,oBACEL,IAAA,CAACF,yBAAyB;IACxBI,QAAQ,EAAEA,QAAS;IACnBC,WAAW,EAAEA,WAAY;IACzBG,cAAc,EAAED,KAAK,CAACC,cAAe;IACrCC,UAAU,EAAEF,KAAK,CAACE,UAAW;IAC7BC,SAAS,EAAEH,KAAK,CAACG,SAAU;IAC3BC,kBAAkB,EAAEJ,KAAK,CAACI,kBAAmB;IAAAC,QAAA,EAE5CA,CACC;MAAEC,QAAQ;MAAEL,cAAc,EAAEM,qBAAqB;MAAE,GAAGC;IAAgB,CAAC,EACvE;MAAEC,oBAAoB;MAAEC;IAA+B,CAAC,kBAExDf,IAAA,CAACH,QAAQ,CAACmB,QAAQ;MAAA,GACZH,eAAe;MAAA,GACfR,KAAK;MACTM,QAAQ,EAAEA,QAAS;MAAA,IACdC,qBAAqB,IAAI;QAC5BN,cAAc,EAAEM;MAClB,CAAC;MACDK,qBAAqB,EAAGC,oBAAoB,iBAC1ClB,IAAA,CAACmB,uBAAuB;QAAA,GAClBD,oBAAoB;QACxBd,qBAAqB,EAAE,CACrBW,8BAA8B,EAC9B;UAAEK,UAAU,EAAEN;QAAqB,CAAC,EACpCV,qBAAqB;MACrB,CACH;IACD,CACH;EACF,CACwB,CAAC;AAEhC;AAEA,MAAMe,uBAAuB,gBAAGvB,UAAU,CAGxC,CAAC;EAAEc,QAAQ;EAAEN,qBAAqB;EAAE,GAAGiB;AAAK,CAAC,EAAEC,GAAG,KAAK;EACvD,oBACEtB,IAAA,CAACH,QAAQ,CAAC0B,UAAU;IAAA,GAAKF,IAAI;IAAEC,GAAG,EAAEA,GAAI;IAAAZ,QAAA,eACtCV,IAAA,CAACH,QAAQ,CAAC2B,IAAI;MAACC,KAAK,EAAErB,qBAAsB;MAAAM,QAAA,EAAEA;IAAQ,CAAgB;EAAC,CACpD,CAAC;AAE1B,CAAC,CAAC","ignoreList":[]}

package/lib/module/components/ScrollManager.js

@@ -25,7 +25,12 @@ import { useScrollManager } from "../hooks/index.js";
  */
 export function HeaderMotionScrollManager({
   children,
-  scrollId
+  scrollId,
+  animatedRef,
+  refreshControl,
+  refreshing,
+  onRefresh,
+  progressViewOffset
 }) {
   if (typeof children !== 'function') {
     throw new Error('HeaderMotion.ScrollManager only accepts render function as the only child.');
@@ -33,7 +38,13 @@ export function HeaderMotionScrollManager({
   const {
     scrollableProps,
     headerMotionContext
-  } = useScrollManager(scrollId);
+  } = useScrollManager(scrollId, {
+    animatedRef,
+    refreshControl,
+    refreshing,
+    onRefresh,
+    progressViewOffset
+  });
   return children(scrollableProps, headerMotionContext);
 }
 //# sourceMappingURL=ScrollManager.js.map

package/lib/module/components/ScrollManager.js.map

@@ -1 +1 @@
-{"version":3,"names":["useScrollManager","HeaderMotionScrollManager","children","scrollId","Error","scrollableProps","headerMotionContext"],"sourceRoot":"../../../src","sources":["components/ScrollManager.tsx"],"mappings":";;AAAA,SAASA,gBAAgB,QAAQ,mBAAU;AAsB3C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,yBAAyBA,CAAC;EACxCC,QAAQ;EACRC;AAC8B,CAAC,EAAE;EACjC,IAAI,OAAOD,QAAQ,KAAK,UAAU,EAAE;IAClC,MAAM,IAAIE,KAAK,CACb,4EACF,CAAC;EACH;EAEA,MAAM;IAAEC,eAAe;IAAEC;EAAoB,CAAC,GAAGN,gBAAgB,CAACG,QAAQ,CAAC;EAE3E,OAAOD,QAAQ,CAACG,eAAe,EAAEC,mBAAmB,CAAC;AACvD","ignoreList":[]}
+{"version":3,"names":["useScrollManager","HeaderMotionScrollManager","children","scrollId","animatedRef","refreshControl","refreshing","onRefresh","progressViewOffset","Error","scrollableProps","headerMotionContext"],"sourceRoot":"../../../src","sources":["components/ScrollManager.tsx"],"mappings":";;AAAA,SAASA,gBAAgB,QAAQ,mBAAU;AAmC3C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,yBAAyBA,CAAC;EACxCC,QAAQ;EACRC,QAAQ;EACRC,WAAW;EACXC,cAAc;EACdC,UAAU;EACVC,SAAS;EACTC;AAC8B,CAAC,EAAE;EACjC,IAAI,OAAON,QAAQ,KAAK,UAAU,EAAE;IAClC,MAAM,IAAIO,KAAK,CACb,4EACF,CAAC;EACH;EAEA,MAAM;IAAEC,eAAe;IAAEC;EAAoB,CAAC,GAAGX,gBAAgB,CAACG,QAAQ,EAAE;IAC1EC,WAAW;IACXC,cAAc;IACdC,UAAU;IACVC,SAAS;IACTC;EACF,CAAC,CAAC;EAEF,OAAON,QAAQ,CAACQ,eAAe,EAAEC,mBAAmB,CAAC;AACvD","ignoreList":[]}

package/lib/module/components/ScrollView.js

@@ -19,14 +19,19 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 export function HeaderMotionScrollView({
   scrollId,
+  animatedRef,
   children,
   contentContainerStyle,
+  refreshControl,
   ...props
 }) {
   return /*#__PURE__*/_jsx(HeaderMotionScrollManager, {
     scrollId: scrollId,
+    animatedRef: animatedRef,
+    refreshControl: refreshControl,
     children: ({
       onScroll,
+      refreshControl: managedRefreshControl,
       ...scrollViewProps
     }, {
       originalHeaderHeight,
@@ -35,6 +40,9 @@ export function HeaderMotionScrollView({
       ...scrollViewProps,
       ...props,
       onScroll: onScroll,
+      ...(managedRefreshControl && {
+        refreshControl: managedRefreshControl
+      }),
       children: /*#__PURE__*/_jsx(Animated.View, {
         style: [minHeightContentContainerStyle, {
           paddingTop: originalHeaderHeight

package/lib/module/components/ScrollView.js.map

@@ -1 +1 @@
-{"version":3,"names":["Animated","HeaderMotionScrollManager","jsx","_jsx","HeaderMotionScrollView","scrollId","children","contentContainerStyle","props","onScroll","scrollViewProps","originalHeaderHeight","minHeightContentContainerStyle","ScrollView","View","style","paddingTop"],"sourceRoot":"../../../src","sources":["components/ScrollView.tsx"],"mappings":";;AAAA,OAAOA,QAAQ,MAER,yBAAyB;AAChC,SAASC,yBAAyB,QAAQ,oBAAiB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAU5D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,sBAAsBA,CAAC;EACrCC,QAAQ;EACRC,QAAQ;EACRC,qBAAqB;EACrB,GAAGC;AACwB,CAAC,EAAE;EAC9B,oBACEL,IAAA,CAACF,yBAAyB;IAACI,QAAQ,EAAEA,QAAS;IAAAC,QAAA,EAC3CA,CACC;MAAEG,QAAQ;MAAE,GAAGC;IAAgB,CAAC,EAChC;MAAEC,oBAAoB;MAAEC;IAA+B,CAAC,kBAExDT,IAAA,CAACH,QAAQ,CAACa,UAAU;MAAA,GACdH,eAAe;MAAA,GACfF,KAAK;MACTC,QAAQ,EAAEA,QAAS;MAAAH,QAAA,eAEnBH,IAAA,CAACH,QAAQ,CAACc,IAAI;QACZC,KAAK,EAAE,CACLH,8BAA8B,EAC9B;UAAEI,UAAU,EAAEL;QAAqB,CAAC,EACpCJ,qBAAqB,CACrB;QAAAD,QAAA,EAEDA;MAAQ,CACI;IAAC,CACG;EACtB,CACwB,CAAC;AAEhC","ignoreList":[]}
+{"version":3,"names":["Animated","HeaderMotionScrollManager","jsx","_jsx","HeaderMotionScrollView","scrollId","animatedRef","children","contentContainerStyle","refreshControl","props","onScroll","managedRefreshControl","scrollViewProps","originalHeaderHeight","minHeightContentContainerStyle","ScrollView","View","style","paddingTop"],"sourceRoot":"../../../src","sources":["components/ScrollView.tsx"],"mappings":";;AAAA,OAAOA,QAAQ,MAGR,yBAAyB;AAChC,SAASC,yBAAyB,QAAQ,oBAAiB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAe5D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,sBAAsBA,CAAC;EACrCC,QAAQ;EACRC,WAAW;EACXC,QAAQ;EACRC,qBAAqB;EACrBC,cAAc;EACd,GAAGC;AACwB,CAAC,EAAE;EAC9B,oBACEP,IAAA,CAACF,yBAAyB;IACxBI,QAAQ,EAAEA,QAAS;IACnBC,WAAW,EAAEA,WAAY;IACzBG,cAAc,EAAEA,cAAe;IAAAF,QAAA,EAE9BA,CACC;MAAEI,QAAQ;MAAEF,cAAc,EAAEG,qBAAqB;MAAE,GAAGC;IAAgB,CAAC,EACvE;MAAEC,oBAAoB;MAAEC;IAA+B,CAAC,kBAExDZ,IAAA,CAACH,QAAQ,CAACgB,UAAU;MAAA,GACdH,eAAe;MAAA,GACfH,KAAK;MACTC,QAAQ,EAAEA,QAAS;MAAA,IACdC,qBAAqB,IAAI;QAC5BH,cAAc,EAAEG;MAClB,CAAC;MAAAL,QAAA,eAEDJ,IAAA,CAACH,QAAQ,CAACiB,IAAI;QACZC,KAAK,EAAE,CACLH,8BAA8B,EAC9B;UAAEI,UAAU,EAAEL;QAAqB,CAAC,EACpCN,qBAAqB,CACrB;QAAAD,QAAA,EAEDA;MAAQ,CACI;IAAC,CACG;EACtB,CACwB,CAAC;AAEhC","ignoreList":[]}

package/lib/module/hooks/refreshControl.js

@@ -0,0 +1,31 @@
+"use strict";
+
+import { cloneElement, createElement, isValidElement } from 'react';
+import { RefreshControl } from 'react-native';
+function injectProgressViewOffset(refreshControl, progressViewOffset) {
+  if (refreshControl.props.progressViewOffset !== undefined) {
+    return refreshControl;
+  }
+  return /*#__PURE__*/cloneElement(refreshControl, {
+    progressViewOffset: progressViewOffset
+  });
+}
+export function resolveRefreshControl({
+  refreshControl,
+  refreshing,
+  onRefresh,
+  progressViewOffset
+}) {
+  if (refreshControl) {
+    return /*#__PURE__*/isValidElement(refreshControl) ? injectProgressViewOffset(refreshControl, progressViewOffset) : undefined;
+  }
+  if (!onRefresh) {
+    return undefined;
+  }
+  return /*#__PURE__*/createElement(RefreshControl, {
+    refreshing: refreshing ?? false,
+    onRefresh: onRefresh,
+    progressViewOffset: progressViewOffset
+  });
+}
+//# sourceMappingURL=refreshControl.js.map

package/lib/module/hooks/refreshControl.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["cloneElement","createElement","isValidElement","RefreshControl","injectProgressViewOffset","refreshControl","progressViewOffset","props","undefined","resolveRefreshControl","refreshing","onRefresh"],"sourceRoot":"../../../src","sources":["hooks/refreshControl.ts"],"mappings":";;AAAA,SACEA,YAAY,EACZC,aAAa,EACbC,cAAc,QAET,OAAO;AACd,SAASC,cAAc,QAAkC,cAAc;AAYvE,SAASC,wBAAwBA,CAC/BC,cAAiD,EACjDC,kBAAuC,EACvC;EACA,IAAID,cAAc,CAACE,KAAK,CAACD,kBAAkB,KAAKE,SAAS,EAAE;IACzD,OAAOH,cAAc;EACvB;EAEA,oBAAOL,YAAY,CAACK,cAAc,EAAE;IAClCC,kBAAkB,EAAEA;EACtB,CAAC,CAAC;AACJ;AAEA,OAAO,SAASG,qBAAqBA,CAAC;EACpCJ,cAAc;EACdK,UAAU;EACVC,SAAS;EACTL;AAC4B,CAAC,EAEjB;EACZ,IAAID,cAAc,EAAE;IAClB,OAAO,aAAAH,cAAc,CAAsBG,cAAc,CAAC,GACtDD,wBAAwB,CAACC,cAAc,EAAEC,kBAAkB,CAAC,GAC5DE,SAAS;EACf;EAEA,IAAI,CAACG,SAAS,EAAE;IACd,OAAOH,SAAS;EAClB;EAEA,oBAAOP,aAAa,CAACE,cAAc,EAAE;IACnCO,UAAU,EAAGA,UAAU,IAAgB,KAAK;IAC5CC,SAAS,EAAEA,SAAuB;IAClCL,kBAAkB,EAAEA;EACtB,CAAC,CAAC;AACJ","ignoreList":[]}

package/lib/module/hooks/useScrollManager.js

@@ -5,6 +5,7 @@ import { measure, scrollTo, useAnimatedReaction, useAnimatedRef, useAnimatedScro
 import { RuntimeKind, scheduleOnUI } from 'react-native-worklets';
 import { HeaderMotionContext } from "../context.js";
 import { DEFAULT_SCROLL_ID, getInitialScrollValue } from "../utils/index.js";
+import { resolveRefreshControl } from "./refreshControl.js";
 
 /**
  * Hook that manages scroll tracking and synchronization for header animations.
@@ -19,6 +20,9 @@ import { DEFAULT_SCROLL_ID, getInitialScrollValue } from "../utils/index.js";
  *
  * @param scrollId - Optional unique identifier for the related scrollable.
  *                   Use when you have multiple scrollables (e.g., in tabs).
+ * @param options - Optional configuration object.
+ * @param options.animatedRef - Optional animated ref to use instead of creating one internally.
+ *                              Useful when you need access to the scroll view ref from outside.
  * @returns Configuration object containing:
  * - `scrollableProps`: Props to apply to scrollable component (onScroll, scrollEventThrottle, ref)
  * - `headerMotionContext`: Header context values (originalHeaderHeight, minHeightContentContainerStyle)
@@ -40,7 +44,8 @@ import { DEFAULT_SCROLL_ID, getInitialScrollValue } from "../utils/index.js";
  * }
  * ```
  */
-export function useScrollManager(scrollId) {
+
+export function useScrollManager(scrollId, options) {
   const ctxValue = useContext(HeaderMotionContext);
   if (!ctxValue) {
     throw new Error('useScrollManager must be used within a HeaderMotion component');
@@ -53,8 +58,12 @@ export function useScrollManager(scrollId) {
     originalHeaderHeight
   } = ctxValue;
   const id = scrollId ?? DEFAULT_SCROLL_ID;
-  const animatedRef = useAnimatedRef(); // TODO: better typing
-
+  const localRef = useAnimatedRef(); // TODO: better typing
+  const animatedRef = options?.animatedRef ?? localRef;
+  const refreshControl = options?.refreshControl;
+  const refreshing = options?.refreshing;
+  const onRefresh = options?.onRefresh;
+  const progressViewOffset = options?.progressViewOffset ?? originalHeaderHeight;
   useEffect(() => {
     return () => {
       scheduleOnUI(scrollIdToDelete => {
@@ -133,10 +142,17 @@ export function useScrollManager(scrollId) {
       minHeight: measurement.height + progressThreshold
     };
   });
+  const resolvedRefreshControl = resolveRefreshControl({
+    refreshControl,
+    refreshing,
+    onRefresh,
+    progressViewOffset
+  });
   const scrollableProps = {
     onScroll,
     scrollEventThrottle: 16,
-    ref: animatedRef
+    ref: animatedRef,
+    refreshControl: resolvedRefreshControl
   };
   const headerMotionContext = {
     originalHeaderHeight,

package/lib/module/hooks/useScrollManager.js.map

@@ -1 +1 @@
-{"version":3,"names":["useContext","useCallback","useEffect","measure","scrollTo","useAnimatedReaction","useAnimatedRef","useAnimatedScrollHandler","useAnimatedStyle","RuntimeKind","scheduleOnUI","HeaderMotionContext","DEFAULT_SCROLL_ID","getInitialScrollValue","useScrollManager","scrollId","ctxValue","Error","scrollValues","progress","activeScrollId","progressThreshold","originalHeaderHeight","id","animatedRef","scrollIdToDelete","modify","value","newProgress","oldProgress","currentActiveScrollId","get","newCur","scrollValue","progressDiff","current","newMin","min","scrollHandler","e","activeScrollIdValue","oldCurrent","oldMin","isCollapsed","newCurrent","contentOffset","y","Math","max","onScroll","minHeightContentContainerStyle","globalThis","__RUNTIME_KIND","ReactNative","measurement","minHeight","height","scrollableProps","scrollEventThrottle","ref","headerMotionContext"],"sourceRoot":"../../../src","sources":["hooks/useScrollManager.ts"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["useContext","useCallback","useEffect","measure","scrollTo","useAnimatedReaction","useAnimatedRef","useAnimatedScrollHandler","useAnimatedStyle","RuntimeKind","scheduleOnUI","HeaderMotionContext","DEFAULT_SCROLL_ID","getInitialScrollValue","resolveRefreshControl","useScrollManager","scrollId","options","ctxValue","Error","scrollValues","progress","activeScrollId","progressThreshold","originalHeaderHeight","id","localRef","animatedRef","refreshControl","refreshing","onRefresh","progressViewOffset","scrollIdToDelete","modify","value","newProgress","oldProgress","currentActiveScrollId","get","newCur","scrollValue","progressDiff","current","newMin","min","scrollHandler","e","activeScrollIdValue","oldCurrent","oldMin","isCollapsed","newCurrent","contentOffset","y","Math","max","onScroll","minHeightContentContainerStyle","globalThis","__RUNTIME_KIND","ReactNative","measurement","minHeight","height","resolvedRefreshControl","scrollableProps","scrollEventThrottle","ref","headerMotionContext"],"sourceRoot":"../../../src","sources":["hooks/useScrollManager.ts"],"mappings":"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","ignoreList":[]}

package/lib/typescript/src/components/FlatList.d.ts

@@ -1,12 +1,16 @@
 import { type ComponentProps } from 'react';
-import Animated from 'react-native-reanimated';
-type AnimatedFlatListProps<T = any> = ComponentProps<typeof Animated.FlatList<T>>;
-export type HeaderMotionFlatListProps<T = any> = AnimatedFlatListProps<T> & {
+import Animated, { type AnimatedRef } from 'react-native-reanimated';
+export type HeaderMotionFlatListProps<T = any> = ComponentProps<typeof Animated.FlatList<T>> & {
     /**
      * Optional unique identifier for this scroll view.
      * Use this when you have multiple scroll views (e.g. in tabs) to track them separately.
      */
     scrollId?: string;
+    /**
+     * Optional animated ref to use for the flat list.
+     * When provided, the scroll manager will use this ref instead of creating its own.
+     */
+    animatedRef?: AnimatedRef<any>;
 };
 /**
  * Animated FlatList component that integrates with HeaderMotion.
@@ -25,6 +29,5 @@ export type HeaderMotionFlatListProps<T = any> = AnimatedFlatListProps<T> & {
  * </HeaderMotion>
  * ```
  */
-export declare function HeaderMotionFlatList<T = any>({ scrollId, contentContainerStyle, ...props }: HeaderMotionFlatListProps<T>): import("react/jsx-runtime").JSX.Element;
-export {};
+export declare function HeaderMotionFlatList<T = any>({ scrollId, animatedRef, contentContainerStyle, ...props }: HeaderMotionFlatListProps<T>): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=FlatList.d.ts.map

package/lib/typescript/src/components/FlatList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FlatList.d.ts","sourceRoot":"","sources":["../../../../src/components/FlatList.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAqB,MAAM,OAAO,CAAC;AAC3E,OAAO,QAAQ,MAAM,yBAAyB,CAAC;AAK/C,KAAK,qBAAqB,CAAC,CAAC,GAAG,GAAG,IAAI,cAAc,CAClD,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAC5B,CAAC;AAEF,MAAM,MAAM,yBAAyB,CAAC,CAAC,GAAG,GAAG,IAAI,qBAAqB,CAAC,CAAC,CAAC,GAAG;IAC1E;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,GAAG,EAAE,EAC5C,QAAQ,EACR,qBAAqB,EACrB,GAAG,KAAK,EACT,EAAE,yBAAyB,CAAC,CAAC,CAAC,2CAyB9B"}
+{"version":3,"file":"FlatList.d.ts","sourceRoot":"","sources":["../../../../src/components/FlatList.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAqB,MAAM,OAAO,CAAC;AAC3E,OAAO,QAAQ,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAKrE,MAAM,MAAM,yBAAyB,CAAC,CAAC,GAAG,GAAG,IAAI,cAAc,CAC7D,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAC5B,GAAG;IACF;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,GAAG,EAAE,EAC5C,QAAQ,EACR,WAAW,EACX,qBAAqB,EACrB,GAAG,KAAK,EACT,EAAE,yBAAyB,CAAC,CAAC,CAAC,2CAmC9B"}

package/lib/typescript/src/components/ScrollManager.d.ts

@@ -1,12 +1,24 @@
 import type { ScrollManagerConfig } from '../types';
+import type { ResolveRefreshControlOptions } from '../hooks/refreshControl';
 import type { ReactNode } from 'react';
+import type { AnimatedRef } from 'react-native-reanimated';
 type ScrollManagerRenderChildren = (scrollableProps: ScrollManagerConfig['scrollableProps'], options: ScrollManagerConfig['headerMotionContext']) => ReactNode;
-export interface HeaderMotionScrollManagerProps {
+export interface HeaderMotionScrollManagerProps extends Omit<ResolveRefreshControlOptions, 'progressViewOffset'> {
     /**
      * Optional unique identifier for this scroll view.
      * Use this when you have multiple scroll views (e.g., in tabs) to track them separately.
      */
     scrollId?: string;
+    /**
+     * Optional animated ref to use for the scroll view.
+     * When provided, the scroll manager will use this ref instead of creating its own.
+     */
+    animatedRef?: AnimatedRef<any>;
+    /**
+     * Optional refresh progress offset override.
+     * When provided, it takes precedence over the automatic offset based on header height.
+     */
+    progressViewOffset?: ResolveRefreshControlOptions['progressViewOffset'];
     /**
      * Render function that receives scroll props and header context.
      * Use this to create custom scroll implementations that integrate with HeaderMotion.
@@ -35,6 +47,6 @@ export interface HeaderMotionScrollManagerProps {
  * </HeaderMotion>
  * ```
  */
-export declare function HeaderMotionScrollManager({ children, scrollId, }: HeaderMotionScrollManagerProps): ReactNode;
+export declare function HeaderMotionScrollManager({ children, scrollId, animatedRef, refreshControl, refreshing, onRefresh, progressViewOffset, }: HeaderMotionScrollManagerProps): ReactNode;
 export {};
 //# sourceMappingURL=ScrollManager.d.ts.map

package/lib/typescript/src/components/ScrollManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScrollManager.d.ts","sourceRoot":"","sources":["../../../../src/components/ScrollManager.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,KAAK,2BAA2B,GAAG,CACjC,eAAe,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EACvD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,KAChD,SAAS,CAAC;AAEf,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,EAAE,2BAA2B,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,QAAQ,EACR,QAAQ,GACT,EAAE,8BAA8B,aAUhC"}
+{"version":3,"file":"ScrollManager.d.ts","sourceRoot":"","sources":["../../../../src/components/ScrollManager.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,KAAK,2BAA2B,GAAG,CACjC,eAAe,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EACvD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,KAChD,SAAS,CAAC;AAEf,MAAM,WAAW,8BACf,SAAQ,IAAI,CAAC,4BAA4B,EAAE,oBAAoB,CAAC;IAChE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,4BAA4B,CAAC,oBAAoB,CAAC,CAAC;IACxE;;;OAGG;IACH,QAAQ,EAAE,2BAA2B,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,cAAc,EACd,UAAU,EACV,SAAS,EACT,kBAAkB,GACnB,EAAE,8BAA8B,aAgBhC"}

package/lib/typescript/src/components/ScrollView.d.ts

@@ -1,10 +1,15 @@
-import { type AnimatedScrollViewProps } from 'react-native-reanimated';
+import { type AnimatedRef, type AnimatedScrollViewProps } from 'react-native-reanimated';
 export type HeaderMotionScrollViewProps = AnimatedScrollViewProps & {
     /**
      * Optional unique identifier for this scroll view.
      * Use this when you have multiple scroll views (e.g. in tabs) to track them separately.
      */
     scrollId?: string;
+    /**
+     * Optional animated ref to use for the scroll view.
+     * When provided, the scroll manager will use this ref instead of creating its own.
+     */
+    animatedRef?: AnimatedRef<any>;
 };
 /**
  * Animated ScrollView component that integrates with HeaderMotion.
@@ -20,5 +25,5 @@ export type HeaderMotionScrollViewProps = AnimatedScrollViewProps & {
  * </HeaderMotion>
  * ```
  */
-export declare function HeaderMotionScrollView({ scrollId, children, contentContainerStyle, ...props }: HeaderMotionScrollViewProps): import("react/jsx-runtime").JSX.Element;
+export declare function HeaderMotionScrollView({ scrollId, animatedRef, children, contentContainerStyle, refreshControl, ...props }: HeaderMotionScrollViewProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ScrollView.d.ts.map

package/lib/typescript/src/components/ScrollView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScrollView.d.ts","sourceRoot":"","sources":["../../../../src/components/ScrollView.tsx"],"names":[],"mappings":"AAAA,OAAiB,EACf,KAAK,uBAAuB,EAC7B,MAAM,yBAAyB,CAAC;AAGjC,MAAM,MAAM,2BAA2B,GAAG,uBAAuB,GAAG;IAClE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,QAAQ,EACR,qBAAqB,EACrB,GAAG,KAAK,EACT,EAAE,2BAA2B,2CAyB7B"}
+{"version":3,"file":"ScrollView.d.ts","sourceRoot":"","sources":["../../../../src/components/ScrollView.tsx"],"names":[],"mappings":"AAAA,OAAiB,EACf,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC7B,MAAM,yBAAyB,CAAC;AAGjC,MAAM,MAAM,2BAA2B,GAAG,uBAAuB,GAAG;IAClE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,qBAAqB,EACrB,cAAc,EACd,GAAG,KAAK,EACT,EAAE,2BAA2B,2CAgC7B"}

package/lib/typescript/src/hooks/refreshControl.d.ts

@@ -0,0 +1,13 @@
+import { type ReactElement } from 'react';
+import { type RefreshControlProps } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+type MaybeShared<T> = T | SharedValue<T | undefined>;
+export interface ResolveRefreshControlOptions {
+    refreshControl?: MaybeShared<ReactElement<RefreshControlProps>>;
+    refreshing?: MaybeShared<boolean>;
+    onRefresh?: MaybeShared<() => void>;
+    progressViewOffset: MaybeShared<number>;
+}
+export declare function resolveRefreshControl({ refreshControl, refreshing, onRefresh, progressViewOffset, }: ResolveRefreshControlOptions): ReactElement<RefreshControlProps> | undefined;
+export {};
+//# sourceMappingURL=refreshControl.d.ts.map

package/lib/typescript/src/hooks/refreshControl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshControl.d.ts","sourceRoot":"","sources":["../../../../src/hooks/refreshControl.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,OAAO,CAAC;AACf,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AAErD,MAAM,WAAW,4BAA4B;IAC3C,cAAc,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAChE,UAAU,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,IAAI,CAAC,CAAC;IACpC,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACzC;AAeD,wBAAgB,qBAAqB,CAAC,EACpC,cAAc,EACd,UAAU,EACV,SAAS,EACT,kBAAkB,GACnB,EAAE,4BAA4B,GAC3B,YAAY,CAAC,mBAAmB,CAAC,GACjC,SAAS,CAgBZ"}

package/lib/typescript/src/hooks/useScrollManager.d.ts

@@ -1,4 +1,6 @@
+import { type AnimatedRef } from 'react-native-reanimated';
 import type { ScrollManagerConfig } from '../types';
+import { type ResolveRefreshControlOptions } from './refreshControl';
 /**
  * Hook that manages scroll tracking and synchronization for header animations.
  * Returns props to apply to scrollable components and additional values that help with adjusting styling of the scrollables to header's dimensions.
@@ -12,6 +14,9 @@ import type { ScrollManagerConfig } from '../types';
  *
  * @param scrollId - Optional unique identifier for the related scrollable.
  *                   Use when you have multiple scrollables (e.g., in tabs).
+ * @param options - Optional configuration object.
+ * @param options.animatedRef - Optional animated ref to use instead of creating one internally.
+ *                              Useful when you need access to the scroll view ref from outside.
  * @returns Configuration object containing:
  * - `scrollableProps`: Props to apply to scrollable component (onScroll, scrollEventThrottle, ref)
  * - `headerMotionContext`: Header context values (originalHeaderHeight, minHeightContentContainerStyle)
@@ -33,5 +38,17 @@ import type { ScrollManagerConfig } from '../types';
  * }
  * ```
  */
-export declare function useScrollManager(scrollId?: string): ScrollManagerConfig;
+export interface UseScrollManagerOptions extends Omit<ResolveRefreshControlOptions, 'progressViewOffset'> {
+    /**
+     * Optional animated ref to use instead of creating one internally.
+     * Useful when you need access to the scroll view ref from outside.
+     */
+    animatedRef?: AnimatedRef<any>;
+    /**
+     * Optional refresh progress offset override.
+     * When provided, it takes precedence over the automatic offset based on header height.
+     */
+    progressViewOffset?: ResolveRefreshControlOptions['progressViewOffset'];
+}
+export declare function useScrollManager(scrollId?: string, options?: UseScrollManagerOptions): ScrollManagerConfig;
 //# sourceMappingURL=useScrollManager.d.ts.map

package/lib/typescript/src/hooks/useScrollManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useScrollManager.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useScrollManager.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAgB,MAAM,UAAU,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAwIvE"}
+{"version":3,"file":"useScrollManager.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useScrollManager.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,WAAW,EAEjB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAAE,mBAAmB,EAAgB,MAAM,UAAU,CAAC;AAElE,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,uBACf,SAAQ,IAAI,CAAC,4BAA4B,EAAE,oBAAoB,CAAC;IAChE;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,4BAA4B,CAAC,oBAAoB,CAAC,CAAC;CACzE;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,uBAAuB,GAChC,mBAAmB,CAsJrB"}

package/lib/typescript/src/types.d.ts

@@ -1,4 +1,5 @@
-import type { LayoutChangeEvent, ScrollViewProps } from 'react-native';
+import type { ReactElement } from 'react';
+import type { LayoutChangeEvent, RefreshControlProps, ScrollViewProps } from 'react-native';
 import type { AnimatedRef, SharedValue } from 'react-native-reanimated';
 import { DEFAULT_SCROLL_ID } from './utils/defaults';
 export type Progress = SharedValue<number>;
@@ -36,6 +37,7 @@ export interface ScrollManagerHeaderMotionContext {
 }
 export interface ScrollManagerConfig {
     scrollableProps: Required<Pick<ScrollViewProps, 'onScroll' | 'scrollEventThrottle'>> & {
+        refreshControl?: ReactElement<RefreshControlProps>;
         ref: AnimatedRef<any>;
     };
     headerMotionContext: ScrollManagerHeaderMotionContext;

package/lib/typescript/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAE3C,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,CAAC,CAAC,mBAAmB,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;AAC9C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,EAAE,iBAAiB,KAAK,MAAM,CAAC;AACrE,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEzE,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC5D,KAAK,EAAE,CAAC,CAAC;IACT,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CACpB,CAAC;AACF,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAErE,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG;KACtD,GAAG,IAAI,OAAO,iBAAiB,CAAC,CAAC,EAAE,WAAW;CAChD,CAAC;AAEF,MAAM,MAAM,0BAA0B,CACpC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzD,CAAC,GAAG,cAAc,CAAC;AAEvB,MAAM,MAAM,+BAA+B,CACzC,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzD,0BAA0B,CAAC,CAAC,CAAC,GAAG;IAClC,WAAW,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACnC,SAAS,EAAE,GAAG,CAAC;CAChB,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,2BAA2B,CAAC;IAChD,cAAc,EAAE,2BAA2B,CAAC;CAC7C;AAED,MAAM,WAAW,gCAAgC;IAC/C,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8BAA8B,EAC1B,EAAE,GACF;QACE,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACP;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,QAAQ,CACvB,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,qBAAqB,CAAC,CAC1D,GAAG;QACF,GAAG,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;KACvB,CAAC;IACF,mBAAmB,EAAE,gCAAgC,CAAC;CACvD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EAChB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAE3C,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,CAAC,CAAC,mBAAmB,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;AAC9C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,EAAE,iBAAiB,KAAK,MAAM,CAAC;AACrE,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEzE,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC5D,KAAK,EAAE,CAAC,CAAC;IACT,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CACpB,CAAC;AACF,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAErE,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG;KACtD,GAAG,IAAI,OAAO,iBAAiB,CAAC,CAAC,EAAE,WAAW;CAChD,CAAC;AAEF,MAAM,MAAM,0BAA0B,CACpC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzD,CAAC,GAAG,cAAc,CAAC;AAEvB,MAAM,MAAM,+BAA+B,CACzC,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzD,0BAA0B,CAAC,CAAC,CAAC,GAAG;IAClC,WAAW,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACnC,SAAS,EAAE,GAAG,CAAC;CAChB,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,2BAA2B,CAAC;IAChD,cAAc,EAAE,2BAA2B,CAAC;CAC7C;AAED,MAAM,WAAW,gCAAgC;IAC/C,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8BAA8B,EAC1B,EAAE,GACF;QACE,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACP;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,QAAQ,CACvB,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,qBAAqB,CAAC,CAC1D,GAAG;QACF,cAAc,CAAC,EAAE,YAAY,CAAC,mBAAmB,CAAC,CAAC;QACnD,GAAG,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;KACvB,CAAC;IACF,mBAAmB,EAAE,gCAAgC,CAAC;CACvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-header-motion",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Smooth, animated collapsible headers with scroll-based motion control in React Native",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/components/FlatList.tsx

@@ -1,19 +1,22 @@
 import { forwardRef, type ComponentProps, type ComponentRef } from 'react';
-import Animated from 'react-native-reanimated';
+import Animated, { type AnimatedRef } from 'react-native-reanimated';
 import { HeaderMotionScrollManager } from './ScrollManager';
 
 import type { ScrollViewProps } from 'react-native';
 
-type AnimatedFlatListProps<T = any> = ComponentProps<
+export type HeaderMotionFlatListProps<T = any> = ComponentProps<
   typeof Animated.FlatList<T>
->;
-
-export type HeaderMotionFlatListProps<T = any> = AnimatedFlatListProps<T> & {
+> & {
   /**
    * Optional unique identifier for this scroll view.
    * Use this when you have multiple scroll views (e.g. in tabs) to track them separately.
    */
   scrollId?: string;
+  /**
+   * Optional animated ref to use for the flat list.
+   * When provided, the scroll manager will use this ref instead of creating its own.
+   */
+  animatedRef?: AnimatedRef<any>;
 };
 
 /**
@@ -35,22 +38,33 @@ export type HeaderMotionFlatListProps<T = any> = AnimatedFlatListProps<T> & {
  */
 export function HeaderMotionFlatList<T = any>({
   scrollId,
+  animatedRef,
   contentContainerStyle,
   ...props
 }: HeaderMotionFlatListProps<T>) {
   return (
-    <HeaderMotionScrollManager scrollId={scrollId}>
+    <HeaderMotionScrollManager
+      scrollId={scrollId}
+      animatedRef={animatedRef}
+      refreshControl={props.refreshControl}
+      refreshing={props.refreshing}
+      onRefresh={props.onRefresh}
+      progressViewOffset={props.progressViewOffset}
+    >
       {(
-        { onScroll, ...scrollViewProps },
+        { onScroll, refreshControl: managedRefreshControl, ...scrollViewProps },
         { originalHeaderHeight, minHeightContentContainerStyle }
       ) => (
         <Animated.FlatList
           {...scrollViewProps}
           {...props}
           onScroll={onScroll}
-          renderScrollComponent={(propsz) => (
+          {...(managedRefreshControl && {
+            refreshControl: managedRefreshControl,
+          })}
+          renderScrollComponent={(scrollComponentProps) => (
             <AnimatedScrollContainer
-              {...propsz}
+              {...scrollComponentProps}
               contentContainerStyle={[
                 minHeightContentContainerStyle,
                 { paddingTop: originalHeaderHeight },

package/src/components/ScrollManager.tsx

@@ -1,18 +1,31 @@
 import { useScrollManager } from '../hooks';
 import type { ScrollManagerConfig } from '../types';
+import type { ResolveRefreshControlOptions } from '../hooks/refreshControl';
 import type { ReactNode } from 'react';
+import type { AnimatedRef } from 'react-native-reanimated';
 
 type ScrollManagerRenderChildren = (
   scrollableProps: ScrollManagerConfig['scrollableProps'],
   options: ScrollManagerConfig['headerMotionContext']
 ) => ReactNode;
 
-export interface HeaderMotionScrollManagerProps {
+export interface HeaderMotionScrollManagerProps
+  extends Omit<ResolveRefreshControlOptions, 'progressViewOffset'> {
   /**
    * Optional unique identifier for this scroll view.
    * Use this when you have multiple scroll views (e.g., in tabs) to track them separately.
    */
   scrollId?: string;
+  /**
+   * Optional animated ref to use for the scroll view.
+   * When provided, the scroll manager will use this ref instead of creating its own.
+   */
+  animatedRef?: AnimatedRef<any>;
+  /**
+   * Optional refresh progress offset override.
+   * When provided, it takes precedence over the automatic offset based on header height.
+   */
+  progressViewOffset?: ResolveRefreshControlOptions['progressViewOffset'];
   /**
    * Render function that receives scroll props and header context.
    * Use this to create custom scroll implementations that integrate with HeaderMotion.
@@ -45,6 +58,11 @@ export interface HeaderMotionScrollManagerProps {
 export function HeaderMotionScrollManager({
   children,
   scrollId,
+  animatedRef,
+  refreshControl,
+  refreshing,
+  onRefresh,
+  progressViewOffset,
 }: HeaderMotionScrollManagerProps) {
   if (typeof children !== 'function') {
     throw new Error(
@@ -52,7 +70,13 @@ export function HeaderMotionScrollManager({
     );
   }
 
-  const { scrollableProps, headerMotionContext } = useScrollManager(scrollId);
+  const { scrollableProps, headerMotionContext } = useScrollManager(scrollId, {
+    animatedRef,
+    refreshControl,
+    refreshing,
+    onRefresh,
+    progressViewOffset,
+  });
 
   return children(scrollableProps, headerMotionContext);
 }

package/src/components/ScrollView.tsx

@@ -1,4 +1,5 @@
 import Animated, {
+  type AnimatedRef,
   type AnimatedScrollViewProps,
 } from 'react-native-reanimated';
 import { HeaderMotionScrollManager } from './ScrollManager';
@@ -9,6 +10,11 @@ export type HeaderMotionScrollViewProps = AnimatedScrollViewProps & {
    * Use this when you have multiple scroll views (e.g. in tabs) to track them separately.
    */
   scrollId?: string;
+  /**
+   * Optional animated ref to use for the scroll view.
+   * When provided, the scroll manager will use this ref instead of creating its own.
+   */
+  animatedRef?: AnimatedRef<any>;
 };
 
 /**
@@ -27,20 +33,29 @@ export type HeaderMotionScrollViewProps = AnimatedScrollViewProps & {
  */
 export function HeaderMotionScrollView({
   scrollId,
+  animatedRef,
   children,
   contentContainerStyle,
+  refreshControl,
   ...props
 }: HeaderMotionScrollViewProps) {
   return (
-    <HeaderMotionScrollManager scrollId={scrollId}>
+    <HeaderMotionScrollManager
+      scrollId={scrollId}
+      animatedRef={animatedRef}
+      refreshControl={refreshControl}
+    >
       {(
-        { onScroll, ...scrollViewProps },
+        { onScroll, refreshControl: managedRefreshControl, ...scrollViewProps },
         { originalHeaderHeight, minHeightContentContainerStyle }
       ) => (
         <Animated.ScrollView
           {...scrollViewProps}
           {...props}
           onScroll={onScroll}
+          {...(managedRefreshControl && {
+            refreshControl: managedRefreshControl,
+          })}
         >
           <Animated.View
             style={[

package/src/hooks/refreshControl.ts

@@ -0,0 +1,55 @@
+import {
+  cloneElement,
+  createElement,
+  isValidElement,
+  type ReactElement,
+} from 'react';
+import { RefreshControl, type RefreshControlProps } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+
+type MaybeShared<T> = T | SharedValue<T | undefined>;
+
+export interface ResolveRefreshControlOptions {
+  refreshControl?: MaybeShared<ReactElement<RefreshControlProps>>;
+  refreshing?: MaybeShared<boolean>;
+  onRefresh?: MaybeShared<() => void>;
+  progressViewOffset: MaybeShared<number>;
+}
+
+function injectProgressViewOffset(
+  refreshControl: ReactElement<RefreshControlProps>,
+  progressViewOffset: MaybeShared<number>
+) {
+  if (refreshControl.props.progressViewOffset !== undefined) {
+    return refreshControl;
+  }
+
+  return cloneElement(refreshControl, {
+    progressViewOffset: progressViewOffset as number,
+  });
+}
+
+export function resolveRefreshControl({
+  refreshControl,
+  refreshing,
+  onRefresh,
+  progressViewOffset,
+}: ResolveRefreshControlOptions):
+  | ReactElement<RefreshControlProps>
+  | undefined {
+  if (refreshControl) {
+    return isValidElement<RefreshControlProps>(refreshControl)
+      ? injectProgressViewOffset(refreshControl, progressViewOffset)
+      : undefined;
+  }
+
+  if (!onRefresh) {
+    return undefined;
+  }
+
+  return createElement(RefreshControl, {
+    refreshing: (refreshing as boolean) ?? false,
+    onRefresh: onRefresh as () => void,
+    progressViewOffset: progressViewOffset as number,
+  }) as unknown as ReactElement<RefreshControlProps>;
+}

package/src/hooks/useScrollManager.ts

@@ -6,12 +6,17 @@ import {
   useAnimatedRef,
   useAnimatedScrollHandler,
   useAnimatedStyle,
+  type AnimatedRef,
   type ScrollHandler,
 } from 'react-native-reanimated';
 import { RuntimeKind, scheduleOnUI } from 'react-native-worklets';
 import { HeaderMotionContext } from '../context';
 import type { ScrollManagerConfig, ScrollValues } from '../types';
 import { DEFAULT_SCROLL_ID, getInitialScrollValue } from '../utils';
+import {
+  resolveRefreshControl,
+  type ResolveRefreshControlOptions,
+} from './refreshControl';
 
 /**
  * Hook that manages scroll tracking and synchronization for header animations.
@@ -26,6 +31,9 @@ import { DEFAULT_SCROLL_ID, getInitialScrollValue } from '../utils';
  *
  * @param scrollId - Optional unique identifier for the related scrollable.
  *                   Use when you have multiple scrollables (e.g., in tabs).
+ * @param options - Optional configuration object.
+ * @param options.animatedRef - Optional animated ref to use instead of creating one internally.
+ *                              Useful when you need access to the scroll view ref from outside.
  * @returns Configuration object containing:
  * - `scrollableProps`: Props to apply to scrollable component (onScroll, scrollEventThrottle, ref)
  * - `headerMotionContext`: Header context values (originalHeaderHeight, minHeightContentContainerStyle)
@@ -47,7 +55,24 @@ import { DEFAULT_SCROLL_ID, getInitialScrollValue } from '../utils';
  * }
  * ```
  */
-export function useScrollManager(scrollId?: string): ScrollManagerConfig {
+export interface UseScrollManagerOptions
+  extends Omit<ResolveRefreshControlOptions, 'progressViewOffset'> {
+  /**
+   * Optional animated ref to use instead of creating one internally.
+   * Useful when you need access to the scroll view ref from outside.
+   */
+  animatedRef?: AnimatedRef<any>;
+  /**
+   * Optional refresh progress offset override.
+   * When provided, it takes precedence over the automatic offset based on header height.
+   */
+  progressViewOffset?: ResolveRefreshControlOptions['progressViewOffset'];
+}
+
+export function useScrollManager(
+  scrollId?: string,
+  options?: UseScrollManagerOptions
+): ScrollManagerConfig {
   const ctxValue = useContext(HeaderMotionContext);
   if (!ctxValue) {
     throw new Error(
@@ -64,7 +89,13 @@ export function useScrollManager(scrollId?: string): ScrollManagerConfig {
   } = ctxValue;
   const id = scrollId ?? DEFAULT_SCROLL_ID;
 
-  const animatedRef = useAnimatedRef<any>(); // TODO: better typing
+  const localRef = useAnimatedRef<any>(); // TODO: better typing
+  const animatedRef = options?.animatedRef ?? localRef;
+  const refreshControl = options?.refreshControl;
+  const refreshing = options?.refreshing;
+  const onRefresh = options?.onRefresh;
+  const progressViewOffset =
+    options?.progressViewOffset ?? originalHeaderHeight;
 
   useEffect(() => {
     return () => {
@@ -172,10 +203,18 @@ export function useScrollManager(scrollId?: string): ScrollManagerConfig {
     };
   });
 
+  const resolvedRefreshControl = resolveRefreshControl({
+    refreshControl,
+    refreshing,
+    onRefresh,
+    progressViewOffset,
+  });
+
   const scrollableProps = {
     onScroll,
     scrollEventThrottle: 16,
     ref: animatedRef,
+    refreshControl: resolvedRefreshControl,
   };
   const headerMotionContext = {
     originalHeaderHeight,

package/src/types.ts

@@ -1,4 +1,9 @@
-import type { LayoutChangeEvent, ScrollViewProps } from 'react-native';
+import type { ReactElement } from 'react';
+import type {
+  LayoutChangeEvent,
+  RefreshControlProps,
+  ScrollViewProps,
+} from 'react-native';
 import type { AnimatedRef, SharedValue } from 'react-native-reanimated';
 import { DEFAULT_SCROLL_ID } from './utils/defaults';
 
@@ -56,6 +61,7 @@ export interface ScrollManagerConfig {
   scrollableProps: Required<
     Pick<ScrollViewProps, 'onScroll' | 'scrollEventThrottle'>
   > & {
+    refreshControl?: ReactElement<RefreshControlProps>;
     ref: AnimatedRef<any>; // TODO: better typing
   };
   headerMotionContext: ScrollManagerHeaderMotionContext;