Skip to content

meinto/react-native-viewpager-carousel

Repository files navigation

React Native Viewpager Carousel

npm version dependencie status dev-dependency status npm npm travis build

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

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 should 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
pagingEnabled 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