Pagination Component

September 5, 2025 · View on GitHub

Production-ready comprehensive pagination component with multiple modes including standard pagination, infinite scroll, and load more functionality. Full TypeScript compliance with AI metadata support.

Usage

import '@nexcraft/forge/organisms/pagination';

// Basic usage
html`
  <forge-pagination 
    current-page="1" 
    total-pages="10"
    total-items="100"
  ></forge-pagination>
`;

Properties

Property	Type	Default	Description
`currentPage`	`number`	`1`	Current active page number
`totalPages`	`number`	`1`	Total number of pages
`totalItems`	`number`	`0`	Total number of items across all pages
`pageSize`	`number`	`10`	Number of items per page
`mode`	`'pagination' \| 'infinite' \| 'load-more'`	`'pagination'`	Pagination mode
`showPageSize`	`boolean`	`true`	Show page size selector
`showJumpTo`	`boolean`	`true`	Show jump to page input
`showInfo`	`boolean`	`true`	Show pagination info text
`maxVisiblePages`	`number`	`7`	Maximum visible page buttons
`pageSizeOptions`	`number[]`	`[10, 25, 50, 100]`	Available page size options
`loading`	`boolean`	`false`	Loading state for async operations
`hasNextPage`	`boolean`	`true`	Whether there are more pages (infinite/load-more modes)

Events

Event	Detail	Description
`forge-page-change`	`{ page: number, previousPage: number }`	Fired when page changes
`forge-page-size-change`	`{ pageSize: number, previousPageSize: number }`	Fired when page size changes
`forge-load-more`	`{ currentPage: number }`	Fired when load more is triggered

Methods

Public Methods

Method	Parameters	Returns	Description
`goToPage(page)`	`page: number`	`void`	Navigate to specific page
`nextPage()`	-	`void`	Navigate to next page
`previousPage()`	-	`void`	Navigate to previous page
`firstPage()`	-	`void`	Navigate to first page
`lastPage()`	-	`void`	Navigate to last page
`setPageSize(size)`	`size: number`	`void`	Change page size

AI Metadata Methods

Method	Returns	Description
`explainState()`	`string`	Returns detailed explanation of current state
`getPossibleActions()`	`AIAction[]`	Returns available actions based on current state
`aiState`	`AIState`	Current component state for AI analysis

Key	Action
`Arrow Left`	Previous page
`Arrow Right`	Next page
`Home`	First page
`End`	Last page
`Enter`	Activate focused page button

Styling

CSS Custom Properties

forge-pagination {
  --forge-pagination-bg: #ffffff;
  --forge-pagination-border: #e0e0e0;
  --forge-pagination-border-radius: 8px;
  --forge-pagination-button-size: 40px;
  --forge-pagination-button-gap: 4px;
  --forge-pagination-active-color: #007bff;
  --forge-pagination-active-bg: #007bff;
  --forge-pagination-hover-bg: #f8f9fa;
  --forge-pagination-disabled-opacity: 0.5;
  --forge-pagination-padding: 16px;
}

CSS Parts

Part	Description
`pagination-container`	Main container element
`pagination-info`	Information section
`pagination-controls`	Page navigation controls
`page-button`	Individual page button
`page-size-selector`	Page size selection dropdown
`jump-to-page`	Jump to page input

Pagination Modes

Standard Pagination

Default mode with numbered page buttons and navigation controls.

html`
  <forge-pagination 
    current-page="3" 
    total-pages="20"
    total-items="200"
    mode="pagination"
  ></forge-pagination>
`;

Infinite Scroll Mode

Automatically loads more content as user scrolls to bottom.

html`
  <forge-pagination 
    mode="infinite"
    .hasNextPage=${this.hasMore}
    .loading=${this.isLoading}
    @forge-load-more=${this.loadMoreItems}
  ></forge-pagination>
`;

