shaamilahmed/Htmx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrote all the docs - more noob friendly now.

Browse Source 
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
Enciphered
2026-05-05 23:55:26 +05:00
parent e483bf73e7
commit f6ae86617c
35 changed files with 2159 additions and 2341 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Components/Pagination.md
+40 -57
View File
@@ -1,38 +1,20 @@
# 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.
A row of numbered page links — Previous, 1, 2, 3…, Next. Use it at the bottom of a list or table when there are too many items to show all at once. You give it the current page number, the total number of pages, and a URL pattern; it builds all the links automatically.
---
## HTML structure
## Quick example
```
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)
```csharp
new Pagination(current: 3, total: 10, urlPattern: "/blog?page={0}")
```
---
## 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.
This renders a navigation row with links to pages 1–10 (with ellipsis for interior pages) and the Previous/Next arrows.
---
## Constructor signature
## All the options
```csharp
public Pagination(
@@ -41,60 +23,61 @@ public Pagination(
string urlPattern)
```
| Parameter | Description |
| Parameter | What it does |
|---|---|
| `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}"` |
| `current` | The currently active page. 1-based (the first page is `1`). |
| `total` | The total number of pages. |
| `urlPattern` | A URL with `{0}` where the page number goes. E.g. `"/items?page={0}"`. |
The visible page window is at most 7 buttons. For large page counts, interior pages collapse into ellipsis (`…`) while the first page, last page, and pages close to `current` stay visible.
---
## Usage examples
## Real-world examples
### Basic pagination
### Basic list with pagination
```csharp
new Pagination(current: 3, total: 10, urlPattern: "/blog?page={0}")
```html
<!-- Templates/BlogPage.htmx -->
<div class="space-y-6 mb-10">$$Posts$$</div>
$$Pager$$
```
### 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)
// Templates/BlogPage.htmx.cs
_pager = new Pagination(
current: page,
total: totalPages,
urlPattern: "/blog?page={0}");
```
### HTMX-powered pagination (swap content without full navigation)
### Preserving filters and sort order across pages
The links are standard `<a>` tags. To intercept them with HTMX, use `hx-boost` on the container or wrap in a boosted `<div>`:
Build the URL pattern to include any query parameters that should survive page navigation:
```csharp
var urlPattern = $"/users?role={role}&sort={sort}&page={{0}}";
new Pagination(current: page, total: totalPages, urlPattern: urlPattern)
```
> Note the double braces `{{0}}` to produce a literal `{0}` after string interpolation.
### HTMX-powered pagination (no full page reload)
Wrap the pagination (and the content it controls) in a `hx-boost` container:
```html
<div hx-boost="true" hx-target="#item-list" hx-push-url="true">
$$Pagination$$
<div id="item-list">$$Items$$</div>
$$Pager$$
</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
## How it works
- 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.
All links are plain `<a href="...">` elements — no JavaScript required. The URL for each page is built by calling `string.Format(urlPattern, pageNumber)`. When `current == 1`, the Previous link is styled as disabled (pointer-events removed, opacity reduced); same for Next when `current == total`.
---