facetwp_facet_display_value

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 add a prefix or suffix to facet choice labels, 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, // [bool] - true if this choice is selected, false otherwise
  'facet' => [
    'name' => 'brand', // [string - The facet's name
    'label' => 'Brand', // [string] - The facet's label
    'type' => 'radio', // [string] - The facet's type
    'source' => 'tax/brand', // [string] - The facet's data source
    // + all other facet-specific settings
  ],
  'row' => [
    'facet_value' => 'alfa-romeo', // [string] - The technical "raw" value as indexed and displayed in the URL after selecting this choice
    'facet_display_value' => 'Alfa Romeo', // [string] - The facet choice label as indexed
    'term_id' => '456', // [string] - The term ID. Only if the data source is a taxonomy. Default: 0
    'parent_id' => '123', // [string] - The parent ID. Only if the data source is a hierarchical taxonomy. Default: 0
    'depth' => '1', // [int or string] - The hierarchical depth level. Only if the data source is a hierarchical taxonomy. Default: 0
    'counter' => '5' // [string] - The facet choice count
    'order' => '10' // [int or string] - The facet choice order number. Can be dot-separated (e.g. '20.10.5') for hierarchical facets
    'is_choice' => true // [bool] - If the choice is a choice and not a label (only in Hierarchy facets)
    'overflow' => false // [bool] - If the choice is a choice hidden by the 'Soft limit' setting (only in Color facets)
  ]
];

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 most of these values, stored within the $params['row'] array (see all available values above). It also has access to other data, some of which is facet-type specific.

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

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 );

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 );

For some data source types, you may want to add a prefix or suffix to each facet choice. For example, if the data is stored in an ACF Number field, but it’s actually a price or a weight. In those instances, you may want to prepend the choice label with a currency sign,e.g. €, or append it with kg.

With the facetwp_facet_display_value hook, this is very easy to do. You can prepend or append any text you like. You can also use HTML, as shown below.

Add a prefix

The following example prepends a € sign inside a <strong> tag, followed by a space.

Add the code to your (child) theme’s functions.php, and make sure to replace my_facet_name in line 2 with the name of your facet:

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
    $label = '<strong>€</strong> ' . $label; // Add a bold "€ " prefix to each facet choice label
  }
  return $label;
}, 20, 2 );

Add a suffix

The following example appends kg (preceded by a space) to a weight value:

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
    $label = $label . ' kg'; // Add a  " kg" suffix to each facet choice label
  }
  return $label;
}, 20, 2 );

You can also pre- or append something to the facet choice label conditionally, using the data that is available for each choice in the hook’s parameters. Below are two examples.

The following example uses the $params['selected'] parameter to prepend a ✓ check mark to the selected choice of a specific facet:

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 ( $params['selected'] ) {
      $label = '<strong>&check;</strong> ' . $label; // Prepend a "✓ " check mark to each selected facet choice label in this facet
    }
  }
  return $label;
}, 20, 2 );

And the following example appends m² to each facet label choice that is at the hierarchical depth level of 1 (which is the first child level).

Note that his depth value is only available in facet types that support using a hierarchical taxonomy as data source, like a Checkboxes facet with its “Hierarchical” setting enabled.

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 ( 'checkboxes' == $params['facet']['name'] ) { // Replace "my_facet_name" with the name of your facet
    if ( $params['row']['depth'] == 1 ) {
      $label = $label . ' m<sup>2</sup>'; // Append " m2" to each facet selected choice label with hierarchical depth level 1
    }
  }
  return $label;
}, 20, 2 );

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 can 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 );

Note: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 shown in the above code example.

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 );

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 do the same using the facetwp_facet_html hook, or the facetwp_facet_render_args hook. With this last hook, you can not only directly translate (and re-order) the choices, but also change specific or all facet choice labels into __() translatable strings. These can then be translated with a translation plugin or a gettext filter.

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

Search the Help Center

facetwp_facet_display_value

Overview

Parameters

How to use custom PHP code?

Usage examples

Add a span with class around facet choices

How to use custom PHP code?

Add HTML output to fSelect facet choices

How to use custom PHP code?

Add a prefix or suffix to facet choice labels

Add a prefix

How to use custom PHP code?

Add a suffix

How to use custom PHP code?

Add a prefix or suffix using facet or choice parameters as condition

How to use custom PHP code?

How to use custom PHP code?

Display facet choices as images

How to use custom PHP code?

Use the term description as facet choice label

How to use custom PHP code?

Customize or translate facet choices

How to use custom PHP code?

How to use custom PHP code?

See also

In this article

Your site deserves the best filtering

Search the Help Center

facetwp_facet_display_value

Overview

Parameters

How to use custom PHP code?

Usage examples

Add a span with class around facet choices

How to use custom PHP code?

Add HTML output to fSelect facet choices

How to use custom PHP code?

Add a prefix or suffix to facet choice labels

Add a prefix

How to use custom PHP code?

Add a suffix

How to use custom PHP code?

Add a prefix or suffix using facet or choice parameters as condition

How to use custom PHP code?

How to use custom PHP code?

Display facet choices as images

How to use custom PHP code?

Use the term description as facet choice label

How to use custom PHP code?

Customize or translate facet choices

How to use custom PHP code?

How to use custom PHP code?

See also

In this article

Related articles

Your site deserves the best filtering