react-native-collapsible-header-tabs

Zero-glitch collapsible parallax header with swipeable tab pages for React Native.

Built on Reanimated v4 and react-native-pager-view for frame-perfect header/scroll synchronization — no gaps, no stuttering, no jank.

Features

• ✅ Frame-perfect sync — header and list update in the same UI thread frame
• ✅ Snap-to-edge — header snaps to fully expanded or fully collapsed after a gesture, velocity-aware
• ✅ Auto-sized tab bar — no need to specify tabBarHeight; the library measures the real rendered height automatically
• ✅ Decorator row — easily add a custom row below the tab buttons (e.g. rounded corners, search bar, filter chips) via renderTabBarDecorator
• ✅ Tab switch without jump — inactive tabs are pre-positioned before the transition starts
• ✅ Zero re-render snapping — all animation runs on the UI thread via Reanimated worklets
• ✅ Render props — full control over header content, tab content, and tab bar UI
• ✅ FlashList & FlatList — use CollapsibleFlashList for virtualized lists inside tabs
• ✅ TypeScript — fully typed

Installation

npm install react-native-collapsible-header-tabs
# or
yarn add react-native-collapsible-header-tabs

Peer dependencies

yarn add react-native-reanimated react-native-pager-view react-native-safe-area-context @shopify/flash-list

| Package | Min version | |---------|-------------| | react-native | >= 0.73 | | react-native-reanimated | >= 4.0 | | react-native-pager-view | >= 6.0 | | react-native-safe-area-context | >= 4.0 | | @shopify/flash-list | >= 1.0 |

Quick start

import React from 'react';
import { View, Text } from 'react-native';
import { useSafeAreaInsets } from 'react-native-safe-area-context';
import {
  CollapsibleHeaderTabView,
  CollapsibleScrollable,
} from 'react-native-collapsible-header-tabs';

const TABS = [
  { key: 'posts', title: 'Posts' },
  { key: 'photos', title: 'Photos' },
  { key: 'likes', title: 'Likes' },
];

export function ProfileScreen() {
  const insets = useSafeAreaInsets();

  return (
    <CollapsibleHeaderTabView
      tabs={TABS}
      headerHeight={300}
      minHeaderHeight={insets.top + 44}
      renderHeader={() => (
        <View style={{ flex: 1, backgroundColor: '#1a0a4e' }}>
          {/* your header content */}
        </View>
      )}
      renderScene={({ tab, index }) => (
        <CollapsibleScrollable tabIndex={index}>
          <Text>{tab.title} content</Text>
        </CollapsibleScrollable>
      )}
      onTabChange={(index) => console.log('Active tab:', index)}
    />
  );
}

API

<CollapsibleHeaderTabView>

| Prop | Type | Default | Description | |------|------|---------|-------------| | tabs | TabDefinition[] | required | Array of { key, title, icon? }. | | renderHeader | (props: CollapsibleHeaderProps) => ReactElement | required | Renders the parallax header. Receives scrollY, headerHeight, minHeaderHeight. | | renderScene | (params: RenderSceneParams) => ReactElement | required | Renders the content for each tab. Must use CollapsibleScrollable or CollapsibleFlashList as the root scroll container. | | renderTabBar | (props: TabBarProps) => ReactElement | built-in | Replaces the default tab bar entirely. Receives all TabBarProps including the animated scrollX value. | | headerHeight | number | required | Full (expanded) height of the header in points. | | minHeaderHeight | number | 0 | Height the header collapses to. Set to insets.top + 44 to keep a nav bar visible. | | tabBarHeight | number | 48 | Initial estimate for the tab bar height (tabs row only). The library measures the actual rendered height after layout and keeps scroll padding in sync automatically. Providing this value avoids a one-frame padding jump on first render. | | snapConfig | SnapConfig | — | Enable snap-to-edge behaviour. Pass {} for defaults. See Snap. | | renderTabBarDecorator | () => ReactNode | — | Renders a custom row directly below the tab buttons, inside the sticky tab bar. Height is auto-measured — no manual calculation needed. See Decorator row. | | tabBarDecoratorStyle | StyleProp<ViewStyle> | — | Style applied to the decorator row's container View. | | initialTabIndex | number | 0 | Initially selected tab. | | onTabChange | (index: number) => void | — | Called when the active tab changes (after swipe or tap settles). | | style | StyleProp<ViewStyle> | — | Style for the outermost container. |

