Checkboxes

Overview

The checkbox facet type lets users select multiple values.

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.

Hierarchical checkbox behavior

With 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

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

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

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() {
  ?>
    <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:

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() {
  ?>
    <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

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

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-checkbox .facetwp-expand { 
  display: none; 
}

Customize the expand- and collapse buttons

This code example replaces the expand [+] and collapse [-] icons with 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
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:

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

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
/* 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;
}

Style Checkboxes facet choices as toggles

Checkboxes facets are easy to style. Just like in for example Radio facets, the icons are not real HTML (<input type="checkbox">) form elements, but a simple CSS background image applied to a <div>. This background image can be replaced (or removed) with a few lines of CSS.

The following example CSS replaces all checkbox icons with toggle icons:

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
/*
* Free SVG icons used:
* https://fontawesome.com/icons/toggle-off?f=classic&s=solid
* https://fontawesome.com/icons/toggle-on?f=classic&s=solid
* Convert icons to CSS background images: https://www.svgbackgrounds.com/tools/svg-to-css/
* Change icon color: use a hex color in the fill value (%23 = #)
*/

.facetwp-checkbox {
  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" height="1em" viewBox="0 0 576 512"><!--! Font Awesome Free 6.4.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path d="M384 128c70.7 0 128 57.3 128 128s-57.3 128-128 128H192c-70.7 0-128-57.3-128-128s57.3-128 128-128H384zM576 256c0-106-86-192-192-192H192C86 64 0 150 0 256S86 448 192 448H384c106 0 192-86 192-192zM192 352a96 96 0 1 0 0-192 96 96 0 1 0 0 192z" fill="%23777777"/></svg>');
  background-size: 28px 22px;
  background-position: left center;
  padding-left: 36px;
}

.facetwp-checkbox.checked {
  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" height="1em" viewBox="0 0 576 512"><!--! Font Awesome Free 6.4.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path d="M192 64C86 64 0 150 0 256S86 448 192 448H384c106 0 192-86 192-192s-86-192-192-192H192zm192 96a96 96 0 1 1 0 192 96 96 0 1 1 0-192z" fill="%23777777" /></svg>');
}

/* Optional: remove labels: 

.facetwp-checkbox {
  width: 28px;
  height: 22px;
  padding: 0;
}

.facetwp-checkbox .facetwp-display-value,
.facetwp-checkbox .facetwp-counter{
  display: none;
}

*/

In this example we used free FontAwesome icons, but you could use any icon you like. These can be simple PNGs, but for this example we chose SVGs. To be able to use them as CSS background images, we first converted them to data URIs (with this online tool).

The SVG icons’ color can be changed with the fill attribute in the data URI. Note that you need to use %23 instead of # in the HEX color code.

See also

• Why are my value modifiers not working?
• Indexing
• Using FacetWP with WPML or Polylang
• How to find a WordPress term’s ID
• The facetwp_facet_orderby hook
• The Search facet type
• The Autocomplete facet type
• The Radio facet type
• The facetwp_facet_html hook
• Custom Facet Types