React Native Collapsible Tab View

[![Build Status][build-badge]][build] [![Version][version-badge]][package] [![MIT License][license-badge]][license] [![Runs with Expo][expo-badge]][expo]

• Expo App
• Demo
• Features
• Installation
• Quick Start
• Guides
  • Scroll on Header
• API Reference
  • Core
    • Tabs.Container
    • Tabs.Lazy
    • Tabs.FlatList
    • Tabs.FlashList
    • Tabs.MasonryFlashList
    • Tabs.SectionList
    • Tabs.ScrollView
    • Ref
  • Hooks
    • useCollapsibleStyle
    • useAnimatedTabIndex
    • useFocusedTab
    • useHeaderMeasurements
  • Default Tab Bar
    • MaterialTabBar
    • MaterialTabItem
• Known Issues
  • Android FlatList Pull to Refresh
  • iOS FlatList StickyHeaderIndices
  • ref.setIndex
• Alternative Libraries
• Contributing
  • Documentation Changes

🚀 Version 6 released with Reanimated v3 support

React Native Collapsible Tab View is a versatile library for creating collapsible tab views using Reanimated.

• Explore the examples for the source code of the Expo app.

Credits

The react-native-tab-view example app was used as a template for the demos.

Demo

Default	Snap	revealHeaderOnScroll	revealHeaderOnScroll + Snap

Features

• UI thread animations and interactions
• High customizability
• Full TypeScript support
• Lazy loading with fade-in animation
• DiffClamp header
• Interpolated header
• Scroll snap (with interpolated header)
• Animated snap (with diffClamp header)
• Scrollable tabs, inspired by the react-native-tab-view tab bar

Installation

To install the library, open a terminal in your project's root directory and run:

yarn add react-native-collapsible-tab-view react-native-pager-view

Then, add Reanimated, follow the official installation guide.

Quick Start

import React from 'react'
import { View, StyleSheet, ListRenderItem } from 'react-native'
import { Tabs } from 'react-native-collapsible-tab-view'

const HEADER_HEIGHT = 250

const DATA = [0, 1, 2, 3, 4]
const identity = (v: unknown): string => v + ''

const Header = () => {
  return <View style={styles.header} />
}

const Example: React.FC = () => {
  const renderItem: ListRenderItem<number> = React.useCallback(({ index }) => {
    return (
      <View style={[styles.box, index % 2 === 0 ? styles.boxB : styles.boxA]} />
    )
  }, [])

  return (
    <Tabs.Container
      renderHeader={Header}
      headerHeight={HEADER_HEIGHT} // optional
    >
      <Tabs.Tab name="A">
        <Tabs.FlatList
          data={DATA}
          renderItem={renderItem}
          keyExtractor={identity}
        />
      </Tabs.Tab>
      <Tabs.Tab name="B">
        <Tabs.ScrollView>
          <View style={[styles.box, styles.boxA]} />
          <View style={[styles.box, styles.boxB]} />
        </Tabs.ScrollView>
      </Tabs.Tab>
    </Tabs.Container>
  )
}

const styles = StyleSheet.create({
  box: {
    height: 250,
    width: '100%',
  },
  boxA: {
    backgroundColor: 'white',
  },
  boxB: {
    backgroundColor: '#D8D8D8',
  },
  header: {
    height: HEADER_HEIGHT,
    width: '100%',
    backgroundColor: '#2196f3',
  },
})

export default Example

Guides

Scrolling on the Header

To enable scrolling from the header, follow these steps:

• If the HeaderComponent does not contain touchable components, set the pointerEvents prop to 'none'.
• If the HeaderComponent does contain touchable components, set the pointerEvents prop to 'box-none' to ensure they function properly.

Note: If any child component within the HeaderComponent should not respond to touches, such as an <Image /> element, set its pointerEvents prop to 'none'. Otherwise, it may unintentionally become the target of a touch gesture on iOS devices and prevent scrolling.

