Pagination Component

Overview

The Pagination component provides a flexible navigation interface for paginated content. It's designed to handle various pagination scenarios with customizable options for page display, navigation, and information display.

Basic Usage

import { Pagination } from '@dashflowx/core'

export default function PaginationExample() {
  return (
    <Pagination 
      currentPage={2}
      totalPages={10}
    />
  )
}

Preview:

Examples

Basic Pagination

import { Pagination } from '@dashflowx/core'

export default function BasicPagination() {
  return (
    <Pagination 
      currentPage={2}
      totalPages={10}
    />
  )
}

Preview:

Pagination with First/Last Buttons

import { Pagination } from '@dashflowx/core'

export default function PaginationWithFirstLast() {
  return (
    <Pagination 
      currentPage={5}
      totalPages={20}
      showFirstLast={true}
    />
  )
}

Preview:

Compact Variant

import { Pagination } from '@dashflowx/core'

export default function CompactPagination() {
  return (
    <Pagination 
      currentPage={3}
      totalPages={15}
      maxVisiblePages={3}
      variant="compact"
    />
  )
}

Preview:

Minimal Variant

import { Pagination } from '@dashflowx/core'

export default function MinimalPagination() {
  return (
    <Pagination 
      currentPage={4}
      totalPages={8}
      variant="minimal"
    />
  )
}

Preview:

Extended Variant

import { Pagination } from '@dashflowx/core'

export default function ExtendedPagination() {
  return (
    <Pagination 
      currentPage={10}
      totalPages={100}
      maxVisiblePages={7}
      showFirstLast={true}
      variant="extended"
    />
  )
}

Preview:

Different Sizes

import { Pagination } from '@dashflowx/core'

export default function SizeVariations() {
  return (
    <div className="space-y-4">
      {/* Small */}
      <Pagination 
        currentPage={2}
        totalPages={10}
        size="sm"
      />
      
      {/* Medium (default) */}
      <Pagination 
        currentPage={2}
        totalPages={10}
        size="md"
      />
      
      {/* Large */}
      <Pagination 
        currentPage={2}
        totalPages={10}
        size="lg"
      />
    </div>
  )
}

Preview:

Pagination with Info Text

import { Pagination } from '@dashflowx/core'

export default function PaginationWithInfo() {
  return (
    <Pagination 
      currentPage={2}
      totalItems={150}
      itemsPerPage={10}
      showInfo={true}
    />
  )
}

Preview:

Showing 11-20 of 150 items

Pagination with Page Size Selector

import { Pagination } from '@dashflowx/core'

export default function PaginationWithPageSize() {
  return (
    <Pagination 
      currentPage={1}
      totalItems={200}
      itemsPerPage={20}
      showPageSize={true}
      pageSizeOptions={[10, 20, 50, 100]}
    />
  )
}

Preview:

Items per page:

Interactive Pagination

import { Pagination } from '@dashflowx/core'
import { useState } from 'react'

export default function InteractivePagination() {
  const [currentPage, setCurrentPage] = useState(1);
  const [itemsPerPage, setItemsPerPage] = useState(10);
  const totalItems = 150;

  const handlePageChange = (page: number) => {
    setCurrentPage(page);
  };

  const handlePageSizeChange = (pageSize: number) => {
    setItemsPerPage(pageSize);
    setCurrentPage(1); // Reset to first page when changing page size
  };

  return (
    <Pagination 
      currentPage={currentPage}
      totalItems={totalItems}
      itemsPerPage={itemsPerPage}
      showFirstLast={true}
      showInfo={true}
      showPageSize={true}
      pageSizeOptions={[5, 10, 20, 50]}
      onPageChange={handlePageChange}
      onPageSizeChange={handlePageSizeChange}
    />
  )
}

Preview:

Showing 21-30 of 150 items

Items per page:

Common Use Cases

Data Table Pagination

const DataTablePagination = () => (
  <Pagination 
    currentPage={currentPage}
    totalItems={totalItems}
    itemsPerPage={itemsPerPage}
    showFirstLast={true}
    showInfo={true}
    showPageSize={true}
    variant="extended"
  />
);

Search Results Pagination

const SearchResultsPagination = () => (
  <Pagination 
    currentPage={searchPage}
    totalItems={searchResults.length}
    itemsPerPage={resultsPerPage}
    showFirstLast={false}
    maxVisiblePages={3}
    variant="compact"
  />
);

