@asphalt-react/pagination

Pagination

Pagination component divides content into discrete pages. Use this component to show long lists of data divided across pages for a better experience. Pagination contains a list of links or buttons called page tiles to navigate through the pages. You can control the number of page tiles visible. Pagination also allows users to navigate to next, previous, first and last pages through actionable elements called steppers. They are visible by default, but you can choose to hide them.

Pagination components exports PerPage component. You can use this to set the number of records visible on each page.

You can also create a custom Pagination through a family of unit components and hooks exported by Pagination and other Asphalt React components.

Usage

import React, { useState } from "react"
import { Link } from "gatsby" // or any other router like react-router
import { Pagination, PerPage } from "@asphalt-react/pagination"

function App() {
  const [active, setActive] = useState(1)
  const [current, setCurrent] = useState(10)

  const getTileProps = (num) => ({
    to: `?page=${num}`,
  })

  const getPerPageTileProps = (recordsPerPage) => ({
    to: `?perPage=${recordsPerPage}`,
  })

  const handlePageChange = (e, pageNum) => {
    setActive(pageNum)
  }

  const handlePerPageChange = (e, records) => {
    setCurrent(records)
  }

  return (
    <div >
      <Pagination
        totalPages={50}
        as={Link}
        getTileProps={getTileProps}
        active={active}
        onChange={handlePageChange}
        slim
      />
      <div>
        <div>Items/Page: </div>
        <PerPage
          as={Link}
          getTileProps={getPerPageTileProps}
          recordsPerPage={[10, 25, 50, 100]}
          active={current}
          onChange={handlePerPageChange} 
        />
      </div>
    </div>
  )
}

Variants

Pagination has 3 variants to configure the number of page tiles:

1. minimal - contains only active page tile.
2. slim - contains 3 page tiles including active page tile. This is the default variant.
3. extended - contains 5 page tiles including active page tile.

Accessibility

• Use tab or shift+tab to navigate among pages.

Creating a custom Pagination

Pagination exports layout unit components and hooks using which you can create a custom implementation.

Components

1. BasePagination
2. PageItem

Hooks

usePagination

React hook to implement the functionality of Pagination in your custom implementation. You can customize the tile count and add truncation to your component. Truncation is a visual aid to let users know that some page tiles are hidden behind the truncation symbol like an ellipses.

import { BasePagination, usePagination } from "@asphalt-react/pagination"
import { ToggleButton } from "@asphalt-react/toggle-button"
import { ToggleButton } from "@asphalt-react/button"
import {
	ChevronBackward,
	ChevronForward,
	ChevronLeft,
	ChevronRight,
	More
} from "@asphalt-react/iconpack"

export const Pagination = () => {
	const { getPagesList } = usePagination({
    active,
    totalPages,
    tileCount: 5,
  })

	const pages = getPagesList({ truncate: false })

	return (
		<BasePagination>
      <PageItem>
        <Button
          link={false}
          disabled={!link && active === 1}
          nude
          icon
          compact
          system
          onClick={(e) => onChange(e, 1)}
        >
          <ChevronBackward />
        </Button>
      </PageItem>
      <PageItem>
        <Button
          link={false}
          disabled={!link && active === 1}
          nude
          icon
          compact
          system
          onClick={(e) => onChange(e, active - 1)}
        >
          <ChevronLeft />
        </Button>
      </PageItem>

      {pages.map((pageNum) =>
        <PageItem key={`page-${pageNum}`}>
          <ToggleButton
            link={false}
            seamless
            compact
            underline={false}
            onClick={(e) => onChange(e, pageNum)}
            on={pageNum === active}
          >
            {pageNum}
          </ToggleButton>
        </PageItem>
      )}

      <PageItem>
        <Button
          link={false}
          disabled={!link && active === totalPages}
          nude
          icon
          compact
          system
          onClick={(e) => onChange(e, active + 1)}
        >
          <ChevronRight />
        </Button>
      </PageItem>

      <PageItem>
        <Button
          link={false}
          disabled={!link && active === totalPages}
          nude
          icon
          compact
          system
          onClick={(e) => onChange(e, totalPages)}
        >
          <ChevronForward />
        </Button>
      </PageItem>
    </BasePagination>
	)
}

