Overview

FacetWP Checkboxes facetThe checkbox facet type lets users select multiple values.

Available options

Name Description
Data source Where the values live (taxonomy, custom field, post attribute). When choosing a hierarchical taxonomy, read this warning.
Parent term If the facet’s Data Source is a hierarchical taxonomy and you want to display only child terms of a specific parent, enter the parent’s term ID. (Note: don’t use this in a multilingual setup, because the parent term IDs will be different for each language).
Value modifiers Enter a list of values (one per line, without commas) to include or exclude from the facet’s choices. The values need to match the label (not the slug) of the value exactly, including spaces and capitalization. See the explanation below. If they don’t work, see this page for more info.
Hierarchical Whether to display the facet options visually as a hierarchy, by ordering the child terms below their parent term, indenting the child terms, and by showing [+] / [-] icons to toggle the child levels. This setting only appears if Data Source is set to a taxonomy, and it will only have an effect if the chosen taxonomy is actually a hierarchical taxonomy. Notes:

  • the “Soft limit” setting is not available in combination with the “Hierarchical” setting enabled.
  • If child options don’t show up, make sure the “Count” setting is high enough.
Show expanded This option only appears if the Hierarchical setting is enabled. By default, all child levels will be in the collapsed state and can be expanded with the [+] icons. With this setting enabled, child levels will be expanded all the time. If you want to hide the expand/collapse icons in this case, see the solution below.
Show ghosts Show choices that would return zero results? See the explanation below.
Preserve ghost order Keep ghost choices in the same order (mixed with valid choices)? By default, ghost choices will appear at the bottom.
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:

For custom ways of sorting, for example numerically, you can use the facetwp_facet_orderby hook.

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.
Soft limit The number of options before showing the “See more” link. Set to 0 to display all options. Note: the “Soft limit” option is not available in combination with the “Hierarchical” setting.

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:

Checkboxes facet with value modifiers

What are ghosts?

Checkboxes facet Show ghosts and Preserve ghost order settingsGhosts 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.

Hierarchical checkbox behavior

Checkboxes facet Hierarchical setting enabledWith the “Hierarchical” setting enabled, the facet’s checkbox behavior is as follows:

  • If a parent item is selected, all children on all sublevels of that parent are automatically deselected.
  • If a child item is selected, each parent item on each level above that child item is automatically deselected.
  • If a child item is deselected, each level above it without a selection will collapse.

In other words: parent and child items cannot be selected at the same time and levels will collapse if nothing is selected.

If you want to keep all levels expanded all the time, enable the Show expanded setting. And if you want to automatically expand child items when clicking a parent item, check the code examples below.

Indexing of term hierarchies

Checkboxes hierarchical facet with three levels
Posts with only the Paris term selected in the back-end will be displayed in the front-end results if you select “Europe” or “France” in the facet.

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.

Automatically expand checked hierarchical checkboxes

Checkboxes facet Hierarchical setting enabled and Show expanded setting disabledWith the “Hierarchical” setting enabled and the “Show expanded” setting disabled, clicking a parent item will not expand the child items; only clicking the expand [+] icon will do that.

If you want to automatically expand the direct child items when their parent item is clicked, you can use this code:

<?php
add_action( 'wp_footer', function() {
?>
<script>
document.addEventListener('facetwp-loaded', function() {
    fUtil('.facetwp-checkbox.checked .facetwp-expand').trigger('click');
});
</script>
<?php
}, 100 );

If you want to automatically expand all child items on each sublevel when their parent item is clicked, you can use this code:

<?php
add_action( 'wp_footer', function() {
?>
<script>
document.addEventListener('facetwp-loaded', function() {
    fUtil('.facetwp-checkbox.checked .facetwp-expand, .facetwp-checkbox.checked + .facetwp-depth .facetwp-expand').trigger('click');
});
</script>
<?php
}, 100 );

Hide the expand- and collapse buttons

Checkboxes facet Hierarchical setting enabled and Show expanded setting enabledWith the “Hierarchical” setting enabled and the “Show expanded” setting enabled, all child items of all parents items will be visible by default.

The expand/collapse icons will still keep working: you can collapse each level. However, after each facet interaction (also with other facets), the whole hierarchy will expand again. This makes the expand/collapse icons not very useful in this situation. To hide them, add this CSS into your (child) theme’s style.css:

.facetwp-checkbox .facetwp-expand { 
  display: none; 
}

Customize the expand- and collapse buttons

This code example replaces the expand [+] and collapse [-] icons with text:

add_filter( 'facetwp_assets', function( $assets ) {
    FWP()->display->json['expand'] = '<span>expand</span>';
    FWP()->display->json['collapse'] = '<span>collapse</span>';
    return $assets;
});

Hide counts

To hide the counts for all facets of type Checkboxes, Radio, Hierarchy, and Range List (in UI modes “None”, “Radio” or “Checkboxes”), add this CSS to your (child) theme’s style.css:

.facetwp-counter {
    display: none;
}

If you need to be specific about which (type of) facet to hide the counts for, use any of the following styles:

/* Hide counts in all facets with a checkboxes UI (Checkboxes facet, Range List facet in UI mode "Checkboxes" */
.facetwp-checkbox .facetwp-counter {
    display: none;
}

/* Hide counts in all Checkboxes facets */
[data-type="checkboxes"] .facetwp-counter {
    display: none;
}

/* Hide counts in a specific Checkboxes facet */
.facetwp-facet-yourfacetname .facetwp-counter {
    display: none;
}

See also