User Selections

Overview

The User Selections facet type displays active facet selections as a list, and allows each selection to be unselected individually. The selections are preceded by the facet’s label:

FacetWP User Selections facet — The User Selections facet

The User Selections facet is a good companion for a Reset facet, which resets all choices at once (or, depending on its settings, a selection of facets).

The facet labels that appear before each user selection are translatable with the facetwp_i18n filter.

Usage

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

To add the User Selections facet to your page, add the following shortcode to an HTML or text widget (in Appearance > Widgets), or to a HTML block or shortcode block. Or you can add it directly to your page’s body text:

How to use shortcodes?
Shortcodes can be placed directly in post/page edit screens. You can also add them in text/HTML widgets. The WordPress Block Editor has a Shortcode block to place them in. And most Page builders have a dedicated shortcode module/widget. In PHP templates, shortcodes can be displayed with WP's do_shortcode() function: echo do_shortcode('[my-shortcode]');. More info
[facetwp selections="true"]

To add the facet with PHP, 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
echo facetwp_display( 'selections' )

Add a label above the User Selections

If you want to display a label above the User Selections facet, add the following code to your (child) theme’s functions.php. The label will only be displayed if the user has made selections:

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_head', function() {
  ?>
    <script>
      (function($) {
        $(function() {
          FWP.hooks.addAction('facetwp/loaded', function() {
            $('<p class="selections-label">You selected: </p>').insertBefore('.facetwp-selections ul');
          }, 100 );
        });
      })(jQuery);
    </script>
  <?php
}, 100 );

If you are using a Color facet that uses a taxonomy as data source, by default the term slug is shown as the color name in the User Selections. This color name can be customized or translated.

This behavior is different when you are using Variation Swatches for WooCommerce or WooCommerce Attribute Swatches. In this case, the term name is used in the User Selections, and can also be customized or translated.

Solving issues with User Selections

If the User Selections facet is not showing all selected facet options, or is behaving erratically, make sure you do not have any facets with the name “labels”. This is a reserved word that will cause the User Selections facet to malfunction. In newer versions of FacetWP, if you try to enter “labels” as a name, it will automatically be changed to “labels_” on saving the facet.

Note that in general, there are more reserved terms to avoid when naming your facets.

Since FacetWP v4.5, there are two hooks available to customize which facet types and/or individual facets will be displayed in the User Selections:

By default, all facet types will show up in the User Selections, except Pager, Reset, and Sort facets.

The facetwp/selections/facet_types_skipped hook can be used to customize which facet types are skipped.

The following example removes the sort facet type from the list of skipped facets, and adds the color facet type. So Sort facets, which were previously skipped, will now display their selection in the User Selections facet, and Color facets will no longer.

To change the skipped facets types, just adapt the skipped array in line 12, which by default is: ['pager', 'reset', 'sort'].

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( 'facetwp_scripts', function() {
  ?>
  <script>
    (function($) {
      $(function() {
        if ('object' != typeof FWP) return;

        // Re-add skipped facet types, or skip other facets by facet type.
        // Default = ['pager', 'reset', 'sort']
        // Example: re-add Sort facets and remove Color facets.
        FWP.hooks.addFilter('facetwp/selections/facet_types_skipped', function( skipped ) {
          skipped =  ['pager', 'reset', 'color'];
          return skipped;
        });

      });
    })(fUtil);
  </script>
  <?php
}, 100 );

To customize which individual facets are displayed in the User Selections, use the facetwp/selections/facets hook. This hook filters the selected_facets object, which contains all facets that will be displayed.

The following example removes a facet with the name my_facet from the User Selections:

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( 'facetwp_scripts', function() {
  ?>
  <script>
    (function($) {
      $(function() {
        if ('object' != typeof FWP) return;

        // Customize facets displayed in the User Selections.
        // selected_facets contains an object of all facets to be shown in the User Selections
        // Example: remove the 'my_facet' facet
        FWP.hooks.addFilter('facetwp/selections/facets', function( selected_facets ) {
          delete selected_facets.my_facet;
          return selected_facets;
        });

      });
    })(fUtil);
  </script>
  <?php
}, 100 );

