pagination.tsx

Overview

pagination.tsx defines a set of React UI components designed to build accessible, customizable pagination controls for web applications. These components collectively provide a flexible foundation for rendering paginated navigation elements such as page links, previous/next buttons, and ellipsis indicators. The components leverage utility-first CSS (likely Tailwind CSS) combined with a design system's button variants to maintain consistent styling.

This file exports individual components that can be composed to create a complete pagination interface, allowing developers to customize appearance, behavior, and accessibility attributes with ease.

Components and Their Details

1. Pagination

• Type: React Functional Component

• Purpose: Serves as the root <nav> container for the pagination UI.

• Props: Inherits all standard props for a <nav> element via React.ComponentProps<'nav'> plus an optional className.

• Accessibility: Adds role="navigation" and aria-label="pagination" to indicate the purpose of the navigation landmark.

• Styling: Applies flexbox centering and full-width layout by default, with optional additional classes via className.

• Usage Example:

  <Pagination className="my-4">
    {/* PaginationContent and items here */}
  </Pagination>
  

• Display Name: 'Pagination'

2. PaginationContent

• Type: React ForwardRef Component rendering a <ul> element

• Purpose: Acts as the container for pagination items, typically <li> elements.

• Props: Accepts all <ul> props plus className.

• Ref: Exposes a ref to the underlying <ul> for parent components.

• Styling: Uses flex layout with horizontal direction, aligned center, and defined gap between items.

• Usage Example:

  <PaginationContent>
    <PaginationItem>...</PaginationItem>
    <PaginationItem>...</PaginationItem>
  </PaginationContent>
  

• Display Name: 'PaginationContent'

3. PaginationItem

• Type: React ForwardRef Component rendering an <li> element

• Purpose: Represents an individual pagination item container.

• Props: Accepts all <li> props plus className.

• Ref: Exposes a ref to the <li>.

• Styling: No default styles, but accepts additional classes.

• Usage Example:

  <PaginationItem>
    <PaginationLink href="/page/1">1</PaginationLink>
  </PaginationItem>
  

• Display Name: 'PaginationItem'

4. PaginationLink

• Type: React Functional Component rendering an <a> element styled as a button

• Props:

  • isActive?: boolean — whether this link represents the current active page.

  • size?: ButtonProps['size'] — size variant for the button styling, defaults to 'icon'.

  • All other standard anchor (<a>) props.

• Styling: Uses buttonVariants utility to style links as buttons with conditional variants:

  • 'outline' variant if active page.

  • 'ghost' variant otherwise.

• Accessibility: Sets aria-current="page" if active to signal current page to screen readers.

• Usage Example:

  <PaginationLink href="/page/2" isActive>
    2
  </PaginationLink>
  

• Display Name: 'PaginationLink'

5. PaginationPrevious

• Type: React Functional Component wrapping PaginationLink

• Purpose: Renders a button/link to navigate to the previous page.

• Props: Inherits all props of PaginationLink plus optional className.

• Accessibility: Sets aria-label="Go to previous page".

• Styling: Uses size="default" with padding and gap for icon + label.

• Children: Renders a left chevron icon (<ChevronLeft>) from lucide-react.

• Usage Example:

  <PaginationPrevious href="/page/1" />
  

• Display Name: 'PaginationPrevious'

6. PaginationNext

• Type: React Functional Component wrapping PaginationLink

• Purpose: Renders a button/link to navigate to the next page.

• Props: Same as PaginationPrevious.

• Accessibility: Sets aria-label="Go to next page".

• Styling: Uses size="default" with padding and gap for icon + label.

• Children: Renders a right chevron icon (<ChevronRight>) from lucide-react.

• Usage Example:

  <PaginationNext href="/page/3" />
  

• Display Name: 'PaginationNext'

7. PaginationEllipsis

• Type: React Functional Component rendering a <span>

• Purpose: Displays an ellipsis (...) to indicate skipped pages in the pagination.

• Props: Accepts all <span> props plus className.

• Accessibility: Sets aria-hidden to true for the icon, and includes a visually hidden label "More pages" for screen readers.

• Styling: Fixed square size with flex centering.

• Children: Renders a horizontal dots icon (<MoreHorizontal>) from lucide-react.

• Usage Example:

  <PaginationEllipsis />
  

• Display Name: 'PaginationEllipsis'

Implementation Details and Algorithms

• This file primarily defines presentational components that rely heavily on composition and styling utilities.

• The components use React.forwardRef where appropriate to allow parent components to access DOM nodes directly.

• The cn function is a className merging utility, presumably similar to clsx or classnames, used to combine default and custom styles.

• The buttonVariants function applies consistent design system button styles and variants to PaginationLink, supporting size and variant props.

• Accessibility considerations are embedded, including roles, aria-labels, and aria-current to improve screen reader support.

• Icons are imported from lucide-react, a popular icon library, ensuring consistent and scalable vector graphics for UI elements.

Interaction with Other Parts of the Application

• The file imports buttonVariants and ButtonProps from a UI button component module (@/components/ui/button), indicating dependency on a centralized button styling system.

• It uses the utility function cn from @/lib/utils for class name management.

• The icons (ChevronLeft, ChevronRight, MoreHorizontal) are from the lucide-react icon set, which is likely used throughout the app for consistent iconography.

• These components are designed to be composable and can be integrated into any page or component requiring pagination controls.

• Higher-level pagination logic (e.g., determining page numbers, handling click navigation) is expected to be implemented by the consumer of these components.

Example Usage

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationPrevious,
  PaginationNext,
  PaginationEllipsis,
} from './pagination';

function MyPaginationExample() {
  return (
    <Pagination className="my-4">
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious href="/page/1" />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="/page/1">1</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="/page/2" isActive>
            2
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="/page/3">3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationEllipsis />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="/page/10">10</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationNext href="/page/3" />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  );
}

Mermaid Component Diagram

componentDiagram
    direction LR
    component Pagination {
      +nav (role="navigation", aria-label="pagination")
    }
    component PaginationContent {
      +ul (flex row container)
    }
    component PaginationItem {
      +li (pagination item container)
    }
    component PaginationLink {
      +a (styled link/button)
      +isActive: boolean
      +size: string
    }
    component PaginationPrevious {
      +PaginationLink (with left chevron icon)
    }
    component PaginationNext {
      +PaginationLink (with right chevron icon)
    }
    component PaginationEllipsis {
      +span (ellipsis icon "More pages")
    }

    Pagination "1" --> "1" PaginationContent : contains
    PaginationContent "1" --> "*" PaginationItem : contains
    PaginationItem "*" --> "1" PaginationLink : contains (usually)
    PaginationItem "*" --> "1" PaginationEllipsis : contains (optionally)
    PaginationPrevious --|> PaginationLink : extends
    PaginationNext --|> PaginationLink : extends

Summary

The pagination.tsx file provides a modular and accessible pagination UI system for React applications. It leverages composable components with clean separation of concerns, styling conformity via button variants, and accessibility best practices. The components are designed for flexibility, allowing developers to build complex pagination interfaces while maintaining consistent design and usability.