use-cursor-pagination v0.0.2

usePagination Hook

The usePagination hook simplifies the process of adding pagination to your React components. It is designed to be used within a <PaginationProvider> context.

Installation

npm install use-cursor-pagination

Usage

First, wrap your component tree with :

import { PaginationProvider } from 'use-cursor-pagination';

function App() {
    return (
        <PaginationProvider>
            {/* Your components that use usePagination */}
        </PaginationProvider>
    );
}

Using with Apollo

import { useQuery } from '@apollo/client';
import { usePagination } from 'use-cursor-pagination';

const GET_ITEMS = gql`
  query GetItems($cursor: String, $limit: Int) {
    items(after: $cursor, first: $limit) {
      edges {
        node {
          id
          name
        }
      }
      pageInfo {
        endCursor
        hasNextPage
        hasPreviousPage
      }
      totalCount
    }
  }
`;

function ItemsList() {
  const { usePaginationEffect, getPaginationVariables } = usePagination();

  const { data: itemsData, loading: isItemsLoading } = useQuery(GET_ITEMS, {
    variables: {
      ...getPaginationVariables('itemsList'),
    },
    skip: !getPaginationVariables('itemsList')?.first && !getPaginationVariables('itemsList')?.last,
  });

  usePaginationEffect({
    dataKey: 'itemsList',
    hasNextPage: Boolean(itemsData?.items?.pageInfo.hasNextPage),
    hasPreviousPage: Boolean(itemsData?.items?.pageInfo.hasPreviousPage),
    initItemsPerPage: 10, // Set the initial number of items per page
    totalCount: itemsData?.items?.totalCount,
    endCursor: itemsData?.items?.pageInfo?.endCursor,
    startCursor: itemsData?.items?.pageInfo?.startCursor,
  });
}

The usePaginationEffect is a crucial part of the pagination system when working with GraphQL because it ensures that the pagination context is kept in sync with the latest data fetched from the server. Here's why it's important:

1. Synchronization with Server Data: As your application fetches new data from the server, usePaginationEffect updates the pagination context with the most recent information, such as cursors and page availability (hasNextPage/hasPreviousPage). This ensures that the pagination controls reflect the actual state of your data.

2. Cursor Management: GraphQL uses cursors to navigate through a dataset. usePaginationEffect handles the cursors (startCursor and endCursor) provided by the server, allowing the client to request the next or previous set of data accurately.

3. Dynamic Pagination: The effect dynamically adjusts the pagination based on the total count of items (totalCount) and the initial number of items per page (initItemsPerPage). This allows for flexible and user-friendly pagination.

4. Data Isolation with dataKey: The dataKey parameter is used to uniquely identify each pagination instance. This is important because it allows usePaginationEffect to manage multiple sets of paginated data independently within the same application. Each dataKey corresponds to a specific query, ensuring that the pagination controls interact with the correct dataset.

In summary, usePaginationEffect is essential for maintaining an up-to-date and accurate pagination state that corresponds with the data fetched from GraphQL queries. The dataKey is equally important as it isolates pagination states across different data sets or queries, preventing any mix-ups in the pagination logic.

Using pagination handles

To interact with the pagination handles in your component, you will use the functions provided by the usePagination hook. Here's a breakdown of each function and how to use it:

• goFirstPage(dataKey): Navigates to the first page of the dataset.
• goPreviousPage(dataKey): Moves to the previous page.
• goNextPage(dataKey): Advances to the next page.
• goLastPage(dataKey): Jumps to the last page.
• setCountPerPage(dataKey, count): Sets the number of items to display per page.

The getPaginationEntry function is part of the usePagination hook's API. It retrieves the current state of pagination for a given data set identified by dataKey. The state includes several variables that are essential for managing pagination:

• hasNextPage: A boolean that indicates whether there are more pages available after the current page.
• hasPreviousPage: A boolean that shows if there are pages available before the current page.
• currentPage: The number of the current page being displayed.
• pagesAmount: The total number of pages available.

Here is an example of how these functions can be used in a component

import React from 'react';
import { usePagination } from 'use-cursor-pagination';

export const SimplePagination = ({ dataKey }) => {
  const {
    getPaginationEntry,
    setCountPerPage,
    goPreviousPage,
    goNextPage,
    goFirstPage,
    goLastPage
  } = usePagination();

  const { hasNextPage, hasPreviousPage, currentPage, pagesAmount } = getPaginationEntry(dataKey);

  return (
    <div>
      <div>
        <button onClick={() => goFirstPage(dataKey)} disabled={!hasPreviousPage}>
          First Page
        </button>
        <button onClick={() => goPreviousPage(dataKey)} disabled={!hasPreviousPage}>
          Previous Page
        </button>
        <span>Page {currentPage} of {pagesAmount}</span>
        <button onClick={() => goNextPage(dataKey)} disabled={!hasNextPage}>
          Next Page
        </button>
        <button onClick={() => goLastPage(dataKey)} disabled={!hasNextPage}>
          Last Page
        </button>
      </div>
      <div>
        <label>Items per page:</label>
        <select onChange={(e) => setCountPerPage(dataKey, Number(e.target.value))}>
          <option value="10">10</option>
          <option value="20">20</option>
          <option value="50">50</option>
        </select>
      </div>
    </div>
  );
};