In FacetWP versions older than v4.5, the above facetwp/selections/facets hook is not available, but skipped facets can still be added. The following example shows how to append a specific Sort facet’s selections to the end of the User Selections.

Make sure to replace my_sort_facet with the name of your Sort facet in line 9, and set the desired facet label in line 10:

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
// Use only for FacetWP versions older than v4.5
add_action( 'facetwp_scripts', function() {
  ?>
  <script>
    (function($) {
      $(function() {
        FWP.hooks.addAction('facetwp/loaded', function() {

          const facetname = 'my_sort_facet'; // Replace 'my_sort_facet' with the name of your Sort facet
          const facetlabel = 'Sorted by'; // Set the facet label to be used in the User Selections

          const selected = FWP.facets[facetname];
          if (!selected.length) return;

          $('.facetwp-selections').each(function() {
            const selections = $(this);
            const ul = selections.find('ul').nodes[0] || selections.nodes[0].appendChild(document.createElement('ul'));
            const label = document.querySelector(`.facetwp-facet-sort_testing option[value="${selected}"]`)?.textContent || selected;

            const li = document.createElement('li');
            li.setAttribute('data-facet', facetname);
            li.innerHTML = `<span class="facetwp-selection-label">${facetlabel}: </span><span class="facetwp-selection-value" data-value="${selected}" role="link" aria-label="${label}" tabindex="0">${label}</span>`;
            ul.appendChild(li);
          });

        }, 100);
      });
    })(fUtil);
  </script>
  <?php
}, 100 );

The <ul>/<li> construction of the User Selections facet makes it easy to style.

For example, you could give each facet its own container with its selections, like this:

To accomplish the above look, add the following code to your (child) theme’s functions.php. You may need to tweak it a bit, depending on your theme’s CSS:

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

      .facetwp-selections ul {
          margin: 20px 0;
      }

      .facetwp-selections li {
          display: inline-block;
          margin: 0 6px 6px 0;
          padding: 8px 10px;
          list-style-type: none;
          border: 1px solid #ddd;
          border-radius: 3px;
      }

      .facetwp-selections .facetwp-selection-value {
          color: #6233ca;
      }

      .facetwp-selections .facetwp-selection-value:hover {
          text-decoration: underline;
      }

      .facetwp-selections .facetwp-selection-label + .facetwp-selection-value {
          margin-left: 4px;
      }

      .facetwp-selections .facetwp-selection-value:last-child {
          margin-right: 0;
      }

  </style>
  <?php
}, 100 );

Customize User Selections HTML output

Since FacetWP v4.5 it is possible to customize the output of the HTML of the User Selections facet. This makes it possible to change the HTML tags and classes used, remove parts (like the facet labels), and style the User Selections any way you want.

The following example shows how the default HTML output looks. There are four hooks available to filter/customize each part of this HTML:

facetwp/selections/wrapper_html – Customize the wrapper HTML (the <ul>).
facetwp/selections/facet_selection_html – Customize the facet selection HTML (containing the facet label + facet choices).
facetwp/selections/facet_selection_label_html – Customize the facet label HTML.
facetwp/selections/facet_selection_choice_html – Customize the facet selection choice HTML.


<div class="facetwp-selections">

  <!--  Wrapper-->
  <!--  Hook to change the HTML: facetwp/selections/wrapper_html -->
  <ul>

    <!--  Facets in the User Selections -->
    <!--  Hook to to change skipped facet types: facetwp/selections/facet_types_skipped -->
    <!--  Hook to change facets displayed in the User Selections: facetwp/selections/facets -->

    <!--  Facet selections-->
    <!--  Hook to change the HTML: facetwp/selections/facet_selection_html -->
    <!--  Default HTML:  <li>{selection_content}</li> -->
    <li data-facet="vehicle_type">

      <!--  Facet label-->
      <!--  Hook to to change the HTML: facetwp/selections/facet_selection_label_html -->
      <!--  Default HTML:  <span class="facetwp-selection-label">{selection_label_content}</span> -->
      <span class="facetwp-selection-label">Vehicle Type:</span>

      <!--  Individual choice -->
      <!--  Hook to to change the HTML: facetwp/selections/facet_selection_choice_html -->
      <span class="facetwp-selection-value" data-value="electric" role="link" aria-label="Electric" tabindex="0">Electric</span>

      <!--  Individual choice -->
      <span class="facetwp-selection-value" data-value="suv" role="link" aria-label="SUV" tabindex="0">SUV</span>

    </li>

    <!--  Facet selections-->
    <li data-facet="make">

      <!--  Facet label-->
      <span class="facetwp-selection-label">Make:</span>

      <!--  Individual choice -->
      <span class="facetwp-selection-value" data-value="audi" role="link" aria-label="Audi" tabindex="0">Audi</span>

    </li>

  </ul>

