Pagination
What you're building: a way through a listing that is longer than one page — a load-more button, numbered pages, or infinite scroll.
Pagination is a property of a browse listing. Search does not paginate; it re-queries.
What you need
- Applies toThe browse wrapper
Which style to use: load-more, numbered, or infinite.
- Applies toThe browse wrapper
How many results per page.
Pick a style
| Value | Behaviour | Controls you add |
|---|---|---|
load-more | Appends the next page on click | A button marked wf-algolia-element="load-more" |
numbered | Page links, one per page | Prev, next and page-number elements |
infinite | Loads as the visitor scrolls | None — the script inserts a sentinel |
Set the style on the browse wrapper:
<section
wf-algolia-element="browse"
wf-algolia-index="products"
wf-algolia-pagination="load-more"
wf-algolia-per-page="12"
></section>
Load more
Add a button inside the wrapper with . The script hides it when there are no more pages, so design the visible state and let it disappear on its own.
Numbered pages
Numbered pagination is assembled from separate controls, each with its own role:
- — previous page
- — next page
- — a single page link, cloned per page
- — "page 2 of 9"
The page-number element is a template: design one, and the script clones it. Use to cap how many appear at once, so 200 pages do not produce 200 links.
Generated page links carry the class wf-algolia-page-num, and the current page
gets the active class from data-activeclass.
Infinite scroll
Set wf-algolia-pagination="infinite" and add nothing else. The script places an
invisible sentinel after the results and loads the next page when it scrolls into
view.
Anything below the listing becomes unreachable while pages keep loading. If the
page has a footer people need, prefer load-more, which puts the visitor in
control.
Scroll position
offsets where the page scrolls to when a new page loads. Set it to the height of a sticky header so the first new row is not hidden behind it.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The button does nothing | It sits outside the browse wrapper | Move it inside |
| The button never disappears | The style is not load-more | Set wf-algolia-pagination="load-more" |
| Page numbers do not render | No element marked page-number to clone | Add one |
| Infinite scroll fires once, then stops | The next page failed — look for infinite-scroll loader rejected: | Check the network tab |
| Every page shows the same results | wf-algolia-per-page exceeds the total | Nothing to fix — there is only one page |