renderScene — tab content

Each scene must use CollapsibleScrollable or CollapsibleFlashList as its scroll root. These components automatically:

• Read headerHeight + tabBarHeight from context to apply the correct paddingTop
• Register their scroll ref so the library can programmatically sync scroll position on tab switch
• Drive the shared scrollY value used by the header animation

renderScene={({ tab, index }) => (
  <CollapsibleScrollable tabIndex={index}>
    {/* your content */}
  </CollapsibleScrollable>
)}

CollapsibleScrollable props

| Prop | Type | Default | Description | |------|------|---------|-------------| | tabIndex | number | required | Must match the index from renderScene. | | contentBottomPadding | number | 32 | Extra padding below the last list item. | | children | ReactElement \| ReactElement[] | — | Scroll content. |

CollapsibleFlashList — optional FlashList wrapper

Note: CollapsibleFlashList is not included in the main package bundle to keep @shopify/flash-list optional. Import it via a separate path:

import { CollapsibleFlashList } from 'react-native-collapsible-header-tabs/flash-list';

renderScene={({ tab, index }) => (
  <CollapsibleFlashList
    tabIndex={index}
    data={myData}
    keyExtractor={(item) => item.id}
    estimatedItemSize={80}
    renderItem={({ item }) => <MyRow item={item} />}
  />
)}

Accepts all FlashListProps<T> except onScroll, scrollEventThrottle, and contentContainerStyle (managed internally), plus:

| Prop | Type | Default | Description | |------|------|---------|-------------| | tabIndex | number | required | Must match the index from renderScene. | | contentBottomPadding | number | 32 | Extra padding below the last list item. |

useCollapsibleScrollHandler — custom scroll components

If you have your own scroll component (e.g. MasonryList, a custom FlatList wrapper, etc.), use this hook directly instead of CollapsibleScrollable:

import {
  useCollapsibleScrollHandler,
  useCollapsibleContext,
} from 'react-native-collapsible-header-tabs';
import { useAnimatedRef } from 'react-native-reanimated';
import { useEffect } from 'react';

function MyTab({ tabIndex }: { tabIndex: number }) {
  const { headerHeight, tabBarHeight, scrollableRefs } = useCollapsibleContext();
  const scrollRef = useAnimatedRef<Animated.ScrollView>();

  // Register the ref so tab-switch sync works
  useEffect(() => {
    scrollableRefs.current.set(tabIndex, scrollRef);
    return () => { scrollableRefs.current.delete(tabIndex); };
  }, [tabIndex]);

  const scrollHandler = useCollapsibleScrollHandler(tabIndex);

  return (
    <MasonryList
      ref={scrollRef}
      onScroll={scrollHandler}
      scrollEventThrottle={16}
      contentContainerStyle={{ paddingTop: headerHeight + tabBarHeight }}
      data={myData}
      renderItem={renderItem}
    />
  );
}

The hook handles onBeginDrag, onScroll, onEndDrag, and onMomentumEnd — including snap logic if snapConfig is set on the parent CollapsibleHeaderTabView.

Snap

By default the header follows the scroll position freely and rests wherever the user's finger stops. Pass snapConfig to make the header always animate to one of two positions: fully expanded (scrollY = 0) or fully collapsed (scrollY = collapseRange).

Enable with defaults

<CollapsibleHeaderTabView
  snapConfig={{}}
  ...
/>

Custom thresholds

<CollapsibleHeaderTabView
  snapConfig={{
    snapThreshold: 0.5,       // snap to nearest edge (50/50 split)
    velocityThreshold: 150,   // px/s — fast gesture overrides position
    snapDuration: 300,        // ms — animation duration
  }}
  ...
/>

SnapConfig reference

| Field | Type | Default | Description | |-------|------|---------|-------------| | snapThreshold | number | 0.01 | Fraction of collapseRange used as position threshold. If the header is past this fraction from its nearest edge, it snaps to that edge instead of the opposite. A value of 0.5 gives a symmetric 50/50 split. | | velocityThreshold | number | 100 | px/s. If the end-drag velocity exceeds this value, snap direction is forced by velocity regardless of position. Positive velocity (scroll down) → collapse; negative → expand. | | snapDuration | number | 220 | Duration of the snap withTiming animation in milliseconds. |

How snap works

