fSelect

Overview

The fSelect facet type generates a dropdown combo-box. It supports multi-select, and also includes a search box to narrow choices.

Available options

What are value modifiers?

Value modifiers let you include or exclude certain choices from displaying. This setting requires a re-index to take effect.

Below are some examples:

What are ghosts?

Ghosts are facet choices that do appear in the unfiltered results, but disappear after being filtered out. If a facet choice has no associated posts, then it will never appear.

When “Show ghosts” is enabled, after filtering, facet choices that would return zero results are still shown, but dimmed and not clickable.

By default, the ghosts will appear at the bottom of the list of choices. If you enable “Keep ghost order”, the ghost choices will be shown in the original order (mixed with the other, valid choices), determined by the “Sort by” setting.

Note that if you set the “Facet logic” setting to “OR (match any)”, there will never be ghosts, with one exception: when performing a Search facet search that returns no results.

Indexing of term hierarchies

With the “Hierarchical” setting enabled, FacetWP automatically indexes both explicit and implicit term hierarchies.

If your taxonomy includes Europe > France and a post has only the France term selected, then Europe will get indexed too for that post.

On the front-end this means that if you have a post that has only the Paris term selected, but not its parent terms (France or Europe), the post will still be displayed in the results if you filter by “Europe”, or “France” in the facet.

Hide or customize the counts

Hide the counts

To hide counts from all facets of a type that use a dropdown UI (all fSelect facets, Dropdown facets, Hierarchy Select facets, and Range List facets (in dropdown or fSelect UI mode)), add the following to your 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_facet_dropdown_show_counts', '__return_false' );

If you want to hide counts from specific facets with a dropdown UI, then use this instead:

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_facet_dropdown_show_counts', function( $return, $params ) {
  if ( 'your_facet_name' == $params['facet']['name'] ) {
    $return = false;
  }
  return $return;
}, 10, 2 );

Style the counts

If you need to style the counts differently, or change the HTML, see the example code below that adds a <span> around the counts so you can style them easily with CSS.

Change the search box text

To change the placeholder text in the search box, use this code:

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_render_output', function( $output ) {
  $output['settings']['your_facet_name']['searchText'] = 'Type something'; // default: 'Search'
  return $output;
});

Change the “No results found” text

To change the “No results found” text, use this code:

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_render_output', function( $output ) {
  $output['settings']['your_facet_name']['noResultsText'] = 'Nothing found'; // default: 'No results found'
  return $output;
});

Hide the search box

To hide the search box for a specific fSelect 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_filter( 'facetwp_render_output', function( $output ) {
  $output['settings']['your_facet_name']['showSearch'] = false;
  return $output;
});

To hide the search box for all current and future fSelect 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_filter( 'facetwp_render_output', function( $output ) {
  $facets = FWP()->helper->get_facets();
  foreach ( $facets as $facet ) {
    if ( 'fselect' == $facet['type'] ) {
      $output['settings'][ $facet['name'] ]['showSearch'] = false;
    }
  }
  return $output;
});

You can also hide the search box with CSS. The advantage to above solutions would be that you can use a mediaquery to hide it only on specific device widths, like on mobile:

How to use custom CSS?
CSS code can be placed in your (child) theme's style.css file. Alternatively, you can add it manually between <style> tags in the <head> section, in 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. More info
@media screen and (max-width: 767px) {
  .facetwp-type-fselect .fs-search {
      display: none;
  }
}

Search box auto-focus on open

When an fSelect facet is clicked open, the focus is automatically put on the search input field. However, on touch devices this behavior would directly open the keyboard, which can be annoying to users. Because of this, on touch devices only, we removed this auto-focus behavior so the keyboard will only open when the user clicks in the Search field itself.

Change the number of selections shown

If the “Multi-select” setting is active, the facet shows a “{number} selected” label if the number of selected options is 4 or more. This number can be changed with the numDisplayed setting.

If you change this setting from the default 3 to 2, the ‘{num} selected’ label will show up when a user selects 3 or more options:

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_render_output', function( $output ) {
  $output['settings']['your_facet_name']['numDisplayed'] = 2; // default: 3
  return $output;
});

Show all selections

To always show all selections and prevent the “{number} selected” message from showing up, you can set numDisplayed to a very high number:

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_render_output', function( $output ) {
  $output['settings']['your_facet_name']['numDisplayed'] = 100;
  return $output;
});

Change the overflow text

To change the text for the “{number} selected” label, you can use the following code:

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_render_output', function( $output ) {
  $output['settings']['your_facet_name']['overflowText'] = '{n} chosen'; // default: '{n} selected'
  return $output;
});

Set a custom fixed label

The default behavior of an fSelect dropdown is to show the active choice(s) as its label. If you want to always display the same, custom label, no matter which option is chosen, you can add the following code to your (child) theme’s functions.php, and adapt the text:

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
// Replace 'my_fselect_facet' with your fSelect facet name 3 times, and adapt the text.
add_filter( 'facetwp_render_output', function( $output ) {
  if ( isset( $output['settings']['my_fselect_facet'] ) ) {
    $output['settings']['my_fselect_facet']['overflowText'] = 'Please select a choice';
    $output['settings']['my_fselect_facet']['numDisplayed'] = 0;
  }
  return $output;
});

Note that this overflowText normally is the text shown when the number of selected options is more than the number set in the “numDisplayed” option. The above code makes this text always visible by setting numDisplayed (the number of selections to show in the label) to 0.

