React Native Header Motion

The example app contains standalone screens located in example/src/app/ that demonstrate various implementation scenarios, including:

• Header Behaviors: Simple collapsible headers with navigation bridging, pannable headers, and overscroll effects.
• Offset Strategies: All five offset strategies provided by the library.
• Scrollable Integrations: Support for custom scrollables like FlashList and LegendList.
• Advanced Interactions: Multi-page pager setups, pull to refresh, consumer scroll handlers, and usage with external refs.

The library provides several key capabilities for building complex header animations:

• Automatic Layout Measurement: Automatically measures the total header height and the collapsible portion via <HeaderMotion.Header> and <HeaderMotion.Header.Dynamic>.
• Progress Derivation: Generates a Reanimated shared value named progress that transitions from 0 (expanded) to 1 (collapsed) based on scroll offset.
• Scrollable Synchronization: Orchestrates scroll positions across multiple scrollables, which is useful when a header is shared across tabs or pager pages.
• Navigation Integration: Provides bridging mechanisms to control motion within headers rendered by React Navigation or Expo Router, which typically exist outside the standard component tree.

Choose between providing a manual threshold or using dynamic measurement based on your layout requirements:

When using contentContainerMode: 'renderScrollComponent', you may need to set managedRefTarget: 'inner'.

Use 'inner' when the wrapped component exposes a controller ref on its outside but owns the actual native scroll view internally. This is required for FlashList and LegendList. Standard React Native FlatList does not require this and should use the default 'outer' value.

const HeaderMotionFlashList = createHeaderMotionScrollable(FlashList, {
  displayName: 'HeaderMotionFlashList',
  contentContainerMode: 'renderScrollComponent',
  managedRefTarget: 'inner',
});

If you are not using a navigation library's built-in header (e.g., you have opted out of the navigation header and are rendering your own header component directly inside the screen), you do not need to use Bridge or NavigationBridge. The header will naturally be part of the HeaderMotion subtree and can access context directly.

<HeaderMotion>
  <MyHeader />
  <HeaderMotion.ScrollView>{/* content */}</HeaderMotion.ScrollView>
</HeaderMotion>

Components

• HeaderMotion: The root provider required for all features.
• HeaderMotion.Header: The container for your header. It measures the total header height and overlays it above the scrollable content.
• HeaderMotion.Header.Dynamic: Marks a specific section within the header whose layout defines the progressThreshold.
• HeaderMotion.Bridge: Captures the motion context to be passed to navigation-rendered headers.
• HeaderMotion.NavigationBridge: Re-provides the motion context inside a navigation header.
• HeaderMotion.ScrollView: A drop-in replacement for ScrollView that tracks scroll position.
• HeaderMotion.FlatList: A drop-in replacement for FlatList that tracks scroll position.

Hooks

• useMotionProgress(): Returns { progress, progressThreshold } as Reanimated shared values.

In v1, HeaderMotion.Header is no longer a render-prop bridge for navigation. Instead, you must use a two-step bridging process:

1. Wrap your navigation configuration in HeaderMotion.Bridge to get the context (ctx).
2. Wrap your header component in HeaderMotion.NavigationBridge using that context.

Inside your header component, use useMotionProgress() to access motion data.

<HeaderMotion.Bridge>
  {(ctx) => (
    <Stack.Screen
      options={{
        header: () => (
          <HeaderMotion.NavigationBridge value={ctx}>
            <MyHeader />
          </HeaderMotion.NavigationBridge>
        ),
      }}
    />
  )}
</HeaderMotion.Bridge>

HeaderMotion.Header.Dynamic is a measurement tool, not a restricted animation component. Its primary purpose is to measure its own size so the library can calculate the progressThreshold (the amount of scroll required to reach progress: 1).

When to use it: Wrap any part of your header in Header.Dynamic if that element's size should influence the collapse threshold. If an element is supposed to visually disappear as the header collapses, wrapping it in Header.Dynamic ensures the scrollable content offset is calculated correctly.

What you can animate: You are not limited to animating only the Dynamic component. You can animate any element in the header (including HeaderMotion.Header itself) using standard Reanimated properties like opacity, scale, translateY, or color.

Header panning is supported on both iOS and Android.

• iOS: The pannable implementation specifically targets iOS to provide the panning behavior.
• Android: Panning is handled natively in tested implementations, so no additional configuration is required for Android.

Header Motion is designed to be compatible with both standard React Native callbacks and Reanimated animated handlers. It automatically detects the type of onScroll prop provided:

1. Standard Callbacks: Bridged via scheduleOnRN to run on the JS thread.
2. Reanimated Handlers: Composed via useComposedEventHandler to run on the UI thread.

In both cases, the library's internal scroll tracking for header animations remains functional and does not interfere with your custom logic.