NOTE: Currently, only the md variant has been implemented.

The Pagination component takes in a colorScheme object to customise the colours of the component. ColorScheme is experimental and has been implemented only locally but you can read more about how it currently works and available options on the repository's github.

Anatomy

The root Pagination component allows the user to pass in a pagesCount prop, it is a number that tells the component how many pagination items to render. It also takes in a labels prop which is an object which has this shape { popoverTiggerLabel: string, nextPageButtonLabel: string, previousPageButtonLabel: string }, this prop is responsible for adding labels to the next/previous buttons and the popover trigger, if this prop is not added the default labels are "Next page" for the next page button, "Previous page" for the previous page button and "Open pagination popover" for the popover trigger.

It also takes in a visibleElementsCount prop it can take a value 6 or 8, which dictates how many elements in the pagination we wish to render, inclusive of the next, previous, and popup buttons. For example, with visibleElementsCount set to 6, it will display a previous page button, a next page button, a popup button, and 3 more page buttons. With visibleElementsCount set to 8 it may display up to 5 page buttons. By default, it is set to 6. This component can also takes in an onSelectedPageChange prop which is a function that can allow the parent component to have access to the selected page set on the pagination component. There is also an onItemHover prop which is a function that take a page number as argument and is triggered when a pagination item has been hovered over, we advise you debounce you call back function to prevent function calls.

It can also take in a selectedPage prop which allows the parent component to pass in a numerical value indicating which page the parent component is currently showing, if the selectedPage prop is not passed in, the Pagination component as an internal state to keep track of the current page, by default this state is set to the first page.

The Pagination component also takes in a disabledPages props which is an array of numbers, which indicate which pagination items should be disabled, and it also takes in a indicatedPages prop which is also an array of numbers to indicate which pagination item should be highlighted in the accent colour, which represents the page as completed.

Examples

Number of visible elements

<Pagination
  pagesCount={6}
  colorScheme={{ base: 'purple2', accent: 'purple1'}}
/> 

Above is an example of passing in a number to the pagesCount prop that will render 6 pagination items, the visibleElementsCount prop is set to 6 by default. So the user will see two navigation buttons, an action button to trigger the popover and 3 page numbers.

<Pagination
  pagesCount={6}
  visibleElementsCount={8}
  colorScheme={{ base: 'grey1', accent: 'primary1'}}
/>

Above is an example of passing visibleElementsCount prop and setting it to 8. The user will see two navigation buttons, an action button to trigger the popover and five page numbers.

Disabled and indicated pages

<Pagination
  colorScheme={{ base: 'grey1', accent: 'primary1'}}
  disabledPages={[1,2]}
  indicatedPages={[4,5]}
  visibleElementsCount={8}
  pagesCount={5}
  labels={{ popoverTiggerLabel: 'popover label', nextPageButtonLabel: 'next page label', previousPageButtonLabel: 'previous page label' }}
/>

Above is an example of when we use the disabledPages prop allowing us to render the pagination items for page 1 and 2 as disabled, and using the indicatedPages prop which colours the background of page numbers 4 and 5, and adding custom labels to the next/previous button and popover trigger.

Color Scheme

<Pagination
  pagesCount={6}
  visibleElementsCount={8}
  indicatedPages={[3]}
  colorScheme={{ base: 'primary2', accent: 'purple1'}}
/> 

Above is an example of using the colorScheme property. Base is the unselected & unindicated state, and accent is used for the "highlighted" selection and indicated states. The default is base: 'grey1' accent: 'primary1'

The number (eg. primary1, primary2) refers to the darkness of the palette. A scheme with 1 has a default background of white, and hover of pale colour. A scheme with 2 has a default shifted one level darker, so starts with that pale colour rather than white.

Custom popover trigger

The pagination can also be displayed just using the popover, no number list, with a custom trigger.

<Pagination
        pagesCount={24}
        selectedPage={1}
        indicatedPages={[4,5]}
      >
        <Pagination.Popover>
          <Button>
            <Text>Question 1/24</Text>
          </Button>
        </Pagination.Popover>
      </Pagination>

API Reference