boundless-pagination

Pagination

Pagination is implemented as an encapsulated view system, accepting an array of items as input.

Component Instance Methods

When using Pagination in your project, you may call the following methods on a rendered instance of the component. Use refs to get the instance.

• currentPage() returns the one-indexed page number currently in view

• jumpToIndex(index: number) renders the page that contains the zero-indexed item

Installation

npm i boundless-pagination --save

Then use it like:

/** @jsx createElement */
 
/* eslint no-console:0 */
 
import { createElement, PureComponent } from 'react';
import Pagination from 'boundless-pagination';
 
export default class PaginationDemo extends PureComponent {
    state = {
        items: require('./fixture.json'),
        identifier: 'rolodex1000',
    }
 
    itemToJSX = (data) => (
        <div
            onFocus={() => console.log('focused id: ' + data.id)}
            onKeyDown={(e) => console.log('pressed ' + e.key + ' on id: ' + data.id)}>
            <div className='card-left'>
                <strong>{data.first_name} {data.last_name}</strong><br/>
                <em>{data.job_title}</em>
            </div>
            <div className='card-right'>
                {data.address1}<br/>
                {data.city}, {data.country}<br/>
                <strong>p:</strong> {data.phone}<br/>
                <strong>e:</strong> {data.email}
            </div>
        </div>
    )
 
    handleItemRequest = (index) => {
        // this might be async if row must be retrieved remotely
 
        if (index >= 10) {
            return new Promise((resolve) => {
                window.setTimeout((setIndex) => {
                    resolve(this.state.items[setIndex]);
                }, 2000, index);
            });
        }
 
        return this.state.items[index];
    }
 
    render() {
        return (
            <Pagination
                className='demo-pagination'
                customControlContent='Your custom content'
                getItem={this.handleItemRequest}
                identifier={this.state.identifier}
                itemToJSXConverter={this.itemToJSX}
                jumpToFirstPageControlContent='⇤'
                jumpToLastPageControlContent='⇥'
                jumpToNextPageControlContent='→'
                jumpToPreviousPageControlContent='←'
                numItemsPerPage={5}
                showPaginationState={true}
                totalItems={this.state.items.length} />
        );
    }
}

Pagination can also just be directly used from the main Boundless library. This is recommended when you're getting started to avoid maintaining the package versions of several components:

npm i boundless --save

the ES6 import statement then becomes like:

import { Pagination } from 'boundless';

Props

Note: only top-level props are in the README, for the full list check out the website.

Required Props

• getItem · called with a desired item index when that item comes into view; accepts a Promise if you need to fetch the row asynchronously

  Expects	Default Value
  function	() => {}

• identifier · a unique name for the data source being consumed; pass a different name to cause the view to fully reset and pull fresh data

  Expects	Default Value
  string	uuid()

• totalItems · the total number of items to be displayed in the view

  Expects	Default Value
  number	null

Optional Props

• * · any React-supported attribute

  Expects	Default Value
  any	n/a

• after · arbitrary content to be rendered after the items in the DOM

  Expects	Default Value
  any renderable	null

• before · arbitrary content to be rendered before the items in the DOM

  Expects	Default Value
  any renderable	null

• controlWrapperProps

  Expects	Default Value
  object	{}

• customControlContent · allows for arbitrary content to be rendered into the control area

  Expects	Default Value
  any renderable	null

• hidePagerIfNotNeeded · does not render the paging controls if the number of items supplied to the view is less-than-or-equal-to the number of items to show per page via props.numItemsPerPage

  Expects	Default Value
  bool	false

• initialPage · the (one-indexed) number of the page that should be initially displayed; must be a positive integer less than or equal to the total number of pages

  Expects	Default Value
  custom	1

• itemLoadingContent · allows for arbitrary content to be rendered into pagination items as they're loading if the backing data is a Promise

  Expects	Default Value
  any renderable	undefined

• itemToJSXConverter · an function to specify how an item should be converted to JSX, if it is not already renderable by React

   
  const getItem = () => ({id: 1234, text: 'foo'});
  const objToJSX = ({id, text}) => <div data-id={id}>{text}</div>;
   
  <Pagination
      getItem={getItem}
      identifer='foo'
      itemToJSXConverter={objToJSX}
      totalItems={1} />

  Expects	Default Value
  function	(x) => x

• itemWrapperProps

  Expects	Default Value
  object	{}

• jumpToFirstPageControlContent · content to be displayed inside of the "First page" control button

  Expects	Default Value
  any renderable	'⇤'

• jumpToLastPageControlContent · content to be displayed inside of the "Last page" control button

  Expects	Default Value
  any renderable	'⇥'

• jumpToNextPageControlContent · content to be displayed inside of the "Next page" control button

  Expects	Default Value
  any renderable	'→'

• jumpToPreviousPageControlContent · content to be displayed inside of the "Previous page" control button

  Expects	Default Value
  any renderable	'←'

• numItemsPerPage · the maximum number of items to be displayed on each page; must be greater than zero

  Expects	Default Value
  custom	10

• numPageToggles · the maximum number of pages to be displayed in the control bar at one time

  Expects	Default Value
  number	5

• position · determines whether the pagination controls are displayed above, below, or both above and below the content

  Expects	Default Value
  Pagination.position.ABOVE or Pagination.position.BELOW or Pagination.position.BOTH	Pagination.position.ABOVE

• showJumpToFirstPageControl · whether the "first page" control button should be displayed

  Expects	Default Value
  bool	true

• showJumpToLastPageControl · whether the "last page" control button should be displayed

  Expects	Default Value
  bool	true

• showJumpToNextPageControl · whether the "next page" control button should be displayed

  Expects	Default Value
  bool	true

• showJumpToPreviousPageControl · whether the "previous page" control button should be displayed

  Expects	Default Value
  bool	true

• showPaginationState · renders an element called .b-pagination-control-state that contains the current state of the pagination like "1 of 10"; alternatively, this prop also accepts a function that it will call with the currentPage and totalPages for you to format:

  showPaginatedState={
      (currentPage, totalPages) => (
          <div className='foo'>
              You're on page {currentPage} of {totalPages} pages!
          </div>
      )
  }

  Expects	Default Value
  bool or function	true

Reference Styles

Stylus

You can see what variables are available to override in variables.styl.

// Redefine any variables as desired, e.g:
color-accent = royalblue
 
// Bring in the component styles; they will be autoconfigured based on the above
@require "node_modules/boundless-pagination/style"

CSS

If desired, a precompiled plain CSS stylesheet is available for customization at /build/style.css, based on Boundless's default variables.