The label created in this way is something else than the “Default label” in the facet’s settings. That label is shown when no choices are made.

If you are adding a custom fixed label on a multi-select fSelect facet, it would make sense to make the text for the “Default label” the same as the text set in the code above.

However, on a single-select fSelect facet the behavior is slightly different: with the above code to set a custom fixed label, that label will also be shown when no choices are made. In this situation leaving the Default label set to “Any” makes the most sense, as on single-select fSelect facets the Default label is also shown above the dropdown options, as a way to reset the chosen option.

Customize single select active option styling

If the “Multi-select” setting is disabled, the single selected option gets a light blue background.

To change the background color, and other styles, you can use the following CSS. This example adds a light gray background and bold text to the selected option:

How to use custom CSS?
CSS code can be placed in your (child) theme's style.css file. Alternatively, you can add it manually between <style> tags in the <head> section, in 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. More info
.facetwp-type-fselect .fs-wrap.single .fs-option.selected {
  background-color: #f8f8f8; /* light gray */
  font-weight: bold;
}

Indent hierarchical checkboxes

If you have enabled the “Multi-select” and “Hierarchical” settings, by default the child options will indent, but the checkboxes will stay aligned to the left.

If you want the checkboxes to indent together with the child options, you can use the following CSS:

How to use custom CSS?
CSS code can be placed in your (child) theme's style.css file. Alternatively, you can add it manually between <style> tags in the <head> section, in 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. More info
.facetwp-facet.facetwp-type-fselect .fs-options .fs-option  .fs-option-label {
  padding-left: 0;
}

.facetwp-type-fselect .fs-option.d1 {
  margin-left: 20px;
}

.facetwp-type-fselect .fs-option.d2 {
  margin-left: 40px;
}

.facetwp-type-fselect .fs-option.d3 {
  margin-left: 60px;
}

Create stand-alone fSelect dropdowns

The built-in fSelect component makes it possible to create a custom (non-facet) fSelect dropdown from any <select> HTML element, on any page of a site with the FacetWP plugin active, also on pages without facets.

The following example assumes a <select> element with a my-custom-fselect class. If you want a single-select fSelect (without checkboxes), leave out the multiple="multiple" attribute:

<select class="my-custom-fselect" multiple="multiple">
  <option>option one</option>
  <option>option two</option>
  <option>option three</option>
</select>

Add the following code to your (child) theme’s functions.php to initiate an fSelect dropdown from the above <select> element:

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
<?php
add_action( 'wp_footer', function() {
  ?>
    <link href="/wp-content/plugins/facetwp/assets/vendor/fSelect/fSelect.css" rel="stylesheet" type="text/css">
    <script src="/wp-content/plugins/facetwp/assets/vendor/fSelect/fSelect.js"></script>
    <script>
      document.addEventListener('DOMContentLoaded', function() {
        fSelect('.my-custom-fselect'); // Replace with the unique class of your <select> element. Use this class on only one element.
      });
    </script>
  <?php
}, 100 );

If you are using this on a page where you already have an fSelect facet, leave out the two lines that include the CSS and JavaScript files, as they will already be included.

Note that the fSelect component works with FacetWP’s built-in fUtil library. It does not need or use jQuery.

Create multiple stand-alone fSelect dropdowns

The above code will not work for multiple stand-alone fSelects with the same class on the same page: they will interact with each other. The solution is to give them each a unique class and instantiate them individually:

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_footer', function() {
  ?>
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      var fselectSelectors = ['.my-custom-fselect1', '.my-custom-fselect2', '.my-custom-fselect3']; // Replace with the unique classes of your <select> elements
      fselectSelectors.forEach(function(selector) {
        fSelect(selector);
      });
    });
  </script>
  <?php
}, 100 );

Customize the fSelect options’ HTML

If you want to customize the fSelect options’ HTML, you can use the facetwp/set_options/fselect hook.

The following example adds a <span> with class facetwp-counter around the option counts:

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
<?php
// Replace 'myfacetname' with the name of your fSelect facet
add_action( 'wp_head', function() {
  ?>
    <script>
      document.addEventListener('DOMContentLoaded', function () {
        if ( 'undefined' !== typeof FWP && 'undefined' !== typeof FWP.hooks) {
          FWP.hooks.addFilter('facetwp/set_options/fselect', function(opts, facet) {
            if (facet.facet_name == 'myfacetname') {
              opts.optionFormatter = function(label, node) {
                var counter = node.getAttribute('data-counter');
                return (counter) ? label + ' <span class="facetwp-counter">' + counter + '</span>' : label;
              };
              return opts;
            }
          });
        }
      });
    </script>
  <?php
}, 100);

With node.getAttribute() you have access to all attributes of each <option>. You can use these to do something with in the HTML of the option label. Available attributes are: value, data-counter, class, and label:

<option value="accessories" data-counter="4" class="d0" label="Accessories">Accessories</option>

The data-counter attribute contains the current count of that option, as used in the above example.

The class attribute has classes like d0, d1, d2 etc. These correspond with the option’s “depth” in the hierarchy, if you are using a hierarchical data source and the “Hierarchical” setting is enabled. These depth classes can also be used to style the hierarchical options.

See also

• Why are my value modifiers not working?
• Using the facetwp_i18n hook to translate facet labels and strings
• Using FacetWP with WPML or Polylang
• The Hierarchy Select facet type
• How to find a WordPress term’s ID
• The facetwp_facet_orderby hook
• The Search facet type
• The Autocomplete facet type
• Using fUtil