Overview

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

Available options

Name Description
Data source Where the values live (taxonomy, custom field, post attribute). When choosing a hierarchical taxonomy, read this warning.
Default label Set the label for the first dropdown option (default: “Any”). Note: this label is translatable with the facetwp_i18n hook. To set a fixed label, see below.
Parent term If Data Source is a hierarchical taxonomy and you want to display only child terms, enter the parent term’s ID.
Value modifiers Enter a list of values (one per line) to include or exclude from the facet’s choices. The values need to match the label of the value exactly, including spaces and capitalization. If they don’t work, see this page for more info.
Hierarchical Whether to indent child terms. If child options don’t show up, make sure the “Count” setting is high enough.
Multi-select If enabled, this facet type will accept multiple selections, and will display a checkbox-style UI.
Show ghosts Show choices that would return zero results?
Preserve ghost order Keep ghost choices in the same order (mixed with valid choices)?
Facet logic Assume a facet with the choices “Apple”, “Banana”, and “Pear”.

  • AND (match all) – if selecting “Apple”, the choices “Banana” and “Pear” will disappear.
  • OR (match any) – if selecting “Apple”, the choices “Banana” and “Pear” will remain. If you select both “Apple” and “Banana”, results matching EITHER will remain.
Sort by Sort facet choices by:

  • Highest count – sorts by the total number of results with that value.
  • Display value – sorts alphabetically according to the label you see on the facet choices.
  • Raw value – sorts by the value that tracks the facet choices. For example in a dropdown, this is the option value rather than the option label. You can see the raw values in the url after making facet selections.
  • Term order – sorts by taxonomy term order. This option uses term_order which is only available when using a plugin that sets an explicit order for taxonomy terms. FacetWP supports:
Count The number of options to display. Be aware that if your source is a hierarchical taxonomy, the count includes the child terms/categories. If the count is too low, (some) child options will not show up.

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 content, then it will never appear.

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.

The values you enter in a facet’s “Value modifiers” field need to match the label of the value exactly, including spaces and capitalization. If they don’t work, see this page for more info.

Hide 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:

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:

add_filter( 'facetwp_facet_dropdown_show_counts', function( $return, $params ) {
    if ( 'your_facet_name' == $params['facet']['name'] ) {
        $return = false;
    }
    return $return;
}, 10, 2 );

Change the search text

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

add_filter( 'facetwp_render_output', function( $output ) {
  $output['settings']['your_facet_name']['searchText'] = 'Type something'; // default: 'Search'
  return $output;
});

To hide the search box for a specific fSelect facet:

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:

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;
});

Change the number of selections shown

fSelect facet with 3 options selectedIf 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:

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:

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:

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:

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

fSelect facet with a default label and a custom overflow text
Single-select fSelect facet with a Default “Any” label and a custom overflowText “Please select a choice”

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

Single select fSelect facet with custom active option styling
Single select fSelect facet with custom 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:

.facetwp-type-fselect .fs-wrap.single .fs-option.selected {
    background-color: #f8f8f8; /* light gray */
    font-weight: bold;
}

Indent hierarchical checkboxes

Multi-select hierarchical fSelect facet with custom CSS for indented checkboxes
Multi-select hierarchical fSelect facet with custom CSS for indented 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:

.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 custom-fselect class. If you want a single-select fSelect (without checkboxes), leave out the multiple="multiple" attribute:

<select class="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:

<?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('.custom-fselect');
      });
    </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.

See also