Overview

With this hook you can modify the display value (the label) of specific facet choices.

This is a very versatile hook. It can for example be used to customize the HTML output of facet choices, to create a facet with images, display term data in facet choices, or to translate facet choices.

Parameters

  • $label | string | The facet choice label (text or HTML)
  • $params | array | An associative array of facet settings and indexed facet choice data (see below)
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
$params = [
  'selected' => false, // TRUE or FALSE
  'facet' => [
    'name' => 'brand',
    'label' => 'Brand',
    'type' => 'radio',
    'source' => 'tax/brand',
    // + other facet-specific settings
  ],
  'row' => [ // all columns from the "facetwp_index" DB table
    'id' => 123,
    'post_id' => 42,
    'facet_name' => 'brand',
    'facet_value' => 'alfa-romeo', // The technical "raw" value, as displayed in the URL after selecting this choice
    'facet_display_value' => 'Alfa Romeo', // The default facet choice label
    'term_id' => 456, // if data source is a  taxonomy. Default: 0
    'parent_id' => 123, // if data source is a hierarchical taxonomy. Default: 0
    'depth' => 1, // if data source is a hierarchical taxonomy. Default: 0
    'variation_id' => 456 // if WooCommerce is active and "Support product variations" is enabled. Default: 0
  ]
];

Each row in the facetwp_index database table consists of nine columns, in which all values are stored for a specific facet choice. This hook has access to all of these values, stored within the $params['row'] array (see all available values above).

Normally, a facet choice’s label is the facet_display_value indexed for that choice. This value is available in this hook via $params['row']['facet_display_value']. The following examples demonstrate how you can replace this label with something else, if needed based on available data in the hook’s $params array.

Usage examples

Add a span with class around facet choices

The following example adds a <span> around each facet choice label, with the facet choice’s facet_value as its class name:

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_facet_display_value', function( $label, $params ) {
  if ( 'my_facet_name' == $params['facet']['name'] ) { // Replace "my_facet_name" with the name of your facet
    $val = $params['row']['facet_value'];
    $label = '<span class="' . $val . '">' . $label . '</span>';
  }
  return $label;
}, 20, 2 );

Add HTML output to fSelect facet choices

When you are using an fSelect facet type, any HTML will be automatically stripped away from the facet choice label output. To prevent this, add an esc_html() function around the output, as follows:

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_facet_display_value', function( $label, $params ) {
  if ( 'my_facet_name' == $params['facet']['name'] ) { // Replace "my_facet_name" with the name of your facet
    $val = $params['row']['facet_value'];
    $label = esc_html('<span class="' . $val . '">' . $label . '</span>');
  }
  return $label;
}, 20, 2 );

Display facet choices as images

FacetWP does not have a dedicated image facet. But you can use the facetwp_facet_display_value hook to display any facet’s choices as icons or images.

The following example shows how to do this for facets based on a taxonomy or custom text field, using the indexed term or field value in the image file name. Note that it is also possible to create an image facet based on an Advanced Custom Fields Image field type, using the selected images directly.

Add the following code to your (child) theme’s functions.php. Make sure to replace vehicle_type in line 4 with the name of your facet. Also change the directory in line 10 to a folder within your theme, in which you place your images. In this example we use SVGs.

The icon/image names are based on each facet choice’s facet_value, e.g. “car”, “truck”, “suv”. The facet_value of a choice is its technical “raw value” that be seen in the URL parameter of the facet when you select that choice.

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_facet_display_value', function( $label, $params ) {

  // Only apply to a facet named "vehicle_type"
  if ( 'vehicle_type' == $params['facet']['name'] ) { // Repace "vehicle_type" with the name of your facet

    // Get the raw value
    $val = $params['row']['facet_value'];

    // Use the raw value to generate the image URL
    $label = '<img src="/wp-content/themes/yourtheme/images/{val}.svg" alt="{val}" />';
    $label = str_replace( '{val}', $val, $label );
  }
  return $label;
}, 20, 2 );

Use the term description as facet choice label

One of the values stored in the facetwp_index database table for each facet choice is the term_id. This value only exists if the facet has a taxonomy set as its data source.

The following example uses this term_id, stored $params['row']['term_id'], to look up the term’s description with WP’s get_term_by() function. After sanitizing the value, it sets the description as facet label:

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_facet_display_value', function( $label, $params ) {
  if ( 'my_taxonomy_facet' == $params['facet']['name'] ) { // Replace "my_taxonomy_facet" with the name of your taxonomy-based facet
    $term = get_term_by( 'id', $params['row']['term_id'] );
    if ( ! empty( $term ) && ! empty( $term->description ) ) {
      $label = esc_html( $term->description );
    }
  }
  return $label;
}, 10, 2 );

Customize or translate facet choices

To “manually” customize a specific facet choice label (normally its facet_display_value), just give $label another value. For example its translation:

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_facet_display_value', function( $label, $params ) {
  if ( 'my_facet_name' == $params['facet']['name'] ) { // Replace "my_facet_name" with the name of your facet
    if ( 'Monday' == $label ) { 
      $label = 'Δευτέρα'; // Change "Monday" to the Greek translation
    }
  }
  return $label;
}, 20, 2 );

To translate a facet choice based on the currently set language, you can extend the above code as follows. This example is for when you are using WPML (use line 7 instead of line 4 for Polylang):

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_facet_display_value', function( $label, $params ) {

  if ( 'my_facet_name' == $params['facet']['name'] ) { // Replace "my_facet_name" with the name of your facet

    // Get current language for WPML:
    $lang = ( ! empty( FWP()->facet->http_params['lang'] ) ) ? FWP()->facet->http_params['lang'] : apply_filters( 'wpml_current_language', null );

    // Get current language for Polylang:
    // $lang = ( !empty( FWP()->facet->http_params['lang'] ) ) ? FWP()->facet->http_params['lang'] : pll_current_language(); 
    
    switch ( $lang ) {
      case 'gr' :
        if ( 'Monday' == $label ) {
          $label = 'Δευτέρα'; // translate "Monday" into Greek
        }
        break;
      case 'nl':
        if ( 'Monday' == $label ) {
          $label = 'Maandag'; // translate "Monday" into Dutch
        }
        break;
    }  
  }
  return $label;
}, 20, 2 );

Alternatively, you can change facet choices into __() translatable strings with the facetwp_facet_render_args hook.

Also see this section on the Multilingual page for more info about the recommended way to translate facet choices, which is to translate the facet’s data source itself (the custom field or taxonomy terms).

More examples

See also

Last updated: August 9, 2024