Overview

This hook is useful if FacetWP is unable to auto-detect the correct query (such as when there’s a custom query on a page).

This hook is not relevant for shortcode templates (made with the Listing Builder).

Parameters

  • $is_main_query | boolean | Whether FacetWP should use the current query
  • $query | object | The WP_Query object

How it works

On WP archive templates, or when using a custom WP Query, FacetWP will automatically try to find the right query. FacetWP uses the following logic to determine whether a query should be 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
$is_main_query = ( $query->is_archive || $query->is_search || ( $query->is_main_query() && ! $query->is_singular ) );

FacetWP uses the first query that matches the above criteria. While this works great most of the time, we understand that this won’t work 100% of the time with all themes. This hook is useful when the above logic isn’t sufficient.

Forcing a custom query

Let’s say we have a custom WP_Query on a page that FacetWP isn’t able to auto-detect.

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
$args = [
  'post_type' => 'event',
  'posts_per_page' => 10,
  'facetwp' => true, // we added this
];
$query = new WP_Query( $args );

By adding facetwp => true to the query arguments, FacetWP will use this query for filtering unless another query has already been chosen.

How to ignore archive queries

On WP archive pages (such as post type archives, category, term or /shop/ archives), FacetWP by default will always prioritize the archive query ahead of any other query on the page.

If you are using a custom WP Query or a Listing Builder listing template on a WP archive page, you have to tell FacetWP explicitly which query (not) to use, otherwise unexpected things will happen.

Using this hook, it is possible to force FacetWP to ignore the archive query, and use the custom query or Listing Builder listing query instead. Add the following code to 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_is_main_query', function( $is_main_query, $query ) {
  if ( $query->is_archive() && $query->is_main_query() ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 10, 2 );

How to ignore archive queries conditionally

If you need to ignore the archive query only on specific archive templates, you can apply the above code conditionally:

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_is_main_query', function( $is_main_query, $query ) {

  $uri = FWP()->helper->get_uri();
  $is_desired_page = in_array( $uri, [ 'some/page', 'some/other/page', 'also/this/page'] );

  if ( $query->is_archive() && $query->is_main_query() && $is_desired_page ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 10, 2 );

For the condition, you can also use regular WordPress conditional tags, for example is_category('events').

How to ignore other queries

In some cases, FacetWP’s automatic query detection latches on to the wrong query on the page. This example tells FacetWP to ignore queries with the post_type set to tribe_events:

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_is_main_query', function( $is_main_query, $query ) {
  if ( 'tribe_events' == $query->get( 'post_type' ) ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 10, 2 );

Disable automatic query detection

FacetWP will automatically try to detect the right query on the page. If you want to disable this feature, and only allow explicitly set queries, add the following code to 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_is_main_query', function( $is_main_query, $query ) {
  if ( true !== $query->get( 'facetwp', false ) ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 10, 2 );

With this code in place, queries must be explicitly set to enable FacetWP. This happens when:

Enable “Strict query detection” with PHP

Enable Strict query detection in FacetWP's settings.
Enable Strict query detection in FacetWP’s settings.

FacetWP’s “Strict query detection” setting prevents FacetWP’s automatic query detection from incorrectly using (invisible) archive queries on the page. As its name implies, this setting uses a stricter way of detecting the right query, which in most cases will solve the issue.

The setting is enabled by default in versions newer than v4.2.3. Keep this setting enabled unless you have a specific reason to disable it, or you are instructed to do so in support.

If you want to “enable” this setting with PHP, you can add the following code to your (child) theme’s functions.php. The code does the same as the setting:

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_is_main_query', function( $is_main_query, $query ) {
  if ( $query->is_archive() && ! ( $query->is_main_query() || true === $query->get( 'facetwp', false ) ) ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 100, 2 );

More examples

See also

Last updated: May 22, 2025