React Native Viewpager Carousel

Contribution

Feel free to make a pull request. I'm happy about every contribution.

Examples

You can find example implementations for all use cases of this library in the repo react-native-viewpager-carousel-example-app. The example project is also linked as git submodule in this project.

Installation

yarn add react-native-viewpager-carousel

or

npm install --save react-native-viewpager-carousel

Preview

ViewPager

The <ViewPager /> is the base component of the library. Till now it acts like a simple view-carousel:

import { ViewPager } from 'react-native-viewpager-carousel'

class ExampleCarousel extends PureComponent {

    constructor() {
        this.data = [
            { title: 'title 1' },
            { title: 'title 2' },
            { title: 'title 3' },
        ]
    }
    
    _renderPage = ({data}) => {
        return ( <Text>{item.title}</Text> )
    }

    render() {
        return (
            <ViewPager
                data={this.data}
                renderPage={this._renderPage}
            />
        )
    }
}

API

| prop name | data type | default | functionality | | --------------------- | --------- | ------- | ------------- | | containerStyle | style | {} | the component is wrapped into a <View />. Styles to this <View /> can be assigned through this property | | contentContainerStyle | style | {} | posibility to set styles to the content container (the entire scrollable area) | | data | array | [] | a data array of objects | | dev | boolean | false | draws a black line around the pages and tabs for debugging | | lazyrender | boolean | false | lazyrender renders the active page only when its in the viewport | | lazyrenderThreshold | number | 1 | determines how many threshold left and right the current visible page sould be rendered if lazyrender={true} | | renderAsCarousel | boolean | true | renders the as endless carousel | | thresholdPages | number | 1 | number of pages left and right of the scrollable content (sneak preview) | | pageWidth | number | {{screen width of device}} | width of page | | initialPage | object | {} | key value pair of initial page: e. g. data=[{key:'page-a'}, {key:'page-b'}] & initialPage={{key:'page-b}} | | scrollEnabled | boolean | true | decleares wether the ViewPager sould be able to scroll by user or not | | firePageChangeIfPassedScreenCenter | boolean | false | toggle's if onPageChange sould already be called when the dragged page passed half of the screen | | pageingEnabled | boolean | true | | | experimentalMirroring | boolean | false | toggles the mirroring of the scrollposition of the threshold views - more information here | | showNativeScrollIndicator | boolean | false | native ScrollView indicator is disabled by default | | renderPage | function | () => {} | render callback for content page | | onPageChange | function | () => {} | callback when the page changes -> retuns the current pageNumber as first argument | | onScroll | function | () => {} | callback when the content area scrolls |

TabbedPager

In addition to the <ViewPager /> the <TabbedPager /> component provides an additional renderFunction for Tabs above the content view. The following pseudo-code shows the basic usage with an <Image /> as content and a <Text /> as tab.

import { TabbedPager } from 'react-native-viewpager-carousel'

class ExampleCarousel extends PureComponent {

    constructor() {
        this.data = [
            { title: 'title 1', url: 'http://...' },
            { title: 'title 2', url: 'http://...' },
            { title: 'title 3', url: 'http://...' },
        ]
    }
    
    _renderTab = ({data}) => {
        return ( <Text>{data.title}</Text> )
    }
    
    _renderPage = ({data}) => {
        return ( <Image source={{uri: data.url}} /> )
    }

    render() {
        return (
            <ViewPager
                data={this.data}
                renderTab={this._renderTab}
                renderPage={this._renderPage}
            />
        )
    }
}

API

| prop name | data type | default | functionality | | --------------------- | --------- | ------------- | ------------- | | data | array | [] | a data array of objects | | dev | boolean | false | draws a black line around the pages and tabs for debugging | | fullScreen | boolean | true | draws the in full screen mode (flex 1) | | lazyrender | boolean | false | lazyrender renders the active page only when its in the viewport | | lazyrenderThreshold | number | 1 | determines how many threshold left and right the current visible page sould be rendered if lazyrender={true} | | renderAsCarousel | boolean | true | renders the as endless carousel | | tabContainerPosition | string | 'top' | could be 'top' || 'bottom' - places the tab container on top of the viewpager or on the bottom side |
| scrollTabsEnabled | boolean | false | | | firePageChangeIfPassedScreenCenter | boolean | false | toggle's if onPageChange sould already be called when the dragged page passed half of the screen | | staticTabWidth | number | {{screen width of device / 2}} | | | initialPage | object | {} | key value pair of initial page: e. g. data=[{key:'page-a'}, {key:'page-b'}] & initialPage={{key:'page-b}} | | showTabIndicator | boolean | true | toggles the tab indicator | | tabIndicatorColor | string | 'transparent' | changes the color of the tab indicator | | tabIndicatorHeight | number | 2 | height of tab indicator | | tabsVisible | boolean | true | indicates if tabs should be visible or not | | DividerComponent | any | null | renders a given Component between the tabs and the content area | | renderPage | function | () => {} | render callback for content page | | renderTab | function | () => {} | render callback for the tab | | onPageChange | function | () => {} | callback when the page changes -> retuns the current pageNumber as first argument | | experimentalMirroring | boolean | false | toggles the mirroring of the scrollposition of the threshold views - more information here |