Search

Overview

Allow users to filter content by keyword(s).

Available options

Name	Description
Search engine	Which search engine to use (extra engines appear if SearchWP or our Relevanssi integration add-on is installed). The default “WP Default” engine uses WP core search.
Placeholder text	The placeholder text that appears within the input box (default: “Enter keywords”). Note: this text is translatable with the facetwp_i18n hook. The default text is also translatable with a translation plugin or a WordPress gettext filter (see this example).
Auto refresh	If enabled, the facet will start auto-refreshing the results as soon as the user starts typing, at the first character entered in the field. It is possible to delay auto-refreshing until a certain number of characters have been entered.
Order by relevance	By default, when a Search facet is in use (without also using a Sort facet) the results are automatically ordered by relevance (using 'orderby' => 'post__in'). Disable this setting to use the original listing query order instead. Note that ordering by relevance can also be disabled with a hook.

What gets searched and how?

By default, Search facets use the “WP Default” search engine, which is WordPress core search. For more flexibility, you can use FacetWP’s SearchWP or Relevanssi integration.

For searching in short data items only, you could consider using an Autocomplete facet instead.

Note that by default, when using a Search facet, the number of search results are limited for performance reasons. The exact limit depends on the chosen Search engine and can be removed or customized.

Using default WordPress core search

WordPress core search is pretty limited: it searches the post title, excerpt, and post content, but nothing else. It has no understanding of relevancy, and no search logic options: it matches search terms with AND logic.

You can exclude search terms though, by prepending them with a - sign. For example, searching apples -pears will result in posts that match apples but not pears. The - exclusion sign can be customized with the wp_query_search_exclusion_prefix hook.

WP core search behavior can be customized with the posts_search hook. For example, you can limit it to only search in post titles.

Also good to know is that WordPress search has a default list of so-called “stopwords” that will be ignored. At the time of writing, this list is:

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
// See get_search_stopwords() in: includes/class-wp-query.php
_x(
  'about,an,are,as,at,be,by,com,for,from,how,in,is,it,of,on,or,that,the,this,to,was,what,when,where,who,will,with,www',
  'Comma-separated list of search stopwords in your language'
);

This list is a gettext (__()) translatable string, making it possible to set another set of stopwords in your site’s language. You can also add or remove stopwords from the stopwords array (which is constructed from the above string), with the wp_search_stopwords hook.

Using SearchWP or Relevanssi

If you need more flexibility, FacetWP integrates with both SearchWP (built-in) and Relevanssi (with an add-on). Both plugins let you search other data (custom fields, taxonomy terms, PDF content, etc) too. They each offer many settings and add-ons to make search results more relevant, change the search logic (e.g. to OR logic), and enable quoted/exact search or boolean search.

After installing SearchWP, or Relevanssi and the Relevanssi add-on, the available new engine choices will appear in Search facets’ Search engine setting.

Search in a custom field, taxonomy or post type attribute only

If you only want to search in a custom field, taxonomy or post type attribute, you could consider using an Autocomplete facet instead of a Search facet.

The Autocomplete facet is a search box that automatically displays suggestions as you type. It is not a “true” search; it’s meant for searching short data items like last names or SKU’s of products, and is less suited for searching longer phrases like post titles. It is not suited for searching post content.

Customize or remove the post limit

By default, when using a Search facet, the number of search results are limited for performance reasons. The exact limit depends on the chosen Search engine and can be removed or customized:

Customize the post limit for the WP Default engine

When using the “WP Default” search engine, a Search facet returns a maximum of 200 results. With the facetwp_search_query_args hook, you can remove or customize this limit.

Add the following code to your (child) theme’s functions.php to change the posts_per_page value. If you use -1, the number of results will not be limited, and all results will be retrieved. Be aware that doing this may harm performance if your listing template query has a high number of posts.

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_search_query_args', function( $search_args, $params ) {
  $search_args['posts_per_page'] = -1; // Default: 200. Set to -1 to show all search results.
  return $search_args;
}, 10, 2 );

Customize the post limit for a SearchWP engine

If you are using SearchWP and your Search facet has a SearchWP engine set, the number of results is limited to 200 by default. This post limit can be removed or customized.

Customize the post limit for the Relevanssi engine

