@@ -0,0 +1,172 @@
|
||||
# Pagination
|
||||
|
||||
A page navigation row with Prev/Next links and numbered page buttons. The current page is highlighted. Links are built from a URL pattern.
|
||||
|
||||
---
|
||||
|
||||
## HTML structure
|
||||
|
||||
```
|
||||
nav[aria-label=Pagination].flex.items-center.justify-center.gap-1
|
||||
a.pag-btn[href=prevUrl, aria-label=Previous] ← disabled styling when current=1
|
||||
svg (chevron-left)
|
||||
a.pag-btn[href=url] ← one per page in the visible window
|
||||
{pageNumber} ← current page has pag-btn-active class
|
||||
span.pag-ellipsis ← rendered when pages are skipped
|
||||
a.pag-btn[href=nextUrl, aria-label=Next] ← disabled styling when current=total
|
||||
svg (chevron-right)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSS mechanics
|
||||
|
||||
| Class | Effect |
|
||||
|---|---|
|
||||
| `pag-btn` | `inline-flex h-9 w-9 items-center justify-center rounded-md border border-input bg-background text-sm hover:bg-accent` |
|
||||
| `pag-btn-active` | `bg-primary text-primary-foreground border-primary hover:bg-primary/90` |
|
||||
| `pag-ellipsis` | `inline-flex h-9 w-9 items-center justify-center text-sm text-muted-foreground` |
|
||||
| `pointer-events-none opacity-50` | Applied to Prev when `current == 1`, to Next when `current == total` |
|
||||
|
||||
The visible page window is limited to 7 buttons maximum. For large page counts the component collapses interior pages into ellipsis spans, keeping first page, last page, and the pages immediately around `current` always visible.
|
||||
|
||||
---
|
||||
|
||||
## Constructor signature
|
||||
|
||||
```csharp
|
||||
public Pagination(
|
||||
int current,
|
||||
int total,
|
||||
string urlPattern)
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `current` | 1-based current page number |
|
||||
| `total` | Total number of pages |
|
||||
| `urlPattern` | URL template with `{0}` replaced by the page number, e.g. `"/items?page={0}"` |
|
||||
|
||||
---
|
||||
|
||||
## Usage examples
|
||||
|
||||
### Basic pagination
|
||||
|
||||
```csharp
|
||||
new Pagination(current: 3, total: 10, urlPattern: "/blog?page={0}")
|
||||
```
|
||||
|
||||
### Preserving query parameters
|
||||
|
||||
```csharp
|
||||
// Build the URL pattern from the current request
|
||||
var query = HttpUtility.ParseQueryString(Request.QueryString.ToString());
|
||||
query["page"] = "{0}";
|
||||
var pattern = "/search?" + query.ToString();
|
||||
|
||||
new Pagination(current: page, total: totalPages, urlPattern: pattern)
|
||||
```
|
||||
|
||||
### HTMX-powered pagination (swap content without full navigation)
|
||||
|
||||
The links are standard `<a>` tags. To intercept them with HTMX, use `hx-boost` on the container or wrap in a boosted `<div>`:
|
||||
|
||||
```html
|
||||
<div hx-boost="true" hx-target="#item-list" hx-push-url="true">
|
||||
$$Pagination$$
|
||||
</div>
|
||||
```
|
||||
|
||||
### Single page (hides naturally)
|
||||
|
||||
```csharp
|
||||
// When total == 1, Prev and Next are both disabled and only "1" is rendered.
|
||||
new Pagination(current: 1, total: 1, urlPattern: "/items?page={0}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips and tricks
|
||||
|
||||
- The `urlPattern` uses `string.Format`-style `{0}` — do not use `{page}` or other named placeholders.
|
||||
- Page numbers are 1-based throughout — the first page is page `1`.
|
||||
- When `total` is 0 or negative the component renders nothing — guard `total > 1` in the page if you want to hide it entirely when there is only one page.
|
||||
- To preserve sort order or filters across pages, include those values in the `urlPattern` query string.
|
||||
- For very small page counts (2–3 pages), all page buttons are shown with no ellipsis.
|
||||
- For very small page counts (2–3 pages), all page buttons are shown with no ellipsis.
|
||||
|
||||
---
|
||||
|
||||
## Complete page example
|
||||
|
||||
**`Templates/BlogPage.htmx`**
|
||||
```html
|
||||
<div class="max-w-3xl mx-auto py-10">
|
||||
<h1 class="text-2xl font-bold mb-6">Blog</h1>
|
||||
<div class="space-y-6 mb-10">
|
||||
$$PostList$$
|
||||
</div>
|
||||
$$Pagination$$
|
||||
</div>
|
||||
```
|
||||
|
||||
**`Templates/BlogPage.htmx.cs`**
|
||||
```csharp
|
||||
namespace Htmx.ApiDemo.Templates;
|
||||
|
||||
public sealed class BlogPage : BlogPageBase
|
||||
{
|
||||
private readonly byte[] _postList;
|
||||
private readonly IHtmxComponent _pagination;
|
||||
|
||||
public BlogPage(IEnumerable<BlogPost> posts, int currentPage, int totalPages)
|
||||
{
|
||||
var sb = new System.Text.StringBuilder();
|
||||
foreach (var post in posts)
|
||||
{
|
||||
sb.Append($"""
|
||||
<article class="border-b pb-6">
|
||||
<h2 class="text-lg font-semibold mb-1">
|
||||
<a href="/blog/{System.Net.WebUtility.HtmlEncode(post.Slug)}"
|
||||
class="hover:underline">
|
||||
{System.Net.WebUtility.HtmlEncode(post.Title)}
|
||||
</a>
|
||||
</h2>
|
||||
<p class="text-sm text-muted-foreground mb-2">{post.PublishedAt:MMMM d, yyyy}</p>
|
||||
<p class="text-sm">{System.Net.WebUtility.HtmlEncode(post.Summary)}</p>
|
||||
</article>
|
||||
""");
|
||||
}
|
||||
_postList = sb.ToString().ToUtf8Bytes();
|
||||
_pagination = new Components.Pagination(
|
||||
current: currentPage,
|
||||
total: totalPages,
|
||||
urlPattern: "/blog?page={0}");
|
||||
}
|
||||
|
||||
protected override void RenderPostList(HtmxRenderContext ctx) => ctx.Writer.WriteUtf8(_postList);
|
||||
protected override void RenderPagination(HtmxRenderContext ctx) => _pagination.Render(ctx.Next());
|
||||
}
|
||||
```
|
||||
|
||||
**GET handler**
|
||||
```csharp
|
||||
[Handler]
|
||||
[MapGet("/blog")]
|
||||
public static partial class GetBlogHandler
|
||||
{
|
||||
public record Query([property: FromQuery] int Page = 1);
|
||||
|
||||
private static async Task<IResult> HandleAsync(
|
||||
Query q, HttpContext ctx, BlogService blog, CancellationToken ct)
|
||||
{
|
||||
const int pageSize = 10;
|
||||
var (posts, total) = await blog.GetPageAsync(q.Page, pageSize, ct);
|
||||
int totalPages = (int)Math.Ceiling(total / (double)pageSize);
|
||||
|
||||
return await ctx.WriteHtmxPage(
|
||||
new BlogPage(posts, q.Page, totalPages), title: "Blog");
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user