# **react-native-synced-tab-view**
Synchronized top tabs with a measured, collapsible header for React Native. Build profile, feed, and dashboard layouts where horizontal paging and vertical scroll positions stay aligned across tabs.
[](https://github.com/user-attachments/assets/bda34c41-86ae-4324-999d-5637040c3a10)
## **โก Powered by Reanimated + Worklets**
This library uses `react-native-reanimated` and `react-native-worklets` to keep tab switching, header collapse, and scroll synchronization smooth across modern React Native apps.
* **Smooth shared-value driven interactions**: Active tab state and indicator movement are animated with Reanimated.
* **Synchronized scrolling**: Header and tab content offsets stay coordinated when users swipe between tabs.
* **Modern compatibility**: Built for current React Native projects using Reanimated `>= 4`.
## **โจ Features**
* **Collapsible Header Layout**: Render any header above your tabs and let the package measure and sync it automatically.
* **Synced Tab Content**: Keep vertical scroll state aligned while switching between tab pages.
* **Ready-to-use Scroll Wrappers**: Use `TabFlatList`, `TabSectionList`, and `TabScrollView` out of the box.
* **Custom List Support**: Wrap third-party scrollers like FlashList or Legend List with `createSyncedTabScrollComponent`.
* **Customizable Top Tabs**: Style the indicator, labels, colors, and even provide a fully custom `renderTabItem`.
* **Profile-style UI Friendly**: Designed for layouts like social profiles, dashboards, and content hubs.
## **๐งฉ Compatibility**
| Target | Supported Version |
| :---- | :---- |
| React Native | `>= 0.76` |
| React | `>= 18` |
| Reanimated | `>= 4` |
| React Native Worklets | `>= 0.7.0` |
| Android | Supported |
| iOS | Supported |
| Web | Not supported yet |
## **๐ฆ Installation**
Install the package and its peer dependencies:
```bash
yarn add react-native-synced-tab-view react-native-reanimated react-native-worklets
```
### **Peer Dependency Setup**
Make sure your project is already configured for `react-native-reanimated`. After installing dependencies, rebuild the native app. If you are using a bare iOS project, run:
```bash
cd ios && pod install
```
If you are using Expo, install versions compatible with your SDK and rebuild the app if needed.
## **๐ Quick Start**
```tsx
import * as React from "react";
import {
StyleSheet,
Text,
View,
type ListRenderItemInfo,
} from "react-native";
import {
SyncedTabsLayout,
TabFlatList,
type TabItem,
type TabPageProps,
type TabViewTopTabsProps,
} from "react-native-synced-tab-view";
type DemoItem = {
id: string;
title: string;
};
const POSTS_DATA: DemoItem[] = Array.from({ length: 12 }, (_, index) => ({
id: `post-${index + 1}`,
title: `Post ${index + 1}`,
}));
const SAVED_DATA: DemoItem[] = Array.from({ length: 12 }, (_, index) => ({
id: `saved-${index + 1}`,
title: `Saved ${index + 1}`,
}));
const keyExtractor = (item: DemoItem) => item.id;
const DemoCard = React.memo(({ item }: { item: DemoItem }) => (
{item.title}
));
type FeedTabProps = Pick & {
data: DemoItem[];
};
const FeedTab = React.memo(function FeedTab({
index,
width,
data,
}: FeedTabProps) {
const renderItem = React.useCallback(
({ item }: ListRenderItemInfo) => ,
[],
);
return (
);
});
export default function ExampleScreen() {
const tabs = React.useMemo(
() =>
[
{
key: "posts",
name: "Posts",
component: ({ index, width }: TabPageProps) => (
),
},
{
key: "saved",
name: "Saved",
component: ({ index, width }: TabPageProps) => (
),
},
] satisfies TabItem[],
[],
);
return (
Profile
Collapsible header content goes here.
}
tabs={tabs}
initialTabIndex={0}
topTabsProps={TOP_TABS_PROPS}
/>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: "#fff",
},
header: {
padding: 24,
backgroundColor: "#f3f4f6",
},
title: {
fontSize: 24,
fontWeight: "700",
color: "#111827",
marginBottom: 8,
},
subtitle: {
fontSize: 14,
color: "#4b5563",
},
listContent: {
padding: 16,
},
card: {
padding: 16,
borderRadius: 12,
backgroundColor: "#e5e7eb",
marginBottom: 12,
},
cardTitle: {
fontSize: 16,
fontWeight: "600",
color: "#111827",
},
tabText: {
fontSize: 14,
fontWeight: "600",
},
});
const TOP_TABS_PROPS = {
indicatorColor: "#111827",
indicatorHeight: 3,
tabTextStyle: styles.tabText,
} satisfies TabViewTopTabsProps;
```
## **โ๏ธ API Reference**
### **Exports**
| Export | Description |
| :---- | :---- |
| `SyncedTabsLayout` | High-level layout component that wires the provider, measured header, top tabs, and pager together. |
| `TabFlatList` | Synchronized `FlatList` wrapper for tab content. |
| `TabSectionList` | Synchronized `SectionList` wrapper for tab content. |
| `TabScrollView` | Synchronized `ScrollView` wrapper for tab content. |
| `createSyncedTabScrollComponent` | Factory for wrapping third-party scrollable components. |
### **SyncedTabsLayout Props**
| Prop | Type | Description | Default |
| :---- | :---- | :---- | :---- |
| `header` | `React.ReactNode` | Content rendered above the tabs and measured by the shared scroller. | **Required** |
| `tabs` | `TabItem[]` | Tab definitions shared between the tab bar and pager. | **Required** |
| `width` | `number` | Width of the tab bar and page area. | Screen width |
| `initialTabIndex` | `number` | Tab shown on first render. | `0` |
| `topTabsProps` | `TabViewTopTabsProps` | Props forwarded to the built-in top tabs component. | `{}` |
| `scrollerProps` | `TabViewScrollerProps` | Props forwarded to the horizontal pager scroller. | `{}` |
| `tabsProviderProps` | `object` | Shared scroll behavior options, including `resetPreviousScrollingY`. | `{ resetPreviousScrollingY: true }` |
| `scrollerContainerProps` | `object` | Props for the outer synchronized vertical scroller. | โ |
| `headerContainerProps` | `object` | Props for the measured header container. | โ |
### **TabItem Shape**
| Field | Type | Description |
| :---- | :---- | :---- |
| `key` | `string \| number` | Stable identity used for React keys and tab state when provided. |
| `id` | `string \| number` | Alternate stable identity if `key` is not used. |
| `name` | `string` | Label rendered in the top tabs. |
| `component` | `(props: TabPageProps) => React.ReactNode` | Function that renders the tab page. |
`TabPageProps` includes:
* `item`: the current `TabItem`
* `index`: the tab index
* `width`: the page width
* `isActive`: a Reanimated shared value indicating whether the tab is active
### **Synced Scroll Components**
| Component | Based On | Extra Props |
| :---- | :---- | :---- |
| `TabFlatList` | `FlatListProps` | `index: number`, `width?: number` |
| `TabSectionList` | `SectionListProps` | `index: number`, `width?: number` |
| `TabScrollView` | `ScrollViewProps` | `index: number`, `width?: number` |
`TabFlatList` and `TabSectionList` intentionally do not expose `windowSize`.
### **Common `topTabsProps` Options**
| Prop | Type | Description | Default |
| :---- | :---- | :---- | :---- |
| `tabItemStyle` | `StyleProp` | Style applied to each tab item wrapper. | โ |
| `tabTextStyle` | `StyleProp` | Style applied to tab labels. | โ |
| `indicatorColor` | `string` | Color of the active indicator. | `"white"` |
| `indicatorHeight` | `number` | Height of the indicator. | `4` |
| `indicatorWidth` | `number` | Width of the indicator. | `50` |
| `showIndicator` | `boolean` | Whether the indicator is visible. | `true` |
| `renderTabItem` | `(props: TopTabItemRenderProps) => React.ReactElement` | Custom tab item renderer. | โ |
| `renderIndicator` | `() => React.ReactElement` | Custom indicator renderer. | โ |
## **๐งช Custom Scroll Components**
If you want to sync a third-party list, wrap it with `createSyncedTabScrollComponent`:
```tsx
import { FlashList } from "@shopify/flash-list";
import { createSyncedTabScrollComponent } from "react-native-synced-tab-view";
const SyncedFlashList = createSyncedTabScrollComponent(FlashList);
```
The wrapped component still forwards refs to the underlying list instance, so imperative methods remain available.
## **๐ Why not wire this manually?**
Profile-style tab layouts usually require several moving parts at the same time: a measured header, a horizontal pager, synchronized vertical offsets, and custom tab visuals. Wiring all of that by hand often leads to duplicated `onScroll` logic, ref coordination, and edge cases when switching tabs.
`react-native-synced-tab-view` packages those behaviors behind a small API so each tab can focus on rendering content instead of managing scroll synchronization.
## **๐ฑ Example App**
The repository includes an Expo example app with these demo flows:
* Base synchronized tabs example
* Example with saved tab position
* Instagram-style profile layout
* TikTok-style profile layout
* FlashList integration example
* Legend List integration example
You can keep this section as-is or replace it with screenshots, GIFs, or hosted demo links later.
## **โ ๏ธ Known Issues**
* Tab scroll-position reset and restore behavior should currently be considered experimental. On Android, it can flicker and may not be stable across every list adapter.
* When using a `LegendList` adapter inside a tab together with position reset on tab switch (`resetPreviousScrollingY: true`), resetting the list can temporarily show a white background.
## **๐ Limitations**
* This package currently supports Android and iOS. Web support is not available yet.
* The top section does not currently support a horizontal `FlatList`.
* If you need horizontal list content there, use a horizontal `FlashList` or horizontal `LegendList` instead.
## **๐ก Recommendations**
* For the best performance with a vertical list and `tabsProviderProps={{ resetPreviousScrollingY: false }}`, prefer `LegendList`.
* If `resetPreviousScrollingY` is enabled (`true`, the default), prefer `FlashList`.
## **๐งช Local Development**
```bash
yarn install
yarn start
yarn example:ios
yarn example:android
yarn typecheck
yarn build
```
## **๐งฏ Troubleshooting**
* **Animations are not working**: Verify `react-native-reanimated` is installed and configured correctly in your app, then rebuild the native project.
* **Scroll sync feels inconsistent after tab changes**: Provide a stable `key` or `id` on every `TabItem`, especially if tab order can change.
* **You need a different list implementation**: Wrap it with `createSyncedTabScrollComponent` instead of syncing it manually.
* **You want the outer vertical scroll indicator visible**: Pass `scrollerContainerProps={{ showsVerticalScrollIndicator: true }}`.
## **๐ License**
MIT ยฉ Mohammed B.
## **โ Support**
If you find this project useful and would like to support its ongoing development, consider buying me a coffee! Your support helps keep the creativity brewing and allows me to continue improving and maintaining this project. Thank you! โ๐
