mostlylucid.pagingtaghelper 1.0.0

Mostlylucid Paging TagHelper

The most flexible, powerful, and easy-to-use pagination library for ASP.NET Core.

v1.0 is 100% backward compatible! Upgrading from pre-v1 is safe and requires zero code changes. All existing attributes and defaults continue to work exactly as before. See migration guide

Built for modern web apps with HTMX, Alpine.js, or vanilla JavaScript support. Style it with TailwindCSS, DaisyUI, Bootstrap, or bring your own CSS. Zero configuration required to get started, infinitely customizable when you need it.

<paging model="Model" />

Live Demo | Documentation | Blog Posts

Features

Multiple UI Frameworks Out of the Box

• TailwindCSS + DaisyUI - Modern, beautiful components with dark mode
• Pure TailwindCSS - Utility-first styling without component dependencies
• Bootstrap - Classic Bootstrap pagination styles
• Plain CSS - Custom injected styles for any project
• Custom Views - Complete control with your own Razor views

Progressive Enhancement with JavaScript Modes

• HTMX - AJAX pagination without page reloads (default)
• HTMX + Alpine.js - Reactive state management with HTMX
• Alpine.js - Lightweight client-side navigation
• Plain JavaScript - Vanilla JS for maximum compatibility
• No JavaScript - Fully functional with forms and links only

Internationalization Built-In

• 8 languages supported out of the box (EN, DE, ES, FR, IT, JA, PT, ZH-Hans)
• Custom localization with resource files or inline text
• language="fr" - Just set the culture
• Custom summary templates with placeholders

Developer Experience

• Zero Configuration - Works immediately with sensible defaults
• Type-Safe - Full IntelliSense support in Razor views
• Extensible - Override anything, customize everything
• Well-Tested - 106 unit tests and counting
• HTMX-First - But works great without it

Bonus Features

• Continuation Token Pagination - Support for NoSQL databases (Cosmos DB, DynamoDB, Azure Table Storage) - Included in v1.0 with basic functionality, enhanced features coming in v1.1
• Sortable Headers - Flip between ascending/descending with visual indicators
• Page Size Selector - Standalone component for changing items per page
• Search Integration - Preserve search terms and filters across pages automatically
• Dark Mode - Automatic dark mode support for all views

Installation

dotnet add package mostlylucid.pagingtaghelper

That's it! No configuration files, no middleware, no setup. Just add the package and start using it.

Quick Start

1. Create Your Model

Implement IPagingModel with your data:

public class ProductListViewModel : IPagingModel
{
    public int Page { get; set; } = 1;
    public int PageSize { get; set; } = 10;
    public int TotalItems { get; set; }
    public List<Product> Products { get; set; } = new();
}

2. Populate in Your Controller

public async Task<IActionResult> Index(int page = 1, int pageSize = 10)
{
    var totalProducts = await _db.Products.CountAsync();
    var products = await _db.Products
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .ToListAsync();

    var model = new ProductListViewModel
    {
        Page = page,
        PageSize = pageSize,
        TotalItems = totalProducts,
        Products = products
    };

    return View(model);
}

3. Add to Your View

@model ProductListViewModel

<h1>Products</h1>

@foreach (var product in Model.Products)
{
    <div>@product.Name</div>
}

<paging model="Model" />

Done! You now have fully-functional pagination with HTMX support, page size selection, and localized text.

Usage Examples

HTMX with Partial Updates

<div id="product-list">
    <partial name="_ProductList" model="Model" />
</div>

<paging model="Model"
        hx-target="#product-list"
        hx-swap="outerHTML" />

Custom Language

<paging model="Model" language="fr" />

Custom Summary Template

<paging model="Model"
        summary-template="Showing {startItem}-{endItem} of {totalItems} items" />

Pure Tailwind (No DaisyUI)

<paging model="Model" view-type="Tailwind" />

No JavaScript (Progressive Enhancement)

<paging model="Model" js-mode="NoJS" />

Custom Text

<paging model="Model"
        first-page-text="First"
        previous-page-text="Previous"
        next-page-text="Next"
        last-page-text="Last" />

With Search

<paging model="Model" search-term="@Model.SearchQuery" />

Styling

The tag helper includes several built-in view types:

<paging model="Model" view-type="Tailwind" />

Custom Views

Create your own view in Views/Shared/Components/Pager/:

<paging model="Model" view-type="Custom" use-local-view="true" />

Read the Custom Views Guide

JavaScript Modes