Blog Post Pagination

const BlogPagination = () => (
  <Pagination 
    currentPage={currentPost}
    totalPages={totalPosts}
    showFirstLast={true}
    maxVisiblePages={7}
    variant="extended"
    size="lg"
  />
);

API Response Pagination

const ApiPagination = () => (
  <Pagination 
    currentPage={apiPage}
    totalItems={apiTotalItems}
    itemsPerPage={apiItemsPerPage}
    showFirstLast={true}
    showInfo={true}
    onPageChange={handleApiPageChange}
    onPageSizeChange={handleApiPageSizeChange}
  />
);

Best Practices

Organize pagination logically and consistently.

// ✅ Good - Clear structure
<Pagination 
  currentPage={currentPage}
  totalItems={totalItems}
  itemsPerPage={itemsPerPage}
  showFirstLast={true}
  showInfo={true}
/>

// ❌ Avoid - Confusing structure
<div>Random page numbers</div>

Consistent Styling

Maintain consistent styling across your application.

// ✅ Good - Consistent styling
<Pagination 
  className="standard-pagination-style"
  variant="default"
  size="md"
  currentPage={currentPage}
  totalItems={totalItems}
/>

// ❌ Avoid - Inconsistent styling
<Pagination 
  className="random-styles"
  variant="minimal"
  size="lg"
  currentPage={currentPage}
  totalItems={totalItems}
/>

Accessible Pagination

Ensure pagination is accessible to all users.

// ✅ Good - Accessible
<Pagination 
  currentPage={currentPage}
  totalItems={totalItems}
  showFirstLast={true}
  showInfo={true}
/>

// ❌ Avoid - Not accessible
<div>Page numbers without proper structure</div>

Responsive Design

Make pagination responsive for different screen sizes.

// ✅ Good - Responsive
<Pagination 
  currentPage={currentPage}
  totalItems={totalItems}
  maxVisiblePages={window.innerWidth < 768 ? 3 : 7}
  variant="compact"
/>

// ❌ Avoid - Fixed width
<Pagination 
  currentPage={currentPage}
  totalItems={totalItems}
  className="w-96"
/>

Proper Page Handling

Handle page changes properly.

// ✅ Good - Proper handling
const handlePageChange = (page: number) => {
  setCurrentPage(page);
  fetchData(page);
};

const handlePageSizeChange = (pageSize: number) => {
  setItemsPerPage(pageSize);
  setCurrentPage(1);
  fetchData(1, pageSize);
};

// ❌ Avoid - No handling
<Pagination 
  currentPage={currentPage}
  totalItems={totalItems}
/>

Customization

Custom Styling

You can customize the pagination appearance using CSS classes:

<Pagination 
  className="border border-gray-300 rounded-lg p-4"
  currentPage={currentPage}
  totalItems={totalItems}
/>

Different Variants

Use different variants for different contexts:

// Compact variant for mobile
<Pagination 
  currentPage={currentPage}
  totalItems={totalItems}
  variant="compact"
  maxVisiblePages={3}
/>

// Extended variant for desktop
<Pagination 
  currentPage={currentPage}
  totalItems={totalItems}
  variant="extended"
  maxVisiblePages={7}
  showFirstLast={true}
/>

Size Variations

Use different sizes for different emphasis levels:

// Small pagination for secondary content
<Pagination 
  size="sm"
  currentPage={currentPage}
  totalItems={totalItems}
/>

// Large pagination for primary content
<Pagination 
  size="lg"
  currentPage={currentPage}
  totalItems={totalItems}
/>

Utility Functions

The pagination utility functions provide powerful state management and helper functions for working with pagination.

Using the usePagination Hook

import { Pagination } from '@dashflowx/core'
import { usePagination } from '@/utils/pagination'

export default function PaginationWithHook() {
  const { state, actions } = usePagination({
    currentPage: 1,
    totalItems: 150,
    itemsPerPage: 10
  });

  const handlePageChange = (page: number) => {
    actions.setCurrentPage(page);
    // Fetch new data here
  };

  const handlePageSizeChange = (pageSize: number) => {
    actions.setItemsPerPage(pageSize);
    // Fetch new data with new page size
  };

  return (
    <Pagination 
      currentPage={state.currentPage}
      totalItems={state.totalItems}
      itemsPerPage={state.itemsPerPage}
      showFirstLast={true}
      showInfo={true}
      showPageSize={true}
      onPageChange={handlePageChange}
      onPageSizeChange={handlePageSizeChange}
    />
  )
}

