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