PedroBern
React Native Collapsible Tab View
- Expo App
- Demo
- Features
- Installation
- Quick Start
- Guides
- API Reference
- Known Issues
- Alternative Libraries
- Contributing
🚀 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-viewThen, 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
HeaderComponentdoes not contain touchable components, set thepointerEventsprop to'none'. - If the
HeaderComponentdoes contain touchable components, set thepointerEventsprop 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 |
(data: { prevIndex: number index: number prevTabName: T tabName: T }) => void |
|Callback fired when the tab changes. It receives the previous and current index and tabnames. | |
pagerProps |
Omit<FlatListProps<number>, 'data' | 'keyExtractor' | 'renderItem' | 'horizontal' | 'pagingEnabled' | 'onScroll' | 'showsHorizontalScrollIndicator' | 'getItemLayout'> |
|Props passed to the pager. If you want for example to disable swiping, you can pass { scrollEnabled: false } |
|
renderHeader |
(props: TabBarProps<TabName>) => React.ReactElement | null |
| | |
renderTabBar |
(props: TabBarProps<TabName>) => React.ReactElement | null |
(props: TabBarProps<TabName>) => MaterialTabBar |
|
revealHeaderOnScroll |
boolean | undefined |
|Reveal header when scrolling down. Implements diffClamp. | |
snapThreshold |
number | null | undefined |
null |
Percentage of header height to define as the snap point. A number between 0 and 1, or null to disable snapping. |
tabBarHeight |
number | undefined |
|Is optional, but will optimize the first render. | |
width |
number | undefined |
|Custom width of the container. Defaults to the window width. |
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 |
number |
|
indexDecimal |
SharedValue<number> |
|
label |
string | ((props: TabItemProps<T>) => ReactNode) |
|
labelStyle |
StyleProp<AnimateStyle<TextStyle>> |
Style to apply to the tab item label |
name |
T |
|
onLayout |
(((event: LayoutChangeEvent) => void) & ((event: LayoutChangeEvent) => void)) | undefined |
Invoked on mount and layout changes with {nativeEvent: { layout: {x, y, width, height}}}. |
onPress |
(name: T) => void |
|
pressColor |
string | undefined |
|
pressOpacity |
number | undefined |
|
scrollEnabled |
boolean | undefined |
|
style |
StyleProp<ViewStyle> |
Either view styles or a function that receives a boolean reflecting whether the component is currently pressed and returns view styles. |
Known Issues
Android FlatList Pull to Refresh
Refer to this open issue. We utilize scrollTo to synchronize the unfocused tabs. While it is intended for use with ScrollView, it works well with FlatList, until the RefreshControl is added. Note that this issue occurs only on Android.
Workaround: Check out the Android Shared Pull To Refresh example in the expo app. You can implement a single pull-to-refresh for the Tabs.Container.
iOS FlatList StickyHeaderIndices and iOS SectionList StickySectionHeadersEnabled
When using the stickyHeaderIndices prop on a FlatList or stickySectionHeadersEnabled on a SectionList, the sticky elements do not scroll up as the header collapses. This issue is specific to iOS.
See #136.
ref.setIndex
This is not an issue per se, but it's essential to be aware of it. When using containerRef.current.setIndex(i), if you set it to the current index, the screen will scroll to the top. You can prevent this behavior as follows:
const index = pageRef.current?.getCurrentIndex()
if (index !== nextIndex) {
pageRef.current?.setIndex(nextIndex)
}Alternative Libraries
If you do not require a full-featured tab view, consider another option: a simple segmented control / material tab bar without swiping or snapping, using only the React Native Animated API.
Contributing and running the Example
While developing, you can run the example app to test your changes.
First run yarn in root:
yarnThen prepare the example:
cd example
yarnThen run the example:
yarn iosPlease follow the angular commit message format.
Make sure your code passes TypeScript and ESLint. Run the following to verify:
yarn typescript
yarn lintTo fix formatting errors, run the following:
yarn lint -- --fixDocumentation changes
Edit the README_TEMPLATE, or update the docstrings inside the src folder, and run:
yarn docs