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).
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 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.

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.

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.

Limit the number of results

By default, a Search facet returns a maximum of 200 results. This maximum can be changed by using the facetwp_search_query_args hook to change the posts_per_page query parameter:

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; // Show all search results
  return $search_args;
}, 10, 2 );

Include draft posts

Similar to the previous example, you can 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 same hook can 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 );

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
• 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