Home

Awesome

react-native-image-header-scroll-view

badge

A ScrollView-like component that:

Breaking changes

Version 1.0.0

/!\ Warning /!\ The lib has been upgraded to match with new React and React Native standards (hooks, deprecated methods, etc...). The version 1.0.0 may contain some bugs or regressions. Ping me in issues if you notice a bad behaviour of the upgraded lib on your project. I advice you to update the lib in a separate commit to roll back if necessary. However the lib should work for most of cases, so don't be scared to update the lib. It is a first step to improve the lib in the future, so please be understanding 😇

Installation

$ npm install react-native-image-header-scroll-view --save

Demo

react-native-image-header-scroll-view demo android|react-native-image-header-scroll-view demo ios

You can find this example code here : https://github.com/bamlab/react-native-image-header-scroll-view-example/blob/master/src/Pages/TvShow.js

Basic Usage

import { ImageHeaderScrollView, TriggeringView } from 'react-native-image-header-scroll-view';

// Inside of a component's render() method:
render() {
  return (
    <ImageHeaderScrollView
      maxHeight={200}
      minHeight={MIN_HEIGHT}
      headerImage={require("../../assets/NZ.jpg")}
      renderForeground={() => (
        <View style={{ height: 150, justifyContent: "center", alignItems: "center" }} >
          <TouchableOpacity onPress={() => console.log("tap!!")}>
            <Text style={{ backgroundColor: "transparent" }}>Tap Me!</Text>
          </TouchableOpacity>
        </View>
      )}
    >
      <View style={{ height: 1000 }}>
        <TriggeringView onHide={() => console.log("text hidden")}>
          <Text>Scroll Me!</Text>
        </TriggeringView>
      </View>
    </ImageHeaderScrollView>
  );
}

Result :

Basic Usage

You can find examples in a dedicated repository.

Usage (API)

All of the properties of ScrollView are supported. Please refer to the ScrollView documentation for more detail.

The ImageHeaderScrollView handle also the following props. None is required :

Header

PropertyTypeDefault DescriptionExample
renderHeaderfunction Empty viewFunction which return the component to use as header. It can return background image for example.example
headerImageImage source Props (object or number) undefinedShortcut for renderHeader={() => <Image source={this.props.headerImage} style={{ height: this.props.maxHeight, width: Dimensions.get('window').width }} />}example
maxHeightnumber125Max height for the headerexample
minHeightnumber80Min height for the header (in navbar mode)example
minOverlayOpacitynumber0Opacity of a black overlay on the header before any scrollexample
maxOverlayOpacitynumber0.3Opacity of a black overlay on the header when in navbar modeexample
overlayColorstringblackColor of the overlay on the headerexample
useNativeDriverbooleanfalseUse native driver for the animation for performance improvement. A few props are unsupported at the moment if useNativeDriver=true (onScroll, ScrollComponent, renderTouchableFixedForeground)-
headerContainerStyleObjectundefinedOptional styles to be passed to the container of the header component
disableHeaderGrowbooleanundefinedDisable to grow effect on the header

Foreground

PropertyTypeDefault DescriptionExample
renderForegroundfunctionEmpty viewFunction which return the component to use at foreground. The component is render in front of the header and scroll with the ScrollView. It can return a title for example.example
renderFixedForegroundfunctionEmpty viewFunction which return the component to use as fixed foreground. The component is displayed with the header but not affected by the overlay.example
foregroundExtrapolatestringclampOptional prop that allows override extrapolate mode for foreground. Use null to allow extrapolation, which is usefull for using foreground as bottom title-
foregroundParallaxRationumber1Ration for parallax effect of foreground when scrolling. If 2, the header goes up two times faster than the scrollexample
fadeOutForegroundboolfalseIf set, add a fade out effect on the foreground when scroll upexample
renderTouchableFixedForegroundfunctionEmpty viewSame as renderFixedForeground but allow to use touchable in it. Can cause performances issues on Androidexample
fixedForegroundContainerStylesObjectundefinedOptional styles to be passed to the container of the fixed foreground component

Mixed

PropertyTypeDefault DescriptionExample
ScrollViewComponentComponent ScrollViewThe component to be used for scrolling. Can be any component with an onScroll props (ie. ListView, FlatList, SectionList or ScrollView)example
scrollViewBackgroundColorstring whiteBackground color of the scrollView contentexample

TriggeringView

The module also export a TriggeringView component. It is a spy View you put on the page that will can call various callback during the scroll. It accept callback called when it disappear or appear at the top of the ImageHeaderScrollView. You can see an exemple in the dedicated repository.

All of the properties of View are supported.

PropertyTypeDescription
onBeginHiddenfunction Called when the component start to be hidden at the top of the scroll view.
onHidefunction Called when the component is not displayed any more after scroll up
onBeginDisplayedfunction Called when the component begin to be displayed again after scroll down
onDisplayfunction Called when the component finished to be displayed again.
onTouchTopfunction Called when the Top of the component touch the Top of the ScrollView. (onDisplay + onBeginHidden)
onTouchBottomfunction Called when the Bottom of the component touch the Top of the ScrollView. (onHide + onBeginDisplayed)

FAQ

How to remove the black image overlay

Just set the maxOverlayOpacity to 0.

<ImageHeaderScrollView
  minOverlayOpacity={0}
  maxOverlayOpacity={0}
  {/* ... */}
/>

How to remove the image zomming on scroll down

You have two solutions :

  1. You can use the disableHeaderGrow props. It will keep the ios elastic scroll effect.
  2. You can also use the bounces={false} props from the scroll view.

Results :

disableHeaderGrowbounces={false}
react-native-image-header-scroll-view demo disableHeaderGrowreact-native-image-header-scroll-view demo bounces

Contributing

All contributions are welcomed, that might be either adding new features, doing some refaco of the exisiting code or fixing bugs.

How to contribute

  1. Fork the project & clone locally. Follow the initial setup here.
  2. Create a branch, naming it either a feature or bug: git checkout -b feature/that-new-feature or bug/fixing-that-bug
  3. Code and commit your changes. Write a good commit message. Best would be to use git commitizen
  4. Test your changes in the example
  1. Push to the branch: git push origin feature/that-new-feature
  2. Create a pull request for your branch 🎉

Other open-source modules by the folks at BAM