1. usePagination accepts the following props:
   • active - active page number.
   • totalPages - total number of pages.
   • tileCount - page tile count.
2. It returns functions which exposes certain functionality of pagination.
   • isStartTruncated() - returns a boolean value denoting truncation at start of page tiles
   • isEndTruncated - returns a boolean value denoting truncation at end of page tiles
   • getPagesList({ truncate = false }) - returns an array of page numbers which can be used to render the page tiles of pagination. Accepts truncate as a boolean argument.
   • The output of getPagesList contains -1, specifying the position of truncation.

Props

totalPages

Total number of available pages.

type	required	default
number	true	N/A

active

Current page number.

type	required	default
number	false	1

onChange

Callback to be called when page changes.

onChange receives an object with the following shape.

• event - browser event
• page - active page number

({ event, page }) => {}

type	required	default
func	false	N/A

as

Html element/React component to replace the default element. Using this prop, you can use your router's link element, such as "react-router-dom"'s Link element.

type	required	default
elementType	false	"a"

getTileProps

Function to generate props such as "href", "id", data-attributes etc. for page tiles.

type	required	default
func	false	N/A

link

Render a link.

type	required	default
bool	false	true

stepper

Toggle visibility for next and previous stepper.

type	required	default
bool	false	true

previousStepperProps

Function to generate props such as "href", "id", data-attributes etc. for the previous stepper element.

type	required	default
func	false	N/A

nextStepperProps

Function to generate props such as "href", "id", data-attributes etc. for the next stepper element.

type	required	default
func	false	N/A

edgeStepper

Toggle visibility for left and right edge stepper.

type	required	default
bool	false	true

leftEdgeStepperProps

Function to generate props such as "href", "id", data-attributes etc. for the left edge stepper element.

type	required	default
func	false	N/A

rightEdgeStepperProps

Function to generate props such as "href", "id", data-attributes etc. for the right edge stepper element.

type	required	default
func	false	N/A

minimal

Variant to show current active tile, stepper and edge stepper.

type	required	default
bool	false	false

slim

Variant to show 3 page tiles, stepper and edge stepper.

type	required	default
bool	false	false

extended

Variant to show 5 page tiles, stepper and edge stepper.

type	required	default
bool	false	false

nextStepperLabel

aria-label for next stepper.

type	required	default
string	false	"go to next page"

previousStepperLabel

aria-label for previous stepper.

type	required	default
string	false	"go to previous page"

leftEdgeStepperLabel

aria-label for left edge stepper.

type	required	default
string	false	"go to first page"

rightEdgeStepperLabel

aria-label for right edge stepper.

type	required	default
string	false	"go to last page"

PerPage

Set number of records visible on each page.

Props

recordsPerPage

Array of numbers representing PerPage indices.

type	required	default
arrayOf	false	[10, 25, 50, 100]

as

Html element/React component to replace the default element. Using this prop, you can use your router's link element, such as "react-router-dom"'s Link element.

type	required	default
elementType	false	"a"

active

Number of records per page

type	required	default
number	false	10

getTileProps

Function to generate props such as "href", "id" for the custom link element passed in as prop.

type	required	default
func	false	N/A

onChange

Function to be called when per page value changes

onChange receives an object with the following signature

• event - click event
• records - number of records to show per page

 ({event, record}) => void

type	required	default
func	false	N/A

link

Render a link

type	required	default
bool	false	true

BasePagination

The base container unit component.

Props

children

Container for the BasePagination content.

type	required	default
node	false	N/A

gap

Adds gap between child elements

type	required	default
bool	false	true

PageItem

Renders the list element for page tiles.

Props

children

Content for a page list item.

type	required	default
node	true	N/A