Pager
Overview
The Pager facet type can be used to add several types of pagination.
It might seem a bit counter-intuitive that pagination can be added as a facet type, but just like any other facet type, a Pager facet can be added by making a new facet in the FacetWP admin interface.
Go to the Facets tab, click “add new”, choose “Pager” as Facet type, choose a pager type, set its options, and place it on your page with a shortcode.
Choose a pager type
A Pager facet can be used to display four different pager types. For each Pager facet you add, you have to choose one of these four pager types in the Pager facet’s options:
- Page numbers (and “Prev” / “Next” links)
- Result counts
- A “Load more” button
- A “Per page” box
Display multiple pager types on a page
For each pager type you want to display on a page, you need to add a separate Pager facet in the FacetWP admin interface, with the “Pager type” option set to its own type. So if you want to display Page numbers and Result counts and a Per page box, you need to make 3 separate Pager facets and place 3 different shortcodes on the page.
Display a pager type more than once on page
If you want to display page numbers (or any of the other pager types) twice (or more) on the same page, for example above and below your post listing, you can just use re-use the shortcode for that Pager facet and place it on the page twice.
Available options
Pager type
Name | Description |
---|---|
Pager type | Determines the pager type: Page numbers (and “Prev” / “Next” links), Result counts, a “Load more” button or a “Per page” box |
“Page numbers” pager type
Name | Description |
---|---|
Inner size | The number of pages to display on each side of the current page. |
Dots label | The placeholder between the inner and outer pages (leave blank to hide). Note: this label is translatable with the facetwp_i18n hook. |
Prev button label | The “Prev” button label (leave blank to hide). Note: this label is translatable with the facetwp_i18n hook. |
Next button label | The “Next” button label (leave blank to hide). Note: this label is translatable with the facetwp_i18n hook. |
“Result counts” pager type
Name | Description |
---|---|
Count text (plural) | The plural text. Available placeholders: [lower], [upper], [total], [page], [per_page], [total_pages]. Note: this text is translatable with the facetwp_i18n hook. |
Count text (singular) | The “Single result” text. Note: this text is translatable with the facetwp_i18n hook. |
Count text (none) | The “No results” text. Note: this text is translatable with the facetwp_i18n hook. |
“Load more” pager type
Name | Description |
---|---|
Load more text | The button text. Note: this text is translatable with the facetwp_i18n hook. |
Loading text | The button loading text. Note: this text is translatable with the facetwp_i18n hook. |
“Per page” pager type
Name | Description |
---|---|
Default label | Set the default dropdown label, or leave blank. Note: this label is translatable with the facetwp_i18n hook. |
Per page options | A comma-separated list of choices. Optionally add a non-numeric choice, for example “Show all”, to be used to show all results. Note: this “Show all” label text (or the label you give it) is translatable with the facetwp_i18n hook. |
How to add pagination scrolling
FacetWP is ajax-based, meaning pagination happens without a full page reload. The trade-off is that the browser does not automatically scroll to the top of the page upon pagination. This can be achieved with a bit of custom JavaScript. A few examples:
Scroll on paging facet interaction
This example scrolls the page all the way to the top, but only after interacting with the pager facet:
add_action( 'wp_head', function() { ?>
<script>
(function($) {
$(document).on('facetwp-refresh', function() {
if (FWP.soft_refresh == true) {
FWP.enable_scroll = true;
} else {
FWP.enable_scroll = false;
}
});
$(document).on('facetwp-loaded', function() {
if (FWP.enable_scroll == true) {
$('html, body').animate({
scrollTop: 0
}, 500);
}
});
})(jQuery);
</script>
<?php } );
Scroll on any facet interaction
This example scrolls after interaction with any facet, not only with the pager facet. In this example we also specify a point to scroll to: the top of the div with class facetwp-template
, which is the top of the results listing. You can specify any point with a class (.your-class
) or id (#your-id
).
add_action( 'wp_head', function() { ?>
<script>
(function($) {
$(document).on('facetwp-loaded', function() {
if (FWP.loaded) {
$('html, body').animate({
scrollTop: $('.facetwp-template').offset().top
}, 500);
}
});
})(jQuery);
</script>
<?php } );
Scroll offset and speed
Other settings you can play with, besides where to scroll to, are the scroll offset and scroll speed.
If you want to fine-tune the exact position where the scrolling ends, a scroll offset can be added. For example, if you have a sticky navigation bar taking up space at the top, without adjusting the scroll offset the scrolled results will disappear partly behind the sticky navigation bar. In the code example below, the scroll offset is set to -80
, which makes the scroll end 80px above the point specified, leaving room for the navigation bar.
Combine the settings in the code below with the above full examples.
// scrolls to a point that is 80px above the top of the div with class"facetwp-template":
$('html, body').animate({
scrollTop: $('.facetwp-template').offset().top -80
}, 500);
// scrolls to top of the div with class 'facetwp-template' in 350 milliseconds:
$('html, body').animate({
scrollTop: $('.facetwp-template').offset().top
}, 350);
FacetWP and infinite scroll
We often get the question if FacetWP supports infinite scroll, added by for example WooCommerce or Elementor infinite scroll plugins.
FacetWP does not support infinite scroll, which is intentional.
This means that plugins that add any form of infinity load / infinite scroll will not work as expected.
The closest thing is the “load more” pager type of the Pager facet, which generates a “load more” button, working similar to infinite scroll.
The load more button and URL vars
The “load more” pager type of the Pager facet does not update URL vars. This means that if a user clicks the Back button to go back to the listing, the position in the pagination and the previously loaded items are lost.
This behaviour is intentional. Let’s say there are 20 items per page and the user click the “load more” button 5 times, this results in 100 total results on the page. They click to go to a result, then click the Back button. When that Back button is clicked, FacetWP would have to load all 100 items at once, straining the server.
We recommend sticking with the “normal” numbers-based pager type (or use target="_blank"
to open results) unless you absolutely need a “load more” button.
Displaying raw pager data
You can display raw pager data using PHP within your template files.
Show page number:
<?php echo FWP()->facet->pager_args['page']; ?>
Show “Per page” number:
<?php echo FWP()->facet->pager_args['per_page']; ?>
Show the total number of results:
<?php echo FWP()->facet->pager_args['total_rows']; ?>
Show the total number of pages:
<?php echo FWP()->facet->pager_args['total_pages']; ?>
Pagination and WooCommerce
FacetWP has built-in support for WooCommerce pagination, so generally there is no need to use a Pager facet on shop pages.
A good reason to keep WooCommerce pagination is that you can keep your theme’s styling, while if you replace it with a Pager facet, you have to style the pagination to match your theme. But still you might want to to replace it, for example if you want to use a “Load more” Pager type.
Be aware that if you decide to keep WooCommerce pagination, you may need to apply some fixes to get pagination and result counts working properly, depending on your template.
If you decide to replace WooCommerce pagination with a Pager facet, make sure to read these pointers.
If you are using the WooCommerce Product Search plugin, you may see pagination issues using WooCommerce pagination or Pager facets, specifically on product category/term pages. This is a known incompatibility that has a workaround.