Pagination Reference

This document provides a comprehensive guide to implementing and customizing pagination components within the MSDN design system.

Overview

Pagination is a crucial UI pattern for breaking down large sets of data into manageable pages. It improves user experience by:

• Reducing cognitive load by presenting fewer items at once.
• Allowing users to quickly navigate to specific sections of data.
• Providing a clear indication of the user's current position within the dataset.

Component Structure

The standard pagination component consists of:

• Previous/Next Buttons: For navigating to the adjacent page.
• Page Numbers: Links to specific pages.
• Ellipses: Used to indicate a skipped range of page numbers when there are many pages.
• Current Page Indicator: Visually distinguishes the active page.
• Disabled State: For the first page's "Previous" button and the last page's "Next" button.

Basic Implementation

Here's a typical HTML structure for a pagination component:

<nav aria-label="Page navigation">
  <ul class="pagination">
    <li class="disabled">
      <span aria-hidden="true">‹</span>
      <span class="sr-only">Previous</span>
    </li>
    <li><a href="#">1</a></li>
    <li><a href="#">2</a></li>
    <li class="active"><a href="#">3</a></li>
    <li><a href="#">4</a></li>
    <li><a href="#">5</a></li>
    <li class="ellipsis"><span>...</span></li>
    <li><a href="#">10</a></li>
    <li>
      <a href="#" aria-label="Next">
        <span aria-hidden="true">›</span>
        <span class="sr-only">Next</span>
      </a>
    </li>
  </ul>
</nav>

CSS Styling

The provided CSS styles the pagination component for clarity and usability. Key classes include:

• .pagination: The main container for the pagination list.
• .pagination li: Individual list items.
• .pagination a, .pagination span: Styling for clickable/non-clickable page indicators.
• .active: Highlights the current page.
• .disabled: Styles disabled navigation buttons.
• .ellipsis: Styles the placeholder for skipped pages.

Example Usage

Here's a visual representation of the pagination component:

Accessibility Considerations

Ensure your pagination implementation is accessible:

• Use <nav> element with an appropriate aria-label.
• Use <span> with aria-hidden="true" for visual icons (like arrows) and provide screen-reader-only text (.sr-only) for their meaning.
• Mark the current page with .active and consider aria-current="page" for more robust screen reader support.
• For disabled links, use the .disabled class and ensure they are not focusable or clickable.

Customization

You can customize the pagination component by modifying the CSS variables or directly adjusting the styles. Consider:

• Changing the color scheme to match your application's branding.
• Adjusting the size and spacing of pagination items.
• Implementing alternative designs for different contexts (e.g., compact pagination for small screens).

JavaScript Integration

While the styling is pure CSS, you'll typically use JavaScript to handle the dynamic behavior of pagination:

• Fetching data for the requested page.
• Updating the UI to reflect the new page content.
• Managing the active state of pagination links.
• Dynamically generating pagination links based on the total number of items and items per page.

Example JavaScript Snippet (Conceptual)

This is a conceptual example showing how you might handle click events and state updates:

document.addEventListener('DOMContentLoaded', () => {
    const paginationContainer = document.querySelector('.pagination');

    if (paginationContainer) {
        paginationContainer.addEventListener('click', (event) => {
            const target = event.target;
            if (target.tagName === 'A' && !target.closest('li').classList.contains('disabled')) {
                event.preventDefault(); // Prevent default link behavior

                const pageNumber = target.textContent;
                console.log('Navigating to page:', pageNumber);

                // Here you would typically:
                // 1. Remove the 'active' class from the currently active page link.
                // 2. Add the 'active' class to the clicked link.
                // 3. Fetch the data for the 'pageNumber'.
                // 4. Update the content area with the fetched data.
                // 5. Update Previous/Next button states if necessary.

                // Example of updating active state (simplified):
                const currentActive = paginationContainer.querySelector('li.active a');
                if (currentActive) {
                    currentActive.parentElement.classList.remove('active');
                }
                target.parentElement.classList.add('active');
            }
        });
    }
});