Preview:

Showing 21-30 of 150 items

Items per page:

Using Pagination Presets

import { Pagination } from '@dashflowx/core'
import { paginationPresets } from '@/utils/pagination'

export default function PresetPagination() {
  return (
    <div className="space-y-4">
      {/* Small preset */}
      <Pagination 
        currentPage={2}
        totalPages={10}
        {...paginationPresets.small}
      />
      
      {/* Medium preset */}
      <Pagination 
        currentPage={2}
        totalPages={10}
        {...paginationPresets.medium}
      />
      
      {/* Large preset */}
      <Pagination 
        currentPage={2}
        totalPages={10}
        {...paginationPresets.large}
      />
    </div>
  )
}

Preview:

Using Utility Functions

import { paginationUtils } from '@/utils/pagination'

export default function UtilityExample() {
  const currentPage = 3;
  const totalPages = 15;
  const itemsPerPage = 10;
  const totalItems = 150;

  // Get page range
  const pageRange = paginationUtils.getPageRange(currentPage, totalPages, 5);
  
  // Get pagination info
  const paginationInfo = paginationUtils.getPaginationInfo(currentPage, itemsPerPage, totalItems);
  
  // Calculate offset for API calls
  const offset = paginationUtils.getOffset(currentPage, itemsPerPage);

  return (
    <div className="space-y-4">
      <div>
        <strong>Page Range:</strong> {pageRange.join(', ')}
      </div>
      <div>
        <strong>Info:</strong> {paginationInfo.text}
      </div>
      <div>
        <strong>Offset:</strong> {offset}
      </div>
    </div>
  )
}

Manual State Management

import { Pagination } from '@dashflowx/core'
import { usePagination } from '@/utils/pagination'

export default function ManualPagination() {
  const { state, actions } = usePagination({
    currentPage: 1,
    totalItems: 200,
    itemsPerPage: 20
  });

  return (
    <div className="space-y-4">
      {/* Manual controls */}
      <div className="flex gap-2">
        <button
          onClick={actions.goToFirstPage}
          disabled={state.currentPage === 1}
          className="px-3 py-1 bg-blue-500 text-white rounded disabled:opacity-50"
        >
          First
        </button>
        <button
          onClick={actions.goToPreviousPage}
          disabled={state.currentPage === 1}
          className="px-3 py-1 bg-blue-500 text-white rounded disabled:opacity-50"
        >
          Previous
        </button>
        <button
          onClick={actions.goToNextPage}
          disabled={state.currentPage === state.totalPages}
          className="px-3 py-1 bg-blue-500 text-white rounded disabled:opacity-50"
        >
          Next
        </button>
        <button
          onClick={actions.goToLastPage}
          disabled={state.currentPage === state.totalPages}
          className="px-3 py-1 bg-blue-500 text-white rounded disabled:opacity-50"
        >
          Last
        </button>
      </div>

      {/* Pagination component */}
      <Pagination 
        currentPage={state.currentPage}
        totalItems={state.totalItems}
        itemsPerPage={state.itemsPerPage}
        showFirstLast={true}
        showInfo={true}
        onPageChange={actions.setCurrentPage}
      />
    </div>
  )
}

Advanced Usage

Dynamic Pagination

Create dynamic pagination based on data:

import { usePagination } from '@/utils/pagination'

const [paginationData, setPaginationData] = useState({
  currentPage: 1,
  totalItems: 0,
  itemsPerPage: 10
});

const { state, actions } = usePagination(paginationData);

useEffect(() => {
  // Load pagination data based on API response
  loadPaginationData().then(setPaginationData);
}, []);

Conditional Pagination

Show/hide pagination based on conditions:

const getPaginationConfig = (totalItems: number) => {
  const baseConfig = {
    currentPage: 1,
    totalItems,
    itemsPerPage: 10
  };
  
  if (totalItems <= itemsPerPage) {
    return null; // Don't show pagination
  }
  
  return baseConfig;
};

Pagination State Management

Handle pagination state:

const [paginationState, setPaginationState] = useState({
  currentPage: 1,
  itemsPerPage: 10
});

