Overview

With this hook, you can change the raw WP_Query arguments before the query is executed, and after facets are processed in the rendering process.

The query argument array is the input for the query: it tells WordPress which posts to retrieve from the database, in which order, how many per page, etc.

This hook is similar to the facetwp_query_args hook, but it runs much later. In most scenarios where you want to change FacetWP’s query arguments, using the facetwp_query_args hook is recommended. But in some specific situations, you may want to change the query arguments after facet selections have changed them:

When to use this hook

Where the facetwp_query_args hook runs before the facet selections have been processed, the facetwp_filtered_query_args runs after all of the following facet-processing hooks:

This means that facetwp_filtered_query_args has access to the query arguments that may be updated (or added) by the facet selections made:

Keep in mind that Sort facets set/change the orderby query argument with this same facetwp_filtered_query_args hook too, at priority 1. So if you use this hook at a later priority, this updated orderby query argument is also available.

How it works

The hook works similarly to WP’s pre_get_posts hook, but unlike that hook, it only runs on pages with facets, and it has access to information about the page, listing template and facets used, via the FacetWP_Renderer class. This can be used to let the code run only in certain conditions. For example, you can check:

  • if a specific Listing Builder template is used (with $class->ajax_params['template']).
  • if the page has a specific URI (with $class->http_params['uri']). Note that the “URI” is the part of the URL without the domain name and the query variables, and without beginning or ending slashes.
  • if specific facets or facet choices are currently in use (with $class->facets[ $facet_name ]['selected_values']).

See the code examples below for ways to use this.

Where to use this hook

In Listing Builder listing templates, this hook changes the results on the first page load and after facet filtering. For performance reasons, in other types of listing templates (like WP archives and custom WP_Query templates), this hook is prevented from changing the query on the first page load and will only affect the results after facet filtering.

To make this hook also run on the first page load in these other listing types, you can combine it with the following hook in your (child) theme’s functions.php:

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_filter( 'facetwp_preload_force_query', '__return_true' );

Parameters

  • $query_args | array | An associative array of query arguments (see below)
  • $class | object | The FacetWP_Renderer class (see /includes/class-renderer.php)
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
// Based on WP_Query. 
$query_args = [
  'post_type' => 'post',
  'posts_per_page' => 15,
  // ...
  'post__in' => [ 201,205,208 ], // The array of filtered post IDs.
  'paged' => 2, // The page number after using a Pager facet.
  'orderby' => 'post__in' // The order. E.g. 'post__in' if a Search facets is in use with "Order by relevance" enabled. The 'orderby' value is changed after using a Sort facet.
];

Usage examples

Move some posts to the end of the results when using a Search facet

This hook is most useful if you need to manipulate or have access to one of the above-mentionedquery arguments, which are added or changed after processing facet selections.

The most obvious one is post__in which contains all post IDs in the filtered results.

The post IDs in post__in will not be in the order that they are in the results, which is determined by the orderby argument. However, in some situations, the orderby argument is set to 'orderby' => 'post__in'. This happens when a Search facet is in use and its “Order by relevance” setting is enabled, or when a Proximity facet is in use and it is ordering the results by distance.

The following example shows how to make use of this. The code moves the post IDs in the array on line 7 to the end of the filtered results, if a Search facet is in use that has its “Order by relevance” setting enabled.

This example only works when the listing name is my_listing_template, as set in line 3. You could change this condition to use the page URI instead, by using $class->http_params['uri']. See the facetwp_query_args page for some examples.

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_filter( 'facetwp_filtered_query_args', function( $query_args, $class ) {

  if ( 'my_listing_template' == $class->ajax_params['template'] ) { // Change 'my_listing_template' to the name of your listing.

    if ( ! empty( $query_args['post__in'] ) && isset( $query_args['orderby'] ) && $query_args['orderby'] === 'post__in' ) {

      $move_to_last = [ 12875, 12748, 15678 ]; // Move these post IDs to the end of the results.

      foreach ( $move_to_last as $post_id ) {
        $key = array_search( $post_id, $query_args['post__in'] );
        if ( $key !== false ) {
          array_splice( $query_args['post__in'], $key, 1 );
          $query_args['post__in'][] = $post_id;
        }
      }

    }
  }
  return $query_args;
}, 10, 2 );

More examples

See also

Last updated: April 24, 2026