--- title: "Pagination" description: "Pagination with page navigation, next and previous links." url: "https://susonwaiba.github.io/htmx-ui/docs/components/pagination" section: "Components" --- # Pagination Pagination with page navigation, next and previous links. ```html ``` ## Markup - A `

` around a `

`, with `aria-label="Page 2"` so it isn't read as a bare number. - The current page has `aria-current="page"`, which outlines it. It stays a link, so it can be reloaded or copied. - Previous and next add `.pagination-previous` / `.pagination-next` (and `rel="prev"` / `rel="next"`), with their text in a `.pagination-label`. - `.pagination-ellipsis` stands in for pages left out. It is `aria-hidden`: the page numbers either side already show the gap. - Plain links work without JavaScript; add htmx attributes to swap only the list (see [With htmx](#htmx)). The [macro](#macro) works out which pages to show and writes all of this for you. ## Page numbers only Leave out previous and next when there are few pages. ```html
- 1
- 2
- 3
- 4
- 5
``` ## Disabled On the first page there is no previous one. Keep the link in place, so nothing shifts, but drop its `href` and add `aria-disabled="true"`: it fades, can't be clicked and leaves the tab order. A `
10 20 50

Page 2 of 5
``` With htmx, the select can reload the table on change: `hx-get="/invoices" hx-trigger="change" hx-target="#invoices" hx-include="this"`. ## Sizes `.pagination-sm` and `.pagination-lg` on the `
` match `.btn-sm` and `.btn-lg` heights. ```html
- 1
- 2
- 3
- 1
- 2
- 3
``` ## Responsive `.pagination-responsive` fits a phone: below the `sm` breakpoint (640px) only previous, the current page and next show, and the previous / next labels are hidden visually but still read out. Narrow the window to see it. ```html
- Previous
- 1
- 4
- 5
- 6
- 10
- Next
``` ## Macro `pagination(page, total)` works out which pages to show and writes the whole `
`. `{page}` in `href` becomes each link's page number. ```jinja {% from "components/pagination/pagination.html" import pagination %} {{ pagination(5, 10, href="/invoices?page={page}") }} {{ pagination(2, 5, numbers=false, icons=true, first=true, last=true, size="sm", outline=true) }} ``` ### Which pages are shown The first and last `boundaries` pages always show, and `siblings` pages either side of the current one. An ellipsis stands in for two or more pages left out; a gap of one page shows that page instead. Once there are more pages than fit, the list always has the same number of items (2 × `siblings` + 2 × `boundaries` + 3, so 7 by default), so the links don't move about as the current page changes. | Call | Pages shown | | --- | --- | | `pagination(1, 10)` | [1] 2 3 4 5 … 10 | | `pagination(4, 10)` | 1 2 3 [4] 5 … 10 | | `pagination(5, 10)` | 1 … 4 [5] 6 … 10 | | `pagination(7, 10)` | 1 … 6 [7] 8 9 10 | | `pagination(10, 10)` | 1 … 6 7 8 9 [10] | | `pagination(3, 7)` | 1 2 [3] 4 5 6 7 (all fit) | | `pagination(10, 20, siblings=2, boundaries=2)` | 1 2 … 8 9 [10] 11 12 … 19 20 | | `pagination(10, 20, boundaries=0)` | … 9 [10] 11 … | The first, a middle and the last page of ten, rendered: ```html
- Previous
- 1
- 2
- 3
- 4
- 5
- 10
- Next
- Previous
- 1
- 4
- 5
- 6
- 10
- Next
- Previous
- 1
- 6
- 7
- 8
- 9
- 10
- Next
``` | Parameter | Description | | --- | --- | | `page, total` | Required. The current page (kept within 1…total) and the number of pages. | | `href="?page={page}"` | Each link's URL; {page} is replaced with its page number. | | `siblings=1` | Pages shown on each side of the current one. | | `boundaries=1` | Pages always shown at each end. | | `numbers=true` | false leaves out the page numbers: previous / next (and first / last) only. | | `previous=true, next=true` | true for "Previous" / "Next", a string for other text, false to leave the link out. | | `first=false, last=false` | true for icon-only links labelled "First page" / "Last page", or a string for another label. | | `icons=false` | true makes previous / next icon-only; their text becomes the aria-label. | | `page_label="Page {page}"` | Each page link's aria-label. | | `responsive=false` | true adds .pagination-responsive. | | `size` | "sm" or "lg". | | `outline=false` | true adds .pagination-outline. | | `label="Pagination"` | The
's aria-label. | | `attrs` | More attributes for every enabled link, as a dict; {page} is replaced in the values. | | `class` | More classes on the
. | ## With htmx Keep the links' `href`s, so the pages work without JavaScript, and let htmx fetch the same URLs and swap only the region holding the table and its pagination. With the macro, `attrs` puts the attributes on every link: ```jinja
…rows for this page…
{{ pagination(page, pages, href="/invoices?page={page}", attrs={ "hx-get": "/invoices?page={page}", "hx-target": "#invoices", "hx-select": "#invoices", "hx-swap": "outerHTML", "hx-push-url": "true" }) }}
``` which writes links like: ```html 3 ``` - `hx-select="#invoices"` picks the region out of the full page the server returns, so one route serves both normal visits and htmx requests. A server that checks the `HX-Request` header can return just the region instead and drop `hx-select`. - The region swapped includes the pagination, so the current page and the disabled ends update with the rows. - `hx-push-url="true"` puts `?page=3` in the address bar, so reloading and the back button land on the same page. - Disabled links have no `href` and the macro leaves their htmx attributes off, so they send nothing. - After the swap, focus is lost with the old link. Move it to the top of the region (for example a heading with `tabindex="-1"`) if keyboard users would otherwise start again from the top of the page. To write the attributes once rather than on every link, put them on the `
` as inherited attributes (`hx-target:inherited="#invoices"` and so on) and use `hx-boost:inherited="true"`, which makes htmx fetch each link's `href`. ## Keyboard | Key | Action | | --- | --- | | `Tab` `Shift`+`Tab` | Move between the links; disabled ones are skipped | | `Enter` | Go to that page | ## Accessibility - The `
` is a navigation landmark; its `aria-label` tells it apart from the site's other navigation. Use different labels when a page has two. - `aria-current="page"` tells screen readers which page is showing; don't rely on the outline alone. - Icon-only links need an `aria-label`. Links with visible text don't: an `aria-label` that differs from the text breaks voice control ("click Next"). - Page links are labelled "Page 3" rather than "3"; pass `page_label` to the macro to translate it. ## Reference | Class | Description | | --- | --- | | `.pagination` | The
: centres the list in its container. | | `.pagination-content` | The
of items. | | `.pagination-link` | A page, previous, next, first or last link (or button): a ghost button. | | `[aria-current="page"]` | On a .pagination-link: the current page, outlined. | | `[aria-disabled="true"], :disabled` | On a .pagination-link (with no href): faded and not clickable. | | `.pagination-previous / .pagination-next` | Previous / next links, with an icon and a .pagination-label (or an aria-label alone). | | `.pagination-first / .pagination-last` | First / last page links, usually icon-only with an aria-label. | | `.pagination-label` | The text of previous / next; hidden visually on small screens with .pagination-responsive. | | `.pagination-ellipsis` | "…" standing in for pages left out, aria-hidden. | | `.pagination-sm / .pagination-lg` | On the
: 32px / 40px links (36px by default). | | `.pagination-outline` | On the
: every link outlined; the current page filled. | | `.pagination-responsive` | On the
: below sm, only previous, the current page and next, with labels visually hidden. |