const handlePaginationChange = (page: number) => {
  setPaginationState(prev => ({
    ...prev,
    currentPage: page
  }));
  
  // Update URL or fetch new data
  updateUrl(page);
  fetchData(page);
};

const handlePageSizeChange = (pageSize: number) => {
  setPaginationState(prev => ({
    ...prev,
    itemsPerPage: pageSize,
    currentPage: 1
  }));
  
  fetchData(1, pageSize);
};

NavigationMenu: For navigation menus
MenuList: For menu lists
Button: For pagination triggers
Link: For pagination links

Props Reference

PaginationProps

Prop	Type	Default	Description
`currentPage`	`number`	`1`	Current active page number
`totalPages`	`number`	`10`	Total number of pages
`totalItems`	`number`	`undefined`	Total number of items (used to calculate totalPages)
`itemsPerPage`	`number`	`10`	Number of items per page
`className`	`string`	`''`	Additional CSS classes
`showFirstLast`	`boolean`	`false`	Show/hide first and last page buttons
`showPrevNext`	`boolean`	`true`	Show/hide previous and next buttons
`showEllipsis`	`boolean`	`true`	Show/hide ellipsis (...) for hidden pages
`maxVisiblePages`	`number`	`5`	Maximum number of visible page buttons
`variant`	`'default' \| 'minimal' \| 'compact' \| 'extended'`	`'default'`	Visual variant of the pagination
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of the pagination component
`disabled`	`boolean`	`false`	Disable all pagination interactions
`showInfo`	`boolean`	`false`	Show information text (e.g., "Showing 1-10 of 100 items")
`showPageSize`	`boolean`	`false`	Show page size selector
`pageSizeOptions`	`number[]`	`[10, 20, 50, 100]`	Available page size options
`preset`	`'small' \| 'medium' \| 'large' \| 'compact' \| 'extended'`	`undefined`	Apply predefined pagination configuration
`onPageChange`	`(page: number) => void`	`undefined`	Callback function when page changes
`onPageSizeChange`	`(pageSize: number) => void`	`undefined`	Callback function when page size changes

Variants

default: Standard pagination with normal spacing
minimal: Minimal spacing between elements
compact: Compact spacing for tight layouts
extended: Extended spacing for prominent display

Sizes

sm: Small size for secondary content
md: Medium size (default) for standard content
lg: Large size for primary content

Presets

small: Compact pagination with minimal visible pages
medium: Standard pagination with balanced features
large: Extended pagination with maximum visible pages
compact: Minimal pagination without ellipsis
extended: Full-featured pagination with all options

Utility Functions

The @/utils/pagination module provides several utility functions:

usePagination(initialState): React hook for state management
paginationUtils.getPageRange(): Calculate visible page range
paginationUtils.getOffset(): Calculate data offset for API calls
paginationUtils.calculateTotalPages(): Calculate total pages from items
paginationUtils.isValidPage(): Validate page number
paginationUtils.getPaginationInfo(): Get pagination info text
paginationPresets: Predefined configuration objects

Event Handlers

The onPageChange callback receives the new page number:

const handlePageChange = (page: number) => {
  console.log('Page changed to:', page);
  // Update state, fetch data, update URL, etc.
};

The onPageSizeChange callback receives the new page size:

const handlePageSizeChange = (pageSize: number) => {
  console.log('Page size changed to:', pageSize);
  // Update state, reset to first page, fetch data, etc.
};

API Reference

For the complete API reference and advanced usage patterns, see the Pagination API documentation.

Overview

Basic Usage

Examples

Basic Pagination

Pagination with First/Last Buttons

Compact Variant

Minimal Variant

Extended Variant

Different Sizes

Pagination with Info Text

Pagination with Page Size Selector

Interactive Pagination

Common Use Cases

Data Table Pagination

Search Results Pagination

Blog Post Pagination

API Response Pagination

Best Practices

Clear Navigation Structure

Consistent Styling

Accessible Pagination

Responsive Design

Proper Page Handling

Customization

Custom Styling

Different Variants

Size Variations

Utility Functions

Using the usePagination Hook

Using Pagination Presets

Using Utility Functions

Manual State Management

Advanced Usage

Dynamic Pagination

Conditional Pagination

Pagination State Management

Related Components

Props Reference

PaginationProps

Variants

Sizes

Presets

Utility Functions

Event Handlers

API Reference