What are facets?

Facets are UI elements used to filter, or “drill down”, content listings. Facets are aware of the content, and only relevant choices are displayed.

FacetWP offers many different facet types, such as checkboxes, dropdowns, etc. Some facet types are built-in, others you have to install as add-on plugins.

Create a facet

Browse to Settings > FacetWP, then click on “Add New” beside the Facets header. FacetWP includes a sample facet (Categories) to help get you started.

Set facet options

Each facet has its own set of options (which vary depending on the facet type).

Here’s an example of a facet edit screen:

Naming your facets

One thing to keep in mind when choosing a name for your facets, is that WordPress has many reserved terms and reserved query variables. Giving your facet one of these reserved names will cause unexpected behavior.

For example, we have had users with a facet named “name”, which is a reserved term. Changing the name to “first_name” (and re-indexing afterward) fixed their issues. Similarly, don’t name your facet “length”; it will cause issues with certain JavaScript code.

Build the index

Re-index buttonAfter you have saved your facets, click the Re-index button.

This may take a few minutes depending on how much content exists on your site, so please be patient. The progress bar below the button will refresh every few seconds with the percentage completed.

It is not necessary to keep the page open while the indexer is running. If the page is closed, indexing will still finish but it might take a bit longer.

Display a facet

Copy the shortcode

Copy shortcode buttonCopy shortcode in facet overviewAfter creating the facet and setting it’s options, click the red “Copy shortcode” button.

It’s also possible to copy shortcodes directly from the Facets listing screen. Click the cog/gear icon on the right side of the facet’s row and click “Copy shortcode” in the dropdown.

You can also create your shortcode manually, using the facet name (the name in the grey box). Each facet’s shortcode looks like this:

[facetwp facet="the_facet_name"]

Place the shortcode

Place FacetWP shortcode into a WP block editor Shortcode block
How to past a facet or listing shortcode into a WP Shortcode block.

Paste the shortcode into the body field of your page, or into Text widgets (Appearance > Widgets) of – for example – your sidebar.

If you’re using the WordPress block editor, you can also paste shortcodes into a Shortcode block.

Display a facet with PHP

Facets can also be placed directly in your WordPress archive templates, custom templates or includes, with PHP:

echo facetwp_display( 'facet', 'the_facet_name' );

How to duplicate facet

Duplicate, copy or clone a facet Since FacetWP v4.0 it is very easy to clone/duplicate a facet, including all its settings:

Go to Settings > FacetWP and click the Facets tab. On the right side of the row of the facet you want to clone, click the cog/gear icon and click “Duplicate” in the dropdown. This instantly creates a full copy of the facet and its settings, with the label and facet name having the word “copy” added.

You can then change the new facet’s label, name and settings and click “Save changes”. Don’t forget to hit the Re-index button afterwards.

Add a Listing Template

In order for facets to appear, they need to know which posts / query to filter upon.

Facets need what is called a Listing Template. There’s quite a few Listing Template options to choose from.

How to add labels / headings above each facet

FacetWP does not automatically output facet labels / headings, except in the Mobile Flyout menu.

However, it’s possible to add them using a bit of custom code in your (child) theme’s function.php (or use the Custom Hooks add-on). Or place the script part in your theme’s header.php or, better yet, into a custom javascript file.

The code below adds labels to each facet (except to Pager and Sort facets, as labels for those do not make much sense). The code also adds a .facet-wrap wrapper element around each facet and its label, for styling purposes, and to be used in the code snippet below that hides empty facets and their labels.

function fwp_add_facet_labels() {
  ?>
    <script>
      (function($) {
        $(document).on('facetwp-loaded', function() {
          $('.facetwp-facet').each(function() {
            var facet = $(this);
            var facet_name = facet.attr('data-name');
            var facet_type = facet.attr('data-type');
            var facet_label = FWP.settings.labels[facet_name];
            if (facet_type !== 'pager' && facet_type !== 'sort') {
              if (facet.closest('.facet-wrap').length < 1 && facet.closest('.facetwp-flyout').length < 1) {
                facet.wrap('<div class="facet-wrap"></div>');
                facet.before('<h3 class="facet-label">' + facet_label + '</h3>');
              }
            }
          });
        });
      })(jQuery);
    </script>
  <?php
}

add_action( 'wp_head', 'fwp_add_facet_labels', 100 );

How to hide empty facets

The following code hides empty facets (facets with no choices left). It also works for facets in a mobile flyout menu.

The code assumes that each facet has a container element with the CSS class facet-wrap. The above code which adds headings / labels to facets also adds a facet-wrap wrapper, so these two code snippets will work well alongside each other. Put together, facets and their labels will be hidden when the facet is empty.

If you’re using facet shortcodes in separate WP widgets (one for each facet), and you are not using the above code, you can use the widget as wrapper element: in this case replace facet-wrap with widget in the code below.

Show ghosts setting offAlso make sure the targeted facets do not have the “Show ghosts” setting enabled (if you are using Checkboxes, Radio or fSelect facets).

Add this code to your (child) theme’s function.php (or use the Custom Hooks add-on).

add_action( 'wp_footer', function() {
  ?>
    <script>
      (function($) {
        document.addEventListener('facetwp-loaded', function() {
          $.each(FWP.settings.num_choices, function(key, val) {

            // assuming each facet is wrapped within a "facet-wrap" container element
            // this may need to change depending on your setup, for example:
            // change ".facet-wrap" to ".widget" if using WP text widgets

            var $facet = $('.facetwp-facet-' + key);
            var $wrap = $facet.closest('.facet-wrap');
            var $flyout = $facet.closest('.flyout-row');
            if ($wrap.length || $flyout.length) {
              var $which = $wrap.length ? $wrap : $flyout;
              (0 === val) ? $which.hide() : $which.show();
            }
          });
        });
      })(jQuery);
    </script>
  <?php
}, 100 );

See also