Pagination

The Pagination component is a versatile and customizable pagination solution. It is designed to handle paginated content in your application, allowing users to navigate through pages with ease. The component consists of several subcomponents, each of which can be used to customize the appearance and functionality of the pagination.

The main Pagination component is responsible for rendering the pagination structure. It takes care of the layout and the slot management for its child components.

Importing

import {
  Pagination,
  PaginationButton,
  PaginationButtonGroup,
  PaginationItem,
  PaginationPages,
  PaginationSinglePage,
} from '@ef-global/backpack/Pagination';

Usage

Here's a basic example of the Pagination component:

<Pagination>
  <PaginationButton as='button' onClick={() => {}} data-slot='PaginationPreviousButtonGroup'>
    <IconChevronLeft />
  </PaginationButton>
  <PaginationPages data-slot='PaginationPages'>
    <PaginationItem key={1}>
        1
      </PaginationItem>
    <PaginationItem key={2} active={true}>
        2
      </PaginationItem>
    <PaginationItem key={3}>
        3
      </PaginationItem>
    <PaginationItem key={4}>
        4
      </PaginationItem>
  </PaginationPages>
  <PaginationSinglePage>
    2/4
  </PaginationSinglePage>
  <PaginationButton as='button' onClick={() => {}} data-slot='PaginationNextButtonGroup'>
    <IconChevronRight />
  </PaginationButton>
</Pagination>

Props

Prop Name	Type	Description
children	Array of subcomponents	An array of subcomponents to be rendered within the Pagination component. Can include PaginationPreviousButtonGroup, PaginationNextButtonGroup, PaginationPages, and PaginationSinglePage.

Subcomponents

PaginationButton

A button component used for the previous and next buttons in the pagination component. Inherits the properties of the Button component, while providing specific styles for pagination.

PaginationButtonGroup

A container component for grouping buttons within the pagination component. It is used for both the previous and next button groups.

PaginationItem

A component representing an individual page in the pagination component. Can be rendered as an anchor element or as a child element, and can be styled as active (for the current page) or inactive (e.g., for ellipsis).

Props

Prop Name	Type	Description
active	boolean	Indicates whether the PaginationItem is the currently active page. Defaults to `false`.
clickable	boolean	Determines if the PaginationItem is clickable. Defaults to `true`.
className	string	An optional custom CSS class name to be applied to the PaginationItem.
children	React.ReactNode	The content of the PaginationItem, usually the page number or custom content.
asChild	boolean	If `true`, the PaginationItem will render the provided `children` as direct children of the `li` element. Defaults to `false`.

PaginationPages

A container component that holds the PaginationItem components. It is responsible for managing the display and layout of the pagination page indicators.

Props

Prop Name	Type	Description
children	React.ReactNode	The list of PaginationItems to be rendered within the PaginationPages component.

PaginationSinglePage

A component that displays the current page and total pages in a single-page pagination format, such as "3/10". This component is ideal to be shown on mobile.

Props

Prop Name	Type	Description
children	React.ReactNode	The content to be displayed in the PaginationSinglePage component, usually a string with the format "current_page/total_pages".

Using the usePagination Hook

The usePagination hook is a custom hook that simplifies the process of generating a list of page items for a pagination component. It takes three arguments:

visiblePages: The maximum number of pages that should be visible at a time, including ellipsis (the "..." symbol) if they are present.
pageCount: The total number of pages.
activePage: The current active (or selected) page.

The hook returns an array of items that represent the pagination structure. Each item in the array can be either a number, indicating the page number, or a special string value (usually an ellipsis) indicating a range of pages that are not directly visible.

The primary goal of the usePagination hook is to ensure that the pagination component can display a reasonable number of pages while still providing a way to navigate through all available pages. It does this by calculating which pages should be visible, and adding ellipsis symbols when needed to indicate that there are more pages not shown.

Examples

Uncontrolled Pagination

In this example, the pagination component is uncontrolled and the page changes are not managed by a state.

  <Pagination>
    <PaginationButtonGroup data-slot='PaginationPreviousButtonGroup'>
      <PaginationButton className='mobileButton' as='button' onClick={() => {}}>
        <IconChevronDoubleLeft />
      </PaginationButton>
      <PaginationButton as='button' onClick={() => {}}>
        <IconChevronLeft />
      </PaginationButton>
    </PaginationButtonGroup>
    <PaginationPages data-slot='PaginationPages'>
      <PaginationItem key={1}>
          1
        </PaginationItem>
      <PaginationItem key={2} active={true}>
          2
        </PaginationItem>
      <PaginationItem key={3}>
          3
        </PaginationItem>
      <PaginationItem key={4}>
          4
        </PaginationItem>
    </PaginationPages>
    <PaginationSinglePage>
      2/4
    </PaginationSinglePage>
    <PaginationButtonGroup data-slot='PaginationNextButtonGroup'>
      <PaginationButton as='button' onClick={() => {}}>
        <IconChevronRight />
      </PaginationButton>
      <PaginationButton className='mobileButton' as='button' onClick={() => {}}>
        <IconChevronDoubleRight />
      </PaginationButton>
    </PaginationButtonGroup>
  </Pagination>

Controlled Pagination

In this example, the pagination component is controlled, and the page changes are managed by the component's state.

import { isDot, usePagination } from '@/src/components/hooks/usePagination';
const pageCount = 30;
const [activePage, setActivePage] = useState(15);
return (
  <Pagination>
    <PaginationButtonGroup data-slot='PaginationPreviousButtonGroup'>
      <PaginationButton
        className='mobileButton'
        as='button'
        disabled={activePage <= 1}
        onClick={() => setActivePage(1)}
      >
        <IconChevronDoubleLeft />
      </PaginationButton>
      <PaginationButton
        as='button'
        disabled={activePage <= 1}
        onClick={() => setActivePage(activePage - 1)}
      >
        <IconChevronLeft />
      </PaginationButton>
    </PaginationButtonGroup>
    <PaginationPages data-slot='PaginationPages'>
      {usePagination(7, pageCount, activePage).map((item) => (
        <PaginationItem
          key={item}
          clickable={!isDot(item)}
          active={item === activePage}
          onClick={() => !isDot(item) && setActivePage(item)}
        >
          {isDot(item) ? '...' : item}
        </PaginationItem>
      ))}
    </PaginationPages>
    <PaginationSinglePage>
      {activePage}/{pageCount}
    </PaginationSinglePage>
    <PaginationButtonGroup data-slot='PaginationNextButtonGroup'>
      <PaginationButton
        as='button'
        disabled={activePage >= pageCount}
        onClick={() => setActivePage(activePage + 1)}
      >
        <IconChevronRight />
      </PaginationButton>
      <PaginationButton
        className='mobileButton'
        as='button'
        disabled={activePage >= pageCount}
        onClick={() => setActivePage(pageCount)}
      >
        <IconChevronDoubleRight />
      </PaginationButton>
    </PaginationButtonGroup>
  </Pagination>
);

Modal Position Layer