1. onBeginDrag — if a snap animation is running, it is cancelled immediately so the user regains control.
2. onEndDrag — velocity is checked first. If |vy| > velocityThreshold the direction is forced. Otherwise the current header position is compared against an asymmetric threshold from the nearest edge.
3. onMomentumEnd — safety net for cases where the list's momentum scroll leaves the header in a mid-state.
4. withTiming + useAnimatedReaction — the snap animation drives scrollY via withTiming, and a useAnimatedReaction mirrors every intermediate value back to all registered scroll refs via scrollTo(ref, false). Both the header translateY and the list contentOffset update in the same UI thread frame — zero gap, zero glitch.

renderHeader — collapsible header

renderHeader={(props) => (
  <View style={{ flex: 1, backgroundColor: '#1a0a4e' }}>
    {/* use props.scrollY to drive animations inside the header */}
  </View>
)}

CollapsibleHeaderProps

| Field | Type | Description | |-------|------|-------------| | scrollY | SharedValue<number> | Current scroll offset (0 = fully expanded, collapseRange = fully collapsed). Use with useAnimatedStyle for parallax effects. | | headerHeight | number | Full expanded height. | | minHeaderHeight | number | Collapsed height. |

renderTabBar — custom tab bar

Replace the default tab bar with your own component. Receives TabBarProps:

| Field | Type | Description | |-------|------|-------------| | tabs | TabDefinition[] | All tab definitions. | | activeIndex | number | Currently active tab index. | | scrollX | SharedValue<number> | PagerView position + offset (0.0 → n-1). Use to animate a sliding indicator on the UI thread. | | onTabPress | (index: number) => void | Call when a tab button is pressed. | | tabBarHeight | number | Tab row height (excludes decorator). | | renderTabBarDecorator | () => ReactNode | Forwarded from parent. | | tabBarDecoratorStyle | StyleProp<ViewStyle> | Forwarded from parent. |

Decorator row

renderTabBarDecorator lets you add any content directly below the tab buttons, inside the sticky tab bar panel. The height is measured automatically — you never need to add the decorator height to tabBarHeight manually.

Rounded card effect

A common pattern is a rounded top edge that makes the content area look like a card sliding in from behind the header:

<CollapsibleHeaderTabView
  ...
  renderTabBarDecorator={() => (
    <View style={{
      height: 24,
      backgroundColor: '#fff',
      borderTopLeftRadius: 24,
      borderTopRightRadius: 24,
    }} />
  )}
/>

Filter chips / search bar

renderTabBarDecorator={() => (
  <ScrollView horizontal style={{ backgroundColor: '#fff', paddingHorizontal: 12, paddingVertical: 8 }}>
    {FILTERS.map((f) => (
      <FilterChip key={f.key} label={f.label} />
    ))}
  </ScrollView>
)}

Hiding the decorator on a specific tab

Since renderTabBarDecorator doesn't receive the active tab index, pair it with onTabChange state:

const [activeIndex, setActiveIndex] = useState(0);

<CollapsibleHeaderTabView
  onTabChange={setActiveIndex}
  renderTabBarDecorator={() =>
    activeIndex !== 2 ? <DecoratorView /> : null
  }
  ...
/>

TabDefinition

interface TabDefinition {
  key: string;       // unique identifier
  title: string;     // display label
  icon?: ReactNode;  // optional icon shown next to label in the default tab bar
}

How it works

Header / scroll sync

The header translateY is driven by a shared scrollY value. Each CollapsibleScrollable writes to scrollY in a Reanimated worklet on the UI thread whenever it is the active tab. The header and tab bar read scrollY via useAnimatedStyle — all in the same UI thread frame with zero JS-bridge involvement.

Tab switch without jump

When switching tabs (tap or swipe), the destination tab's scroll position is pre-set to match the current scrollY before the transition starts. This prevents the header "jumping" when a tab with different scroll history becomes visible.

Auto tab bar sizing

The entire tab bar Animated.View (tabs row + decorator) has no fixed height. After the first render, onLayout captures the real rendered height and stores it in state. CollapsibleProvider then re-provides the value to all CollapsibleScrollable instances so their paddingTop is always up to date.

Limitations

• Android: Tested primarily on iOS. PagerView scroll behavior may differ on Android — verify tab swipe pre-positioning.
• Horizontal ScrollView inside tabs: Not supported in the same scroll hierarchy.
• Max tabs: No hard limit (unlike previous versions using pre-created refs). Tabs use PagerView children count dynamically.

License

MIT © Your Name