If you are using Relevanssi and have the FacetWP Relevanssi add-on installed, and your Search facet has Relevanssi set as its engine, the number of results is limited to 500 by default. This post limit can be removed or customized.

Include draft posts

The following example shows how to force draft posts to appear in the search results by adding them to the post_status query argument with the facetwp_search_query_args hook:

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_search_query_args', function( $search_args, $params ) {
  $search_args['post_status'] = [ 'publish', 'draft' ];
  return $search_args;
}, 10, 2 );

Exclude posts from search results

The facetwp_search_query_args hook hook can also be used to add a post__not_in query argument to prevent certain posts from showing up in the search results:

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_search_query_args', function( $search_args, $params ) {
  $search_args['post__not_in'] = [ 893,894 ]; // The post ID(s) to exclude from the search results
  return $search_args;
}, 10, 2 );

Customize WP core search results

WordPress core search searches the post title, excerpt, and post content. To customize the default behavior of WP core search, you can use the posts_search filter, which filters the search SQL that is used in the WHERE clause of WP_Query.

The following examples show how to search only post titles.

Search only post titles

To let WP core search search only in post titles, add the following code to your (child) theme’s functions.php.

This example will limit the search globally: both on the site’s default search results page (with /?s=keyword in the URL), as when using a Search facet with its engine set to “WP Default”.

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
// Search by Post title only - Search results page and when using a Search facet
// Example from https://developer.wordpress.org/reference/hooks/posts_search/#comment-2213
add_filter( 'posts_search', function( $search, $wp_query ) {
  global $wpdb;

  if ( empty( $search ) ) {
    return $search; // skip processing - no search term in query
  }

  $q = $wp_query->query_vars;
  $n = ! empty( $q['exact'] ) ? '' : '%';
  $search = '';
  $searchand = '';

  foreach ( (array) $q['search_terms'] as $term ) {
    $term = esc_sql( $wpdb->esc_like( $term ) );
    $search .= "{$searchand}($wpdb->posts.post_title LIKE '{$n}{$term}{$n}')";
    $searchand = ' AND ';
  }

  if ( ! empty( $search ) ) {
    $search = " AND ({$search}) ";
    if ( ! is_user_logged_in() ) {
      $search .= " AND ($wpdb->posts.post_password = '') ";
    }
  }

  return $search;

}, 500, 2 );

To only search in post titles when using a Search facet, you need to wrap the above code in a facetwp_search_query_args hook, which only runs when a Search facet is in use:

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
// Search by Post title only - Only when using a Search facet
add_filter( 'facetwp_search_query_args', function( $search_args, $params ) {

  // Example from https://developer.wordpress.org/reference/hooks/posts_search/#comment-2213
  add_filter( 'posts_search', function( $search, $wp_query ) {
    global $wpdb;

    if ( empty( $search ) ) {
      return $search; // skip processing - no search term in query
    }

    $q = $wp_query->query_vars;
    $n = ! empty( $q['exact'] ) ? '' : '%';
    $search = '';
    $searchand = '';

    foreach ( (array) $q['search_terms'] as $term ) {
      $term = esc_sql( $wpdb->esc_like( $term ) );
      $search .= "{$searchand}($wpdb->posts.post_title LIKE '{$n}{$term}{$n}')";
      $searchand = ' AND ';
    }

    if ( ! empty( $search ) ) {
      $search = " AND ({$search}) ";
      if ( ! is_user_logged_in() ) {
        $search .= " AND ($wpdb->posts.post_password = '') ";
      }
    }

    return $search;

  }, 500, 2 );


  return $search_args;
}, 10, 2 );

Disable order by relevance

By default, when a Search facet is in use (without also using a Sort facet) the results are automatically ordered by relevance (using 'orderby' => 'post__in').

To disable this feature and restore the original listing query order, you can use the “Order by relevance” setting (which is available since FacetWP v4.3).

This feature can also disabled programmatically, by adding the following hook 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_use_search_relevancy', '__return_false' );

Note that if you use this hook in this way (returning false), it will overrule the “Order by relevance” Search facet setting.

Search facets and WooCommerce Catalog visibility settings

If you have a Search facet on a template that queries WooCommerce products, and you are using the “Catalog visibility” settings to influence if products show up in the search results or not, be aware that these settings are ignored when using a Search facet.