</div>

The facetwp/selections/wrapper_html hook

The facetwp/selections/wrapper_html hook filters the wrapper HTML of the User Selections.

By default, this wrapper HTML is:


<ul>{selections}</ul>

Note that the {selections} part needs to stay intact. Its content can be customized with the three hooks mentioned below.

The following example adds a class selections to the wrapper <ul>, on line 12. You could as easily change the <li> to a <div> or something else.

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( 'facetwp_scripts', function() {
  ?>
  <script>
    (function($) {
      $(function() {
        if ('object' != typeof FWP) return;

        // Customize the wrapper HTML of the User Selections.
        // Default HTML:  <ul>{selections}</ul>
        // Example: add a class
        FWP.hooks.addFilter('facetwp/selections/wrapper_html', function( selections ) {
          selections = '<ul class="selections">{selections}</ul>';
          return selections;
        });

      });
    })(fUtil);
  </script>
  <?php
}, 100 );

The facetwp/selections/facet_selection_html hook filters the facet selection HTML containing the facet label and facet choices, for each facet in the User Selections.

By default, this facet selection HTML is:


<li>{selection_content}</li>

Note that the {selection_content} part needs to stay intact. Its content can be customized with the two hooks mentioned below.

This hook has access to the facet name of the facet selection HTML it filters, with its facet_name parameter. You could use this to only customize the selections HTML for specific facets.

The following example removes the <li> tag around each facet selection, on line 13, but only if the facet’s name is not “my_facet”. You could as easily change the <li> to a <div> or something else.

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( 'facetwp_scripts', function() {
  ?>
  <script>
    (function($) {
      $(function() {
        if ('object' != typeof FWP) return;

        // Customize the HTML of the facet selections container that wraps the facet label and all selections per facet. If needed per facet, based on the facet_name.
        // Default HTML:  <li>{selection_content}</li>
        // Example: Remove <li></li> around selection label + selection choices, but only if the facet name is not 'my_facet'
        FWP.hooks.addFilter('facetwp/selections/facet_selection_html', function( selection, facet_name ) {
          if ( facet_name !== 'my_facet' ) {
            selection = '{selection_content}';
          }
          return selection;
        });

      });
    })(fUtil);
  </script>
  <?php
}, 100 );

The facetwp/selections/facet_selection_label_html hook filters the the facet label HTML, for each facet in the User Selections.

By default, this facet label HTML is:


<span class="facetwp-selection-label">{selection_label_content}</span>

This hook can be used to change the HTML part of the label (the <span> or its class). But you can also use it to change the label text itself, which by default is set dynamically with {selection_label_content}.

The hook has access to the facet name of the facet label HTML it filters, with its facet_name parameter. You could use this to only customize the label HTML for specific facets.

The following example changes the label text of the my_sort_facet facet to “Sorted by: ”, on line 12-13. It entirely removes the label for all other facets, on line 15. You could as easily change the <span> to a <div> or something else.

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( 'facetwp_scripts', function() {
  ?>
  <script>
    (function($) {
      $(function() {
        if ('object' != typeof FWP) return;

        // Customize the facet selection label HTML for all or specific facets. Or remove the label entirely.
        // Default HTML:  <span class="facetwp-selection-label">{selection_label_content}</span>
        // Example: Customize label for the 'my_sort_facet' facet, and remove the label for all other facets.
        FWP.hooks.addFilter('facetwp/selections/facet_selection_label_html', function( selection_label, facet_name ) {
          if ( facet_name == 'my_sort_facet' ) {
            selection_label = '<span class="facetwp-selection-label">Sorted by: </span>'; // Add custom label for Sort facet
          } else {
            selection_label = ''; // Remove label for all other facets
          }
          return selection_label;
        });

      });
    })(fUtil);
  </script>
  <?php
}, 100 );

