An often-asked question is how to automatically scroll the page to the results (or to the top of the page or to another target), when using any facet, a specific facet, or even a specific facet choice. Below is a range of examples that should cover most scenarios.

The code in all examples runs on the facetwp-loaded event, which fires after each AJAX page load (meaning after each facet interaction), and also on the initial page load. With extra conditions, you can determine in which situation exactly the page should scroll. You can combine the mentioned conditions if needed.

Most examples scroll to the top of the results, which by definition is the element with class facetwp-template. If needed, you can customize the scroll target. You can also adapt the scroll scroll offset, the scroll duration/speed and easing.

Scroll on facet interaction after the initial page load

The following example scrolls the page to the top of the results (the element with class facetwp-template), after each facet interaction. Because the facetwp-loaded event fires after each AJAX page load, the page will scroll when any facet is used.

The code also demonstrates the use of the FWP.loaded variable in a condition. This variable is only true after the page has been loaded. This means the page will not scroll on the initial page load, also not if there are facet choices in the URL.

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() {
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
        if ( FWP.loaded ) { // Run only after the initial page load
          $('html, body').animate({
            scrollTop: $('.facetwp-template').offset().top // Scroll to the top of the element with class "facetp-template"
          }, 500);
        }
      });
    })(jQuery);
  </script>
<?php } );

Scroll also on the initial page load

If you want the the above code to also work on the initial page load, remove the FWP.loaded condition. Note that this makes the page scroll on any page load, also when there are no facet choices in the URL on the initial page load.

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() { 
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
        $('html, body').animate({
          scrollTop: $('.facetwp-template').offset().top
        }, 500);
      });
    })(jQuery);
  </script>
<?php } );

Scroll only on the initial page load

If you want to scroll the page only when the page initially loads, and not on the subsequent AJAX page loads (when interacting with facets), you can use ! FWP.loaded (where the ! means “not”). This condition is only true on the initial page load:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() { 
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
        if ( ! FWP.loaded ) { // Run only on the initial page load
          $('html, body').animate({
            scrollTop: $('.facetwp-template').offset().top
          }, 500);
        }
      });
    })(jQuery);
  </script>
<?php } );

Scroll when certain facets (or facet choices) are in use

In some situations, you may want the page to scroll only when a certain facet is used (or not used). Or even when a certain facet choice is used (or not used). A few examples:

Scroll only when a certain facet is in use

The following example scrolls the page to the top of the results only when the facet with name industry is in use, no matter which choice is selected:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() {
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
        let selected = FWP.facets['industry'];  // Replace "industry" with your facet name
        if ( selected.length ) { // If this facet has any choice selected
          $('html, body').animate({
            scrollTop: $('.facetwp-template').offset().top
          }, 500);
        }
      });
    })(jQuery);
  </script>
  <?php
}, 100 );

Scroll when a certain facet choice is selected

The following example scrolls the page to the top of the results only when the facet with the name industry has the choice consumer selected:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() {
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
        let selected = FWP.facets['industry']; // Replace "industry" with your facet name
        if ( selected == 'consumer'  ) { // Replace "consumer" with your facet choice (as displayed in the URL when it is selected)
          $('html, body').animate({
            scrollTop: $('.facetwp-template').offset().top
          }, 500);
        }
      });
    })(jQuery);
  </script>
  <?php
}, 100 );

For the facet choice, make sure to use the indexed facet_value, which is displayed in the URL when this choice is selected.

Scroll when any facet choice is selected

The following example scrolls the page to the top of the results when any facet choice is selected. The code uses FWP.buildQueryString() to check if FacetWP’s query string is not empty:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() {
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
        if ( '' != FWP.buildQueryString() ) {
          $('html, body').animate({
            scrollTop: $('.facetwp-template').offset().top
          }, 500);
        }
      });
    })(jQuery);
  </script>
  <?php
}, 100 );

This will work for any facet, except the Reset facet, which empties the query string. To scroll only when a Reset facet is used, see this code example.

Note that you can also do the opposite: check for an empty FWP.buildQueryString(), which lets you scroll the page after all facet choices have been deselected manually, or all at once, when clicking a Reset facet button/link.

Scroll when any facet choice is selected on the initial page load

If you want the page to scroll only on the initial page load, and only when there are facet selections in the URL, you can use the following code. It uses a condition that checks if FWP.loaded is not (!) true, which only happens on the initial page load.