API Reference

Core

Tabs.Container

Basic usage looks like this:

import { Tabs } from 'react-native-collapsible-tab-view'

const Example = () => {
   return (
     <Tabs.Container renderHeader={MyHeader}>
       <Tabs.Tab name="A">
         <ScreenA />
       </Tabs.Tab>
       <Tabs.Tab name="B">
         <ScreenB />
       </Tabs.Tab>
     </Tabs.Container>
   )
}

Props

name	type	default	description
allowHeaderOverscroll	boolean | undefined	false	Whether the header moves down during overscrolling (for example on pull-to-refresh on iOS) or sticks to the top
cancelLazyFadeIn	boolean | undefined
cancelTranslation	boolean | undefined
containerStyle	StyleProp<ViewStyle>
headerContainerStyle	StyleProp<AnimateStyle<ViewStyle>>
headerHeight	number | undefined		Is optional, but will optimize the first render.
initialTabName	string | undefined
lazy	boolean | undefined		If lazy, will mount the screens only when the tab is visited. There is a default fade in transition.
minHeaderHeight	number | undefined		Header minimum height when collapsed
onIndexChange	((index: number) => void) | undefined		Callback fired when the index changes. It receives the current index.
onTabChange

Tabs.Tab

Wrap your screens with Tabs.Tab. Basic usage looks like this:

<Tabs.Container ...>
  <Tabs.Tab name="A" label="First Tab">
   <ScreenA />
  </Tabs.Tab>
  <Tabs.Tab name="B">
   <ScreenA />
  </Tabs.Tab>
</Tabs.Container>

Props

name	type
label	string | ((props: TabItemProps<T>) => ReactNode) | undefined
name	T

Tabs.Lazy

Typically used internally, but if you want to mix lazy and regular screens you can wrap the lazy ones with this component.

Props

name	type
cancelLazyFadeIn	boolean | undefined
startMounted	boolean | undefined

Tabs.FlatList

Use like a regular FlatList.

Tabs.FlashList

Use like a regular FlashList.

Tabs.MasonryFlashList

Use like a regular MasonryFlashList.

Tabs.ScrollView

Use like a regular ScrollView.

Tabs.SectionList

Use like a regular SectionList.

Ref

You can pass a ref to Tabs.Container.

const ref = React.useRef()
<Tabs.Container ref={ref}>

method	type
jumpToTab	(name: T) => boolean
setIndex	(index: number) => boolean
getFocusedTab	() => T
getCurrentIndex	() => number

Hooks

useCollapsibleStyle

This hook provides access to key styles for the collapsible tab view. It can be used to obtain the progressViewOffset and pass it to the RefreshControl of the scroll view.

const {
  contentContainerStyle,
  progressViewOffset,
  style,
} = useCollapsibleStyle()

Values

name	type
contentContainerStyle	{ minHeight: number; paddingTop: number; }
progressViewOffset	number
style	{ width: number; }

useAnimatedTabIndex

This hook returns an animated value representing the current tab index. As the tab view can be in between panes while swiping, this value is a floating-point number.

const tabIndex = useAnimatedTabIndex()

useFocusedTab

This hook returns the name of the currently focused tab.

const focusedTab = useFocusedTab()

useHeaderMeasurements

This hook returns the top distance and the header height. For an example of how to use this, check out the animated header example in the example folder.

const { top, height } = useHeaderMeasurements()

useCurrentTabScrollY

This hook returns the vertical scroll position of the current tab as an Animated SharedValue.

Since this library requires handling the onScroll event for its functionality, this is the only way to react to changes in the scroll position of the underlying scrollable component.

const scrollY = useCurrentTabScrollY()

Default Tab Bar

MaterialTabItem

Any additional props are passed to the pressable component.

Props

name	type	description
activeColor	string | undefined	Color applied to the label when active
inactiveColor	string | undefined	Color applied to the label when inactive
inactiveOpacity	number | undefined
index