private async loadMoreItems() {
  this.isLoading = true;
  const newItems = await this.fetchMoreItems();
  this.items = [...this.items, ...newItems];
  this.hasMore = newItems.length === this.pageSize;
  this.isLoading = false;
}

Load More Mode

Shows a "Load More" button to fetch additional content.

html`
  <forge-pagination 
    mode="load-more"
    .hasNextPage=${this.hasMore}
    .loading=${this.isLoading}
    @forge-load-more=${this.loadMoreItems}
  ></forge-pagination>
`;

Examples

Basic Pagination

html`
  <forge-pagination 
    current-page="1" 
    total-pages="15"
    total-items="150"
    @forge-page-change=${this.handlePageChange}
  ></forge-pagination>
`;

private handlePageChange(e: CustomEvent) {
  const { page } = e.detail;
  this.loadPage(page);
}

Custom Page Sizes

html`
  <forge-pagination 
    current-page="1" 
    total-pages="10"
    total-items="500"
    page-size="50"
    .pageSizeOptions=${[25, 50, 100, 200]}
    @forge-page-size-change=${this.handlePageSizeChange}
  ></forge-pagination>
`;

private handlePageSizeChange(e: CustomEvent) {
  const { pageSize } = e.detail;
  this.pageSize = pageSize;
  this.currentPage = 1; // Reset to first page
  this.loadPage(1);
}

Minimal Pagination

html`
  <forge-pagination 
    current-page="5" 
    total-pages="20"
    show-page-size="false"
    show-jump-to="false"
    max-visible-pages="5"
  ></forge-pagination>
`;

Server-Side Pagination

class MyComponent extends LitElement {
  @state() private currentPage = 1;
  @state() private totalPages = 1;
  @state() private totalItems = 0;
  @state() private loading = false;

  render() {
    return html`
      <forge-pagination 
        .currentPage=${this.currentPage}
        .totalPages=${this.totalPages}
        .totalItems=${this.totalItems}
        .loading=${this.loading}
        @forge-page-change=${this.handlePageChange}
        @forge-page-size-change=${this.handlePageSizeChange}
      ></forge-pagination>
    `;
  }

  private async handlePageChange(e: CustomEvent) {
    const { page } = e.detail;
    this.loading = true;
    
    try {
      const response = await this.fetchPage(page);
      this.currentPage = response.currentPage;
      this.totalPages = response.totalPages;
      this.totalItems = response.totalItems;
      this.data = response.data;
    } finally {
      this.loading = false;
    }
  }
}

Accessibility

Full WCAG 2.1 AA compliance
Keyboard navigation support
ARIA attributes for screen readers:
- role="navigation" with aria-label="Pagination"
- aria-current="page" for current page
- aria-label descriptions for all buttons
Screen reader announcements for page changes
Focus management between page changes

Performance Considerations

Efficient rendering of page buttons with ellipsis for large page counts
Debounced input handling for jump-to-page
Lazy loading support for infinite scroll mode
Memory efficient event handling
Optimized re-rendering with shouldUpdate

Integration Patterns

With Data Table

html`
  <forge-data-table .data=${this.paginatedData}></forge-data-table>
  <forge-pagination 
    .currentPage=${this.currentPage}
    .totalPages=${this.totalPages}
    @forge-page-change=${this.handlePageChange}
  ></forge-pagination>
`;

With Search Results

html`
  <div class="search-results">
    ${this.results.map(result => html`
      <div class="result-item">${result.title}</div>
    `)}
  </div>
  
  <forge-pagination 
    .currentPage=${this.currentPage}
    .totalPages=${this.totalPages}
    .totalItems=${this.totalResults}
    @forge-page-change=${this.handlePageChange}
  ></forge-pagination>
`;

Browser Support

Chrome 84+
Firefox 78+
Safari 14+
Edge 84+

Data Table - Commonly used together for data display
Button - Used internally for navigation buttons
Select - Used for page size selection
Input - Used for jump to page functionality