This can be useful if you want the page to scroll only after using a Submit Button, or after a redirect from a search box on another page.

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() {
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
        if ( ! FWP.loaded ) { // Run on the initial page load only
          if ( '' != FWP.buildQueryString() ) { // Run only when there are facet selections in the URL
            $('html, body').animate({
              scrollTop: $('.facetwp-template').offset().top
            }, 500);
          }
        }
      });
    })(jQuery);
  </script>
  <?php
}, 100 );

Scroll when a Pager facet is used

Since version 4.2.12, FacetWP has a Scroll target setting to enable scrolling when using a Pager facet.

For earlier versions, or if the setting does not give enough control (for example if you want to adapt the scroll duration or use scroll easing), you can still enable scrolling with a code snippet.

The following example scrolls the page to the top of the page, only after interacting with the Pager facet:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
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: $('.facetwp-template').offset().top
          }, 500);
        }
      });
    })(jQuery);
  </script>
<?php } );

Scroll when a Reset facet is used

The following example scrolls the page when a Reset facet is used:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() {
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-refresh', function() {
        if ( FWP.is_reset == true ) {
          FWP.enable_scroll = true;
        } else {
          FWP.enable_scroll = false;
        }
      });
      $(document).on('facetwp-loaded', function() {
        if ( FWP.enable_scroll == true ) {
          $('html, body').animate({
            scrollTop: $('.facetwp-template').offset().top // Scroll to the top of the element with class "facetwp-template"
          }, 500);
        }
      });
    })(jQuery);
  </script>
<?php } );

Scroll when a Reset facet is used or when all facets are deselected

Alternatively, if you want the scroll to happen when clicking a Reset button/link, but also after manually deselecting all facets, you can check for an empty query string like this:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() {
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
        if ( FWP.loaded ) { // Run only after the initial page load
          if ('' == FWP.buildQueryString()) { // When no facets are selected, the query string is empty
            $('html, body').animate({
              scrollTop: $('.facetwp-template').offset().top
            }, 500);
          }
        }
      });
    })(jQuery);
  </script>
  <?php
}, 100 );

Customize the scroll target

The above examples specify a point to scroll to: the top of the element with class facetwp-template, which is the element containing the results listing.

You can use any element on the page as a target, by specifying its class (.my-element) or id (#my-element) in the scrollTop option:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() { 
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
          $('html, body').animate({
            scrollTop: $('#my-element').offset().top // Scroll to the top of an element with id="my-element"
          }, 500);
      });
    })(jQuery);
  </script>
<?php } );

Scroll to the top of the page

To scroll to the top of the page instead of to a specific element, use 0:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() {
  ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
          $('html, body').animate({
            scrollTop: 0 // Scroll to the top of the page
          }, 500);
      });
    })(jQuery);
  </script>
<?php } );

Customize the scroll offset

If you want to fine-tune the exact position where the scrolling ends, you can increase or decrease the target element’s offset (the coordinates relative to the document).

For example, if you have an 80px high 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 adjusted with a value of -80, which makes the scroll end 80px above the point specified, leaving room for the navigation bar.

You can combine this code with any of the full examples above:

How to use custom jQuery code?
jQuery code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. Note that jQuery code needs the jQuery library loaded. If it is not already loaded, you can enable jQuery in FacetWP's settings. More info
// 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);

Customize the scroll duration

To customize the scrolling duration (which determines the scroll speed, depending on the scroll distance), use the second parameter of the animate() function. The duration needs to be specified in milliseconds.

In the example below, the duration is set to 800 milliseconds. You can combine this code with any of the full examples above:

How to use custom jQuery code?
jQuery code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. Note that jQuery code needs the jQuery library loaded. If it is not already loaded, you can enable jQuery in FacetWP's settings. More info
// Scrolls to top of the div with class 'facetwp-template' in 800 milliseconds:
$('html, body').animate({
  scrollTop: $('.facetwp-template').offset().top
}, 800);

Customize the scroll easing

The jQuery animate() function can have an (optional) third “easing” parameter. Easing can be described as the gradual change in speed during an animation, allowing for a smooth-looking scroll movement.

jQuery Core comes with only two built-in easing types: linear and swing (the default), but if you have the jQuery UI library installed, there is a whole range of easing types you can use. There are also easing plugins and you can write custom easing functions.

How to use custom jQuery code?
jQuery code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. Note that jQuery code needs the jQuery library loaded. If it is not already loaded, you can enable jQuery in FacetWP's settings. More info
// Scroll with 'easeInOutCubic' easing
$('html, body').animate({
  scrollTop: $('.facetwp-template').offset().top
}, 800, 'easeInOutCubic');

See also

Last updated: September 10, 2024