@metadiv-studio/pagination

A modern, accessible pagination component built with React and TypeScript. This component provides a clean and intuitive way to navigate through paginated content with support for both light and dark themes.

📦 Installation

npm install @metadiv-studio/pagination

🎨 Tailwind CSS Configuration

Important: To use this package's Tailwind CSS styles, you must add the following path to your tailwind.config.js or tailwind.config.ts file:

// tailwind.config.js
module.exports = {
  content: [
    // ... other content paths
    "./node_modules/@metadiv-studio/**/*.{js,ts,jsx,tsx}",
  ],
  // ... rest of config
}

This ensures that Tailwind can scan the package's components and include the necessary CSS classes in your final build.

🚀 Usage

import { Pagination } from '@metadiv-studio/pagination';

function MyComponent() {
  const [currentPage, setCurrentPage] = useState(1);
  
  return (
    <Pagination
      page={currentPage}
      totalPages={10}
      total={100}
      onPageChange={setCurrentPage}
    />
  );
}

📋 Props

page (required)

• Type: number
• Description: The current active page number
• Example: page={1}

totalPages (required)

• Type: number
• Description: The total number of pages available
• Example: totalPages={10}

total (required)

• Type: number
• Description: The total number of items across all pages
• Example: total={100}

onPageChange (optional)

• Type: (page: number) => void
• Description: Callback function called when a page is clicked
• Example: onPageChange={(page) => console.log('Page changed to:', page)}

🎯 Examples

Basic Pagination

import { Pagination } from '@metadiv-studio/pagination';

function BasicExample() {
  const [page, setPage] = useState(1);
  
  return (
    <Pagination
      page={page}
      totalPages={10}
      total={100}
      onPageChange={setPage}
    />
  );
}

Pagination with Custom Handler

import { Pagination } from '@metadiv-studio/pagination';

function CustomHandlerExample() {
  const [page, setPage] = useState(1);
  
  const handlePageChange = (newPage: number) => {
    setPage(newPage);
    // Fetch data for the new page
    fetchData(newPage);
  };
  
  return (
    <Pagination
      page={page}
      totalPages={20}
      total={200}
      onPageChange={handlePageChange}
    />
  );
}

Static Pagination (Read-only)

import { Pagination } from '@metadiv-studio/pagination';

function StaticExample() {
  return (
    <Pagination
      page={5}
      totalPages={15}
      total={150}
      // No onPageChange prop = read-only
    />
  );
}

🎨 Features

• Responsive Design: Works seamlessly across different screen sizes
• Dark Mode Support: Automatically adapts to light/dark themes
• Accessibility: Built with ARIA attributes and keyboard navigation
• Smart Ellipsis: Intelligently shows ellipsis when there are many pages
• Disabled States: Previous/Next buttons are disabled when at first/last page
• TypeScript Support: Full type safety with TypeScript definitions

🔧 Behavior

The pagination component intelligently displays page numbers based on the current page:

• First Page: Shows current page, next page, and last page with ellipsis if needed
• Middle Pages: Shows previous page, current page, next page, and first/last pages with ellipsis
• Last Page: Shows first page, previous page, and current page with ellipsis if needed
• Small Page Count: Shows all page numbers when total pages ≤ 3

📱 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

🤝 Contributing

This package is part of the MetaDiv Studio component library. For issues, feature requests, or contributions, please refer to the main repository.

📄 License

This project is licensed under the UNLICENSE - see below for details.

UNLICENSE

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to http://unlicense.org/