The facetwp/selections/facet_selection_choice_html hook filters the facet selection choice HTML, for each individual selection of each facet in the User Selections.

This hook can be used to change the HTML of the selection choice, which is passed in the hook’s selection_choice parameter.

The hook has access to the facet name of the facet selection choice HTML it filters, with its facet_name parameter. You could use this to only customize the facet selection choice HTML for specific facets.

The following example wraps each individual selection choice in a <li></li> container, except the selection choice of the my_sort_facet facet. This would be helpful make the selection choices wrap on smaller-width devices, if combined with the removal of the <li></li> container around the facet selection HTML (containing the facet label + facet choices), using the facetwp/selections/facet_selection_html hook. See the section below for a full example.

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( 'facetwp_scripts', function() {
  ?>
  <script>
    (function($) {
      $(function() {
        if ('object' != typeof FWP) return;

        // Customize the HTML of individual facet choices
        // Example: Add <li></li> around individual selection choices instead of around all selections per facet.
        // With an exception for the 'my_sort_facet' facet.
        // Note that you'd also need to remove the <li></li> around the facet selections container, using the facetwp/selections/facet_selection_html hook.
        FWP.hooks.addFilter('facetwp/selections/facet_selection_choice_html', function( selection_choice, facet_name ) {
          if ( facet_name !== 'my_sort_facet' ) {
            selection_choice = '<li>' + selection_choice + '</li>';
          }
          return selection_choice;
        });

      });
    })(fUtil);
  </script>
  <?php
}, 100 );

Style individual selections as single, wrapping items

By default, the User Selections HTML is constructed as an <ul>/<li> list, in which each facet has its own <li> that contains its label and all of its selection.

The result is that the user can clearly see which facet has which selections. But it has one downside: Each facet’s <li> can get quite wide, depending on the number of selections. On smaller-width screens, this <li> will not wrap: it will stay one item. It is impossible to use float: left;, display: inline-block;, or display: flex; to let each individual facet choice wrap as needed.

So on wide and small screens, the User Selections could look something like this:

The default non-wrapping User Selections ul/li construction on wide and small screens.

What you’d probably want in this case is to have each individual selection choice contained in its own <li>, so that the individual items can wrap to the next line. After also removing the facet labels, except for the Sort facet (which would look weird without it), it would then look like this on wide and small screens:

A customized, wrapping User Selections ul/li construction on wide and small screens.

The above image can be achieved with the following code.

For demonstration purposes, in line 8-14 the code first re-adds the Sort facet type (which is skipped by default), using the facetwp/selections/facet_types_skipped hook.

Then, in line 19-24, the facetwp/selections/facet_selection_html hook is used to remove the <li></li> from the HTML of the facet selections container that wraps the facet label and all selections per facet. In this example, we make an exception for the Sort facet, because a Sort facet selection would look weird without its label. It would just say “Price” when it is sorted by price.

Next, in line 29-36, all facet labels are removed, using the facetwp/selections/facet_selection_label_html hook. Except for the Sort facet, which we give a custom label “Sorted by: ”.

Then, in line 42-47, we use the facetwp/selections/facet_selection_choice_html hook to add the <li></li> to the individual selection choices.

