# 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`](https:// * facebook.github.io/react/docs/refs-and-the-dom.html) 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 ```bash npm i boundless-pagination --save ``` Then use it like: ```jsx /** @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) => (
console.log('focused id: ' + data.id)} onKeyDown={(e) => console.log('pressed ' + e.key + ' on id: ' + data.id)}>
{data.first_name} {data.last_name}
{data.job_title}
{data.address1}
{data.city}, {data.country}
p: {data.phone}
e: {data.email}
) 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 can also just be directly used from the main [Boundless library](https://www.npmjs.com/package/boundless). This is recommended when you're getting started to avoid maintaining the package versions of several components: ```bash npm i boundless --save ``` the ES6 `import` statement then becomes like: ```js import { Pagination } from 'boundless'; ``` ## Props > Note: only top-level props are in the README, for the full list check out the [website](https://boundless.js.org/Pagination). ### 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](https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes) 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 ```jsx const getItem = () => ({id: 1234, text: 'foo'}); const objToJSX = ({id, text}) =>
{text}
; ``` 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: ```jsx showPaginatedState={ (currentPage, totalPages) => (
You're on page {currentPage} of {totalPages} pages!
) } ``` Expects | Default Value --- | --- `bool or function` | `true` ## Reference Styles ### Stylus You can see what variables are available to override in [variables.styl](https://github.com/enigma-io/boundless/blob/master/variables.styl). ```stylus // 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](https://github.com/enigma-io/boundless/blob/master/variables.styl).