Napoleon's Pixelated Mugshot

    boundless-pagination

    1.1.0 • Public • Published

    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.

    Install

    npm i boundless-pagination

    DownloadsWeekly Downloads

    13

    Version

    1.1.0

    License

    MIT

    Last publish

    Collaborators

    • sighrobot