Installation

Install the package

Then add the required peer dependencies:

Choose compatible versions

These are the library's declared peer requirements. A minimum version does not mean that every newer combination works together.

Check the Reanimated compatibility table and Gesture Handler requirements when choosing React Native, Reanimated, and Worklets versions. This library targets the New Architecture.

Add the providers

Wrap your app in a gesture root and safe-area provider:

import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { ProfileScreen } from './ProfileScreen';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <ProfileScreen />
      </SafeAreaProvider>
    </GestureHandlerRootView>
  );
}

With Expo Router, wrap your root layout's Stack or Slot in GestureHandlerRootView. Router supplies safe-area context. Android modal content needs its own gesture root.

Configure Worklets

Expo's babel-preset-expo configures the Worklets plugin. For a bare React Native app, put the plugin last:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: ['react-native-worklets/plugin'],
};

Clear Metro's cache and rebuild after changing native dependencies. On iOS, install pods:

npx pod-install

Use an Expo development build when your Expo Go client does not include the required native versions.

Optional list adapters

Tabs.FlatList and Tabs.ScrollView need no extra list dependency. For other lists, install the adapter's peer:

npm install @legendapp/list
# Or, for FlashList:
npm install @shopify/flash-list

The /core entry avoids importing optional list adapters:

import { Tabs } from 'react-native-collapsible-fluid-tabs/core';
import { LegendList } from 'react-native-collapsible-fluid-tabs/legend-list';

Render a separately imported adapter inside Tabs.Tab. The main package entry exports all adapters; its TypeScript declarations may require both optional list packages when skipLibCheck is disabled. See list adapters.