@ibrahimstudio/pagination is a reusable React component designed to handle navigation across paginated datasets or views. It provides a highly customizable interface with support for boundary counts, sibling counts, ellipsis indicators, and various design options. This component ensures accessibility and responsiveness, making it suitable for modern web applications.

This documentation explains how to use the component, its available props, and examples to integrate it effectively.

Code by Ibrahim Space Studio, Design by Ibrahim Design Studio.

1. Features

• Highly Customizable: Adjust spacing, colors, and styles to match your design system.
• Accessible: The component uses semantic HTML and supports ARIA attributes.
• Responsive: Works well on devices with varying screen sizes.
• Minimal Dependencies: Lightweight and optimized for performance.
• Ellipsis Support: Automatically manages long pagination ranges with ellipses.

2. Installation

You can install this package via npm:

npm i @ibrahimstudio/pagination

or via yarn:

yarn add @ibrahimstudio/pagination

3. Usage

Basic Example

To create a basic pagination component:

<Pagination ttlPages={10} currentPage={1} onChange={(page) => console.log(`Navigated to ${page}`)} />

This example initializes a pagination bar for 10 pages. The onChange callback logs the current page when the user navigates to a different page.

Adding Boundary and Sibling Counts

<Pagination ttlPages={10} currentPage={1} sibling={2} boundary={1} />

Here, the pagination displays up to two sibling pages around the current page and one boundary page at the start and end of the range. This setup reduces clutter in large datasets.

Using Custom Labels for Navigation Buttons

<Pagination prevcontent={<span>Previous</span>} nextcontent={<span>Next</span>} />

This example customizes the "Previous" and "Next" button labels using the prevcontent and nextcontent props.

Styling the Pagination

<Pagination radius="full" bcolor="blue" pcolor="white" scolor="gray" variant="hollow" />

This example demonstrates customizing the appearance of the pagination using design props like radius, bcolor (background color), pcolor (primary color), scolor (secondary color), and variant.

4. API

Pagination Props

| Attribute | Type | Required | Description | Depend To | Default | | ------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------- | | id | string | Yes | A unique identifier for the pagination component. | - | '@ibrahimstudio/pagination' | | form | string | - | Specifies the form associated with the pagination buttons. | - | - | | currentPage | number | Yes | The currently active page. | - | 1 | | ttlPages | number | Yes | The total number of pages. | - | 1 | | sibling | number | - | Number of sibling pages to display on each side of the current page. | - | 1 | | boundary | number | - | Number of boundary pages to display at the beginning and end of the range. | - | 1 | | radius | 'none' 'sm' 'md' 'lg' 'full' | - | Defines the border-radius of the pagination buttons. | - | 'md' | | bcolor | string | - | Background color for pagination buttons. Can be a valid CSS color value or variable. | - | 'var(--theme-color-base)' | | pcolor | string | - | Primary color (e.g., text or active state) for pagination buttons. Can be a CSS color or variable. | - | 'var(--theme-color-primary)' | | scolor | string | - | Secondary color for hover or focus effects. Can be a CSS color or variable. | - | 'var(--theme-color-secondary)' | | variant | 'fill' 'hollow' | - | Specifies the visual style of the pagination buttons. | - | 'fill' | | prevcontent | React.ReactNode | - | Custom content for the "Previous" button. | - | <Chevron /> | | nextcontent | React.ReactNode | - | Custom content for the "Next" button. | - | <Chevron /> | | nospacing | boolean | - | If true, removes spacing between pagination buttons. | - | false | | noshadow | boolean | - | If true, disables shadow effects on the buttons. | - | false | | colorized | boolean | - | Applies color effects for the "hollow" variant. | variant='hollow' | false |

Pagination Event(s)

| Attribute | Type | Required | Description | Depend To | | ---------- | ---------------- | -------- | -------------------------------------------------------- | --------- | | onChange | (page) => void | Yes | Callback function triggered when a new page is selected. | - |

5. Contributing

Contributions are welcome! If you have any improvements, bug fixes, or features, feel free to open an issue or create a pull request on GitHub.

6. License

This project is licensed under the MIT License - see the LICENSE file for details.