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:

  1. Page numbers (and “Prev” / “Next” links)
  2. Result counts
  3. A “Load more” button
  4. 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']; ?>

See also