fUtil is a small JavaScript helper library that comes built-in with FacetWP.

Its functionality is similar to jQuery, with the difference that fUtil relies entirely on modern, vanilla JavaScript. fUtil is less than 2KB minified, very small compared to jQuery + Migrate which adds up to ~35KB.

fUtil can be used as a lightweight substitute on websites that don’t need or load jQuery. FacetWP itself does not need jQuery to function (since v3.8), and you can disable loading it in FacetWP’s settings if your theme or other plugins don’t need it.

fUtil methods

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of 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
* fUtil library
* 
* Unless stated, methods return the fUtil instance
*/

// document.ready handler
$(function() { ... })

// select the document
$()

// get an element
$(selector)
// or
fUtil(selector)

// create a new fUtil instance
$(selector).clone()

// get the number of matching elements (returns int)
$(selector).len()

// add CSS class
$(selector).addClass(val)

// remove CSS class
$(selector).removeClass(val)

// has CSS class
$(selector).hasClass(val)

// toggle CSS class
$(selector).toggleClass(val)

// check for a match (returns bool)
$(selector).is(selector)

// check for a match
$(selector).find(selector)

// get first matching element
$(selector).first()

// get last matching element
$(selector).last()

// get previous matching element
$(selector).prev(selector)

// get next matching element
$(selector).next(selector)

// prepends selected element(s) with a value
$(selector).prepend(val)

// appends selected element(s) with a value
$(selector).append(val)

// get selected element(s) parents
$(selector).parents(selector)

// get selected element(s) closest parents
$(selector).closest(selector)

// remove current element(s)
$(selector).remove()

// adds event listener
$(selector).on('action', callback)

// removes event listener
$(selector).off('action', callback)

// trigger an event
$(selector).trigger('action', callback, extraData)

// set an attribute
$(selector).attr(name, val)

// set data values
$(selector).data(key, val)

// set HTML
$(selector).html(val)

// set text value
$(selector).text(val)

// set input value
$(selector).val(val)

// get all matching DOM nodes (returns array of DOM nodes)
$(selector).nodes

// get first matching DOM node (returns DOM node)
$(selector).nodes[0]

// make an ajax POST
$.post(url, data, settings)

// check if a value or variable exists
$.isset(var)

// loop through an iterable
$.each(items, callback)

Usage examples

Do something on document ready:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of 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
(function($) {
  $(function() {
    console.log('document ready');
  });
})(fUtil);

Remove the is-loading class from all “facet-wrap” elements:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of 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
$('.facet-wrap').removeClass('is-loading');

Prepend “Name: ” to all elements with class “the-name”:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of 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
$('.the-name').prepend('Name: ');

Loop through text inputs (class my-input) and, if empty, remove the closest .item parent:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of 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
$('.my-input').each(function() {
  if ('' == $(this).val()) {
    $(this).closest('.item').remove(); // adios!
  }
});

Add fUtil code with the facetwp_scripts hook

The fUtil library is only loaded on pages where FacetWP is loaded (pages with facets). It loads in the footer, included in FacetWP’s minified front.min.js script.

Custom code that uses fUtil can also best be loaded in the footer, with the facetwp_scripts hook. This hook also runs only on pages where FacetWP is loaded, so custom code added with it will never cause fUtil not defined errors. Depending on the exact code, these errors could happen if you would use the wp_footer hook, which runs on every page.

The following example uses the facetwp_scripts hook to add CSS and fUtil JavaScript code to the footer. The code adds a template-loading class to the listing template while it is loading. The CSS then fades the template out when a facet is clicked, and back in when the results have loaded:

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() {
  ?>
  <style>
    .facetwp-template {
      opacity: 1;
      transition: opacity 0.2s ease-out;
    }
    .facetwp-template.template-loading {
      opacity: 0;
    }
  </style>
  <script>
    (function($) {
      document.addEventListener('facetwp-refresh', function() {
        if ( FWP.loaded ) {
         $( '.facetwp-template' ).addClass( 'template-loading' );
        }
      });
      document.addEventListener('facetwp-loaded', function() {
        $( '.facetwp-template' ).removeClass( 'template-loading' );
      });
    })(fUtil);
  </script>  
  <?php
}, 100 );

Note: see this tutorial for more info about fading the listing template on refresh.

The dollar sign as alias for fUtil()

Just like in jQuery where the $ sign is an alias for the jQuery() function, in fUtil, the $ sign is an alias for the fUtil() function.

This means that the JavaScript part from the previous example can also be written like this:

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>
    document.addEventListener('facetwp-refresh', function() {
      if ( FWP.loaded ) {
        fUtil( '.facetwp-template' ).addClass( 'template-loading' );
      }
    });
    document.addEventListener('facetwp-loaded', function() {
      fUtil( '.facetwp-template' ).removeClass( 'template-loading' );
    });
  </script>
  <?php
}, 100 );

Use fUtil on non-FacetWP pages

As fUtil’s functionality is quite similar to jQuery, you can use it as a lightweight substitute on websites that don’t need or load jQuery. FacetWP itself does not need jQuery to function and you can disable loading it in FacetWP’s settings if your theme or other plugins don’t need it.

However, by default, the fUtil library is only loaded on pages where FacetWP is loaded (pages with facets). It loads in the footer, included in FacetWP’s minified front.min.js script. This means that you can’t use it on other, non-FacetWP pages.

To use fUtil on other pages too, you can add the following snippet to your (child) theme’s functions.php. It makes the fUtil library load independently, in the <head> section of all non-FacetWP pages:

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_enqueue_scripts', function() {
  if ( function_exists( 'FWP' ) && empty( FWP()->display->load_assets ) ) {
    wp_enqueue_script( 'futil', plugins_url( 'facetwp/assets/vendor/fUtil/fUtil.js' ), array(), FACETWP_VERSION, false );
  }
} );

When the fUtil library is available like this on all pages, instead of adding your custom fUtil code with the facetwp_scripts hook (which only runs on pages with facets), you can now better add it with the wp_footer hook, which also runs on all pages.

Note that on pages with facets, with the above snippet in place, the fUtil library is still loaded in the footer, included in front.min.js script.

Other custom JS libraries included with FacetWP

Besides fUtil, FacetWP includes the following other custom lightweight helper libraries that you can use for your custom code:

  • fSelect – used in fSelect facets.
  • fDate – our date-picker library, used in the Date Range facet.
  • fTip – our tooltip library to replace jquery-powertip.
  • fComplete – our autocomplete library to replacejquery-autocomplete. It is used in the Autocomplete facet.
  • nummy – our number formatting library.

More examples

See also