react-native-pagination

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 press Cmd + R; you may edit examples/index.ios.js for switch cases.

Vertical

Getting Started

• React Native Pagination
  • ROADMAP.md
  • Show Cases
    • Horizontal
    • Vertical
  • Getting Started
  • Installation
    • Example
    • Development
  • Basic Usage
  • Properties
    • Basic
      • Basic Props
      • Basic Styles
    • Start/End Dots
      • Start/End Dot Basic Props
      • Start/End Dot Text
    • Pagination Dots
      • Pagination Dots Basic Props
      • Dot Text
      • Pagination Dots
    • Advanced Positioning
    • Visibility
    • Methods
    • Other
  • Components
  • Issues

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.bind(this)}
        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;

  // 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.bind(this)}//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