If you need these settings to work for a Search facet results, read this guide.

Add a “Clear” button to a Search facet

Currently, Search facets do not have a “Clear” button or icon.

If you want to add a clear button/icon to a Search facet’s input box, check out our tutorial on how to accomplish that.

Start auto-refresh only after certain number of typed characters

When the Auto-refresh setting is enabled, the Search facet will start auto-refreshing the results as soon as the user starts typing, at the first character entered in the field.

If you want to delay auto-refreshing until a certain number of characters have been entered, add the following code to your (child) theme’s functions.php.

The “trigger character” in this example is 3, meaning that the facet will start auto-refreshing the moment the 3rd character is entered. You can change this number in line 8.

If the code does not work, make sure that Auto-refresh is enabled.

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
// First enable auto-refresh in your Search facet!
add_action('facetwp_scripts', function () { ?>
  <script>
    document.querySelector(".facetwp-type-search").addEventListener("keyup", function(e) {
      if ('object' !== typeof FWP || FWP.is_refresh) {
        return;
      }
      var trigger = 3; // Start auto-refreshing at this number of characters
      e.stopPropagation();
      var $facet = fUtil(this).closest('.facetwp-facet');
      var facet_name = $facet.attr('data-name');
      var sel = this.querySelector('input').value;

      if ('undefined' !== typeof FWP.settings[facet_name]) {
        if ('yes' === FWP.settings[facet_name]['auto_refresh'] && !( trigger > sel.length && 0 < sel.length ) ) {
          FWP.logic.search['delay_refresh'](facet_name);
        }
        else if (13 === e.keyCode) {
          FWP.autoload();
        }
      }
    });
  </script>
<?php }, 1);

Add search suggestions below a Search facet

To add search suggestions (or “popular searches”) below a Search facet, check out our tutorial on how to accomplish that.

The code in the tutorial can be combined with the code in the “Clear button” tutorial mentioned above

Display an “x results found for [keywords]” message

If you have a Search facet on the page, it is possible to display an “x results found for [keywords]” message when the facet is in use.

To do so, first create a Pager facet and set it to the Result counts type. In the settings, use the available placeholders to set it up to display as: “x results”, or “x of y results”, and add the facet to the page.

Next, add the following snippet to your (child) theme’s functions.php. Make sure to replace my_search_facet in line 7 with the name of your Search facet. When the Search facet is in use, the code will append the ” found for [keywords]” text to the Pager facet’s text, wrapped in a <span> tag:

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( 'facetwp_scripts', function() {
  ?>
  <script>
    document.addEventListener('facetwp-loaded', function() {

      var foundtext = '<?php echo facetwp_i18n(__('found for', 'fwp-front')); ?>';
      var selected_choices = FWP.facets['my_search_facet']; // Replace "my_search_facet" with the name of your facet
      var updatedElement_choices = document.querySelector('.facetwp-facet-pager_resultcounts');

      if ( selected_choices && updatedElement_choices ) {
        if ( selected_choices.length ) { // If there are keywords
          var newSpan = document.createElement('span');
          newSpan.textContent = ' ' + foundtext + ' "' + selected_choices + '"';
          updatedElement_choices.appendChild(newSpan);
        }
      }

    });
  </script>
  <?php
}, 100 );

Display the Search facet at full width

By default, the Search facet displays at 240px width. To display it at 100% width of its container, add the following code to your (child) theme’s functions.php. The CSS also works for Proximity facets:

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() {
  ?>
  <style>
    .facetwp-facet input.facetwp-search,
    .facetwp-facet input.facetwp-location,
    .facetwp-input-wrap {
      width: 100%;
    }
  </style>
  <?php
}, 100 );

See also

• Using FacetWP with SearchWP
• Using FacetWP with Relevanssi
• Using FacetWP with ElasticPress
• Using the facetwp_i18n hook to translate facet labels and strings
• The Autocomplete facet type
• The facetwp_search_query_args hook
• Redirect a search box to a FacetWP results page
• How to filter WP attachments and draft, pending or private posts
• How to link filtered products to WooCommerce product variations
• The Sort facet type
• Using FacetWP with WooCommerce
• How to add a “Clear” button to a Search facet
• Add search suggestions below a Search facet
• Using FacetWP with Stock status and Catalog visibility settings