Animated Pagination For React Native's ListView, FlatList, and SectionList
Switch branches/tags
Nothing to show
Clone or download

README.md

react-native-pagination

The best Pagination component for React Native.

npm version npm version npm version npm version PR Stats Issue Stats Join the chat

React Native Pagination

Roadmap

see: ROADMAP.md

Horizontal

To try these out yourself its prudy easy, Just open examples/ios/*.xcodeproj in Xcode, then press Cmd + R; you may edit examples/index.ios.js for switch cases.

react-native-pagination horizontal robot react-native-pagination horizontal

Vertical

react-native-pagination vertical react-native-pagination lighttheme

Getting Started

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