Control how pagination behaves on the client:

<paging model="Model" js-mode="Alpine" />

Read the JavaScript Modes Guide

Localization

Built-in Languages

Set the culture with one attribute:

<paging model="Model" language="de" />  
<paging model="Model" language="ja" />  
<paging model="Model" language="fr" />  

Supported: English, German, Spanish, French, Italian, Japanese, Portuguese, Chinese (Simplified)

Custom Text

Override any text inline:

<paging model="Model"
        first-page-text="First"
        previous-page-text="Prev"
        next-page-text="Next"
        last-page-text="Last" />

Custom Summary Templates

Use placeholders to build your own summary:

<paging model="Model"
        summary-template="Page {currentPage} of {totalPages} - {totalItems} results" />

Available Placeholders:

• {currentPage} - Current page number
• {totalPages} - Total pages
• {totalItems} - Total item count
• {pageSize} - Items per page
• {startItem} - First item on page
• {endItem} - Last item on page

Read the Localization Guide

Bonus: Sortable Headers

Add sortable column headers with visual flip indicators:

<table>
    <thead>
        <tr>
            <sortable-header column="Name"
                           current-order-by="@Model.OrderBy"
                           descending="@Model.Descending">
                Product Name
            </sortable-header>
            <sortable-header column="Price"
                           current-order-by="@Model.OrderBy"
                           descending="@Model.Descending">
                Price
            </sortable-header>
        </tr>
    </thead>
</table>

Works seamlessly with HTMX or standard forms.

Bonus: Page Size Selector

Use the page size component standalone:

<page-size model="Model" />


<page-size model="Model" page-size-steps="5,10,25,50,100" />


<page-size model="Model" hx-target="#results" />

Continuation Pager (NoSQL Pagination)

For NoSQL databases that use continuation tokens (Cosmos DB, DynamoDB, Azure Table Storage):

<continuation-pager
    model="Model"
    htmx-target="#results-container"
    show-page-number="true"
    show-pagesize="true"
    max-history-pages="20"
    preserve-query-parameters="true" />

Key Features:

• Token-based navigation - Uses database continuation tokens instead of page offsets
• Numbered pages - Shows visited pages: [← Prev] [1] [2] [3 active] [4 disabled] [Next →]
• Backward navigation - Stores token history to enable clicking previous page numbers
• Query parameter preservation - Automatically preserves filters/searches (critical for token validity)
• Configurable history limit - Set max-history-pages to limit memory usage (default: 20)

Implement IContinuationPagingModel in your view model:

public class ProductsViewModel : IContinuationPagingModel
{
    public string? NextPageToken { get; set; }
    public bool HasMoreResults { get; set; }
    public int PageSize { get; set; } = 25;
    public int CurrentPage { get; set; } = 1;
    public Dictionary<int, string>? PageTokenHistory { get; set; }
    public List<Product> Products { get; set; } = new();
}

Documentation

Getting Started

• Getting Started - Detailed setup and first steps
• Migration Guide - Upgrading to v1.0 (100% backward compatible)

TagHelper Guides

• Pager TagHelper - Full pagination controls
• PageSize TagHelper - Standalone page size selector
• SortableHeader TagHelper - Sortable column headers
• ContinuationPager TagHelper - NoSQL token-based pagination

Features & Customization

• JavaScript Modes - HTMX, Alpine, PlainJS, NoJS modes
• Custom Views - Build your own pagination UI
• Localization - Multi-language support (8 languages)
• Advanced Usage - Search, sorting, filtering, performance

Reference

• API Reference - Complete attribute and property reference

Why Choose This Library?

For Beginners

• Works immediately with zero configuration
• Sensible defaults for everything
• Clear, simple API

For Professionals

• Full TypeScript/IntelliSense support
• 106 unit tests ensuring stability
• Backward compatible - won't break your code
• Production-ready and battle-tested

For Designers

• Multiple CSS frameworks supported
• Dark mode built-in
• Fully customizable views
• Accessible by default

For Performance

• Minimal JavaScript footprint
• Works without JavaScript entirely
• HTMX-optimized for instant navigation
• No heavy framework dependencies

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Acknowledgments

Built by Scott Galloway

• HTMX - For making AJAX simple again
• Alpine.js - For lightweight reactivity
• TailwindCSS - For utility-first styling
• DaisyUI - For beautiful components

Support

• Live Demo
• Blog Posts
• Issue Tracker

Made with ASP.NET Core Tag Helpers and View Components