The best Pagination component for React Native.
React Native Pagination
Roadmap
see: ROADMAP.md
Horizontal
To try these out yourself its prudy easy, Just open
examples/ios/*.xcodeproj
in Xcode, then pressCmd + R
; you may editexamples/index.ios.js
for switch cases.
Vertical
Getting Started
- React Native Pagination
Installation
- Install
react-native
first
$ npm i react-native -g
$ yarn add react-native-pagination
$ cd ReactNativePaginationExample
$ yarn install #(or with npm "npm i react-native-pagination —save")
$ react-native run-ios
- Initialization of a react-native project
$ react-native init myReactNativePaginationExample
$ cd myReactNativePaginationExample
$ yarn install #(or with npm "npm i && npm i react-native-pagination —save")
$ yarn add react-native-pagination
$ react-native link
$ react-native run-ios
Example
or clone the repo and play with the example project
$ git clone https://github.com/garrettmac/react-native-pagination
$ cd react-native-pagination/ReactNativePaginationExample
$ yarn install
$ react-native link
$ react-native run-ios
one liner
git clone https://github.com/garrettmac/react-native-pagination && cd react-native-pagination/ReactNativePaginationExample && yarn install && react-native link && react-native run-ios
Quick start with ReactNativePaginationExample.
Development
in your project
$ yarn add react-native-pagination
$ react-native link #this makes sure react-native-vector-icons load correctly
$ react-native run-ios
Basic Usage
- In your
myApp/index.ios.js
, use:
import React, { Component } from 'react';
import {AppRegistry,StyleSheet,View,FlatList,} from 'react-native';
import ContactItem from './Pages/widgets/ContactItem'; // https://github.com/garrettmac/react-native-pagination/blob/master/ReactNativePaginationExample/Pages/widgets/ContactItem.js
import faker from 'faker';//assuming you have this.
import _ from 'lodash';
import Pagination,{Icon,Dot} from 'react-native-pagination';//{Icon,Dot} also available
//lets use faker to create mock data
let MockPersonList = new _.times(35,(i)=>{
return {
id:i,
index:i,
name:faker.name.findName(),
avatar:faker.internet.avatar(),
group:_.sample(["Family","Friend","Acquaintance","Other"]),
email:faker.internet.email(),
}
})
export default class ReactNativePaginationExample extends Component {
constructor(props){
super(props);
this.state = {
items: MockPersonList,
};
}
//create each list item
_renderItem = ({item}) => {
return (<ContactItem index={item.id}
onPressItem={this.onPressItem}
name={item.name}
avatar={item.avatar}
description={item.email}
tag={item.group}
createTagColor
/>)
};
//pressed an item
onPressItem = (item) => console.log("onPressItem:item ",item);
//map to some od. We use the "id" attribute of each item in our list created in our MockPersonList
_keyExtractor = (item, index) => item.id.toString();
// REQUIRED for ReactNativePagination to work correctly
onViewableItemsChanged = ({ viewableItems, changed }) =>this.setState({viewableItems})
render() {
return (
<View style={[s.container]}>
<FlatList
data={this.state.items}
ref={r=>this.refs=r}//create refrence point to enable scrolling
keyExtractor={this._keyExtractor}//map your keys to whatever unique ids the have (mine is a "id" prop)
renderItem={this._renderItem}//render each item
onViewableItemsChanged={this.onViewableItemsChanged}//need this
/>
<Pagination
// dotThemeLight //<--use with backgroundColor:"grey"
listRef={this.refs}//to allow React Native Pagination to scroll to item when clicked (so add "ref={r=>this.refs=r}" to your list)
paginationVisibleItems={this.state.viewableItems}//needs to track what the user sees
paginationItems={this.state.items}//pass the same list as data
paginationItemPadSize={3} //num of items to pad above and below your visable items
/>
</View>
)
}
};
const s = StyleSheet.create({
container: {
flex: 1,
// backgroundColor:"grey",//<-- use with "dotThemeLight"
},
});
AppRegistry.registerComponent('ReactNativePaginationExample', () => App);
Currently only supported for FlatList's
Properties
All properties took text editors auto completion into consideration and follow the basic structure
[prefix
][body
][suffix
] where
[component name
][component attribute
][continued component attribute / component change
] to provide users with the full list of options when working with prefix
's without having to revisit the official docs.
Most Common Component Prefix Options:dot
, startDot
,endDot
Most Common Component Body Options:Icon
, Font
,Style
,Color
Most Common Component Suffix Options:Hide
, Size
,IconFamily
,or NotActive
,Active
Empty
Resulting props like
dotIconHide
,startDotIconHide
, or startFontSize
,endDotStyle
ect.
Basic
Basic Props
Prop | Default | Type | Description |
---|---|---|---|
paginationItems | [] |
array |
an array pagination Items |
paginationVisibleItems | [] |
array |
an array pagination visible items obtained by using React Native List Components onViewableItemsChanged callback function (see example) |
dotThemeLight | false |
bool |
if you pass in the dotThemeLight prop (setting it to true ) the pagination dots swaps to a a light theme. By default they are dark. |
horizontal | false |
bool |
use to alternate between horizontal and vertical (just like you do with your list component) |
dotAnimation | LayoutAnimation.Presets.easeInEaseOut |
Animation |
dot Animation triggered when navigating |
paginationStyle | {} |
style |
pagination Styles |
pagingEnabled | false |
bool |
Enable Paging. This is a prop that is also used in React Native List Components (like FlatList ) that gives you that paging effect that stops the scroll on every new page. |
hideEmptyDots | false |
bool |
Hide Empty Dots Icons |
paginationItemPadSize | 3 |
number |
pagination Item Pad Size |
Basic Styles
Prop | Default | Type | Description |
---|---|---|---|
paginationStyle when horizontal |
{height, alignItems:"center" , justifyContent: 'space-between', position:"absolute", top:0, margin:0, bottom:0, right:0, bottom:0, padding:0, flex:1, } |
style |
default when horizontal |
paginationStyle when not horizontal |
{width, alignItems:"center", justifyContent: 'space-between', position:"absolute", margin:0, bottom:10, left:0, right:0, padding:0, flex:1,} |
style |
default when not horizontal |
textStyle | {} |
style object |
global style object. Tread lightly it may overlay if you plan to use my default Light/Dark Themes |
dotStyle | {} |
style object |
addition style to use for pagination dots |
startDotStyle | {} |
style object |
addition style to use for start dots |
endDotStyle` | {} |
style object |
addition style to use for end dots |
this uses react-native-vector-icons [checkout here] (https://github.com/oblador/react-native-vector-icons)
Start/End Dots
Start/End Dot Basic Props
Prop | Default | Type | Description |
---|---|---|---|
startDotIconName (when horizontal ) |
”chevron-left” |
icon name |
Icon shown for dot at start of list |
startDotIconName (when vertical ) |
”chevron-up” |
icon name |
Icon shown for dot at start of list |
endDotIconName (when horizontal ) |
”chevron-right” |
icon name |
Icon shown for dot at start of list |
endDotIconName (when vertical ) |
”chevron-down” |
icon name |
Icon shown for dot at start of list |
startDotIconSize |
15 |
number |
end icon dot size |
endDotIconSize |
15 |
number |
end icon dot size |
startDotIconFamily / endDotIconFamily |
MaterialCommunityIcons |
string of font family name |
Font Family for Icon. options: Entypo , EvilIcons , FontAwesome , Foundation , Ionicons , MaterialIcons , MaterialCommunityIcons , Octicons , Zocial , SimpleLineIcons (available in react-native-vector-icons package) |
Start/End Dot Text
Prop | Default | Type | Description |
---|---|---|---|
startDotFontSize | 11 |
number |
start Dot Font Size |
endDotFontSize | 11 |
number |
end Dot Font Size |
Pagination Dots
These are the list of dots that represent each item in your paginationItems
Pagination Dots Basic Props
Prop | Default | Type | Description |
---|---|---|---|
dotIconFamily |
”MaterialCommunityIcons” |
string of font family name |
Font Family for Icon. options: Entypo , EvilIcons , FontAwesome , Foundation , Ionicons , MaterialIcons , MaterialCommunityIcons , Octicons , Zocial , SimpleLineIcons (available in react-native-vector-icons package) |
dotIconNameEmpty | ”close” |
icon name |
Icon Shown when pagination dot is Empty |
dotIconNameActive | ”checkbox-blank-circle” |
icon name |
Icon Shown when pagination dot is Active |
dotIconNameNotActive | ”checkbox-blank-circle-outline” |
icon name |
Icon Shown when pagination dot is Not Active |
dotIconSizeActive | 15 |
number |
size of pagination icon when active |
dotIconSizeNotActive | 10 |
number |
size of pagination iconwhen vertical |
dotIconColorNotActive | ”rgba(0,0,0,.5)” |
color |
dot Icon Font Size when on page but Not Active |
dotIconColorActive | ”rgba(0,0,0,.3)” |
color |
dot Icon Font Size when on page but Not Active |
dotIconColorEmpty | ”rgba(0,0,0,.2)” |
color |
dot Icon Font Size when on page but Not Active |
when using dotThemeLight
Prop | Default | Type | Description |
---|---|---|---|
dotIconColorNotActive | ”rgba(255,255,255,.4)” |
color |
dot Icon Font Size when on page but Not Active |
dotIconColorActive | ”rgba(255,255,255,.5)” |
color |
dot Icon Font Size when on page but Not Active |
dotIconColorEmpty | ”rgba(255,255,255,.2)” |
color |
dot Icon Font Size when on page but Not Active |
Dot Text
by default it displays index+1
, if you'd like display text add the paginationDotText
property to each one of your items before passing it into the Pagination
Component. Example:
paginationItems=paginationItems.map(o=>{
o.paginationDotText=o.name;
return o
})
Pagination Dots
Prop | Default | Type | Description |
---|---|---|---|
dotFontSizeActive | 11 | number |
dot Text Font Size when Active on page |
dotFontSizeEmpty | 11 | number |
dot Text Font Size when empty on page |
dotFontSizeNotActive | 9 | number |
dot Text Font Size when on page but Not Active |
dotTextColorNotActive | ”rgba(0,0,0,.5)” |
color |
dot Text Color when Not Active |
dotTextColorActive | ”rgba(0,0,0,.3)” |
color |
dot Text Color when Active |
dotTextColorEmpty | ”rgba(0,0,0,.2)” |
color |
dot Text Color when Empty |
when using dotThemeLight
Prop | Default | Type | Description |
---|---|---|---|
dotTextColorNotActive | ”rgba(255,255,255,.4)” |
color |
dot Text Color when Not Active |
dotTextColorActive | ”rgba(255,255,255,.5)” |
color |
dot Text Color when Active |
dotTextColorEmpty | ”rgba(255,255,255,.2)” |
color |
dot Text Color when Empty |
Advanced Positioning
Prop | Default | Type | Description |
---|---|---|---|
dotSwapAxis (all pagination dots)/ startDotSwapAxis / endDotSwapAxis |
false | bool |
keeps the lists in the correct position (horizontal or vertical) by swaps how dots display |
dotPositionSwap (all pagination dots)/startDotPositionSwap / endDotPositionSwap |
false | bool |
Swaps the dots flexDirection default style property. |
Wanna move anything to the left, right, top, or bottom of something? Then use dotSwapAxis
in combination until you find the right mix startDotPositionSwap
.
Visibility
Prop | Default | Type | Description |
---|---|---|---|
dotIconHide / startDotIconHide / endDotIconHide |
false | bool |
hide the dots icon |
dotIconHide / startDotIconHide / endDotIconHide |
false | bool |
hide the dots icon |
dotTextHide / startDotTextHide / endDotTextHide |
false | bool |
hide the dots text |
dotEmptyHide |
false | bool |
hide the dots text |
Methods
Method Name | Description |
---|---|
dotOnPress / startDotOnPress /endDotOnPress |
by default it will scroll to the pagination dot pressed (disableDotOnPressNavigation to turn off), if you'd like a callback you can pass in the dotOnPress callback function |
Other
Prop | Default | Type | Description |
---|---|---|---|
debugMode |
false | bool |
show console log results of list items |
Components
Components | Required Params | Other Params | Description |
---|---|---|---|
Pagination |
paginationItems ,paginationVisibleItems |
see above | main pagination Component |
Dot |
`` | see above | Pagination Dot Component |
Icon |
name |
iconFamily ,size ,color |
same as 'react-native-vector-icons' but with a iconFamily option |
Issues
Feel free to contact me or create an issue