Last but not least, we add a bit of custom CSS to style the <li> items with borders, spacing, and to let them wrap individually by setting display: inline-block;.

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( 'facetwp_scripts', function() {
  ?>
  <script>
    (function($) {
      $(function() {
        if ('object' != typeof FWP) return;

        // Re-add skipped facet types, or skip other facets by facet type.
        // Default = ['pager', 'reset', 'sort']
        // Example: re-add Sort facets.
        FWP.hooks.addFilter('facetwp/selections/facet_types_skipped', function( skipped ) {
          skipped =  ['pager', 'reset' ];
          return skipped;
        });

        // Customize the HTML of the facet selections container that wraps the facet label and all selections per facet. If needed per facet, based on the facet_name.
        // Default HTML:  <li>{selection_content}</li>
        // Example: Remove <li></li> around selection label + selection choices, but only if the facet name is not 'my_sort_facet'
        FWP.hooks.addFilter('facetwp/selections/facet_selection_html', function( selection, facet_name ) {
          if ( facet_name !== 'my_sort_facet' ) {
            selection = '{selection_content}';
          }
          return selection;
        });

        // Customize the facet selection label HTML for all or specific facets. Or remove the label entirely.
        // Default HTML:  <span class="facetwp-selection-label">{selection_label_content}</span>
        // Example: Customize label for the 'my_sort_facet' facet, and remove the label for all other facets.
        FWP.hooks.addFilter('facetwp/selections/facet_selection_label_html', function( selection_label, facet_name ) {
          if ( facet_name == 'my_sort_facet' ) {
            selection_label = '<span class="facetwp-selection-label">Sorted by: </span>'; // Add custom label for Sort facet
          } else {
            selection_label = ''; // Remove label for all other facets
          }
          return selection_label;
        });

        // Customize the HTML of individual facet choices
        // Example: Add <li></li> around individual selection choices instead of around all selections per facet.
        // With an exception for the 'my_sort_facet' facet.
        // Note that you'd also need to remove the <li></li> around the facet selections container, using the facetwp/selections/facet_selection_html hook.
        FWP.hooks.addFilter('facetwp/selections/facet_selection_choice_html', function( selection_choice, facet_name ) {
          if ( facet_name !== 'my_sort_facet' ) {
            selection_choice = '<li>' + selection_choice + '</li>';
          }
          return selection_choice;
        });

      });
    })(fUtil) </script>
  <?php
}, 100 );

add_action( 'wp_head', function() {
  ?>
  <style>

    .facetwp-selections ul {
      margin: 20px 0;
    }

    .facetwp-selections li {
      display: inline-block;
      margin: 0 6px 6px 0;
      padding: 8px 10px;
      list-style-type: none;
      border: 1px solid #ddd;
      border-radius: 3px;
    }

    .facetwp-selections .facetwp-selection-value {
      color: #6233ca;
    }

    .facetwp-selections .facetwp-selection-value:hover {
      text-decoration: underline;
    }

    .facetwp-selections .facetwp-selection-label + .facetwp-selection-value {
      margin-left: 4px;
    }

    .facetwp-selections .facetwp-selection-value:last-child {
      margin-right: 0;
    }

  </style>
  <?php
}, 100 );

Search the Help Center

User Selections

Overview

Usage

How to use shortcodes?

How to use custom PHP code?

Add a label above the User Selections

How to use custom PHP code?

User Selections and Color facets

Solving issues with User Selections

Customize the facets or facet types displayed in the User Selections

Customize the facet types displayed in the User Selections

How to use custom PHP code?

Customize the facets displayed in the User Selections

How to use custom PHP code?

How to use custom PHP code?

Styling the User Selections facet

How to use custom PHP code?

Customize User Selections HTML output

The facetwp/selections/wrapper_html hook

How to use custom PHP code?

The facetwp/selections/facet_selection_html hook

How to use custom PHP code?

The facetwp/selections/facet_selection_label_html hook

How to use custom PHP code?

The facetwp/selections/facet_selection_choice_html hook

How to use custom PHP code?

Style individual selections as single, wrapping items

How to use custom PHP code?

See also

In this article

Your site deserves the best filtering

Search the Help Center

User Selections

Overview

Usage

How to use shortcodes?

How to use custom PHP code?

Add a label above the User Selections

How to use custom PHP code?

User Selections and Color facets

Solving issues with User Selections

Customize the facets or facet types displayed in the User Selections

Customize the facet types displayed in the User Selections

How to use custom PHP code?

Customize the facets displayed in the User Selections

How to use custom PHP code?

How to use custom PHP code?

Styling the User Selections facet

How to use custom PHP code?

Customize User Selections HTML output

The facetwp/selections/wrapper_html hook

How to use custom PHP code?

The facetwp/selections/facet_selection_html hook

How to use custom PHP code?

The facetwp/selections/facet_selection_label_html hook

How to use custom PHP code?

The facetwp/selections/facet_selection_choice_html hook

How to use custom PHP code?

Style individual selections as single, wrapping items

How to use custom PHP code?

See also

In this article

Related articles

Your site deserves the best filtering