Overview

With this hook, you can modify the display value (the label) of facet choices (the label text and its HTML).

This is a very versatile hook. It can for example be used to:

The hook runs once for each facet choice, in most facet types. Note that it will not run on the default “Any” choice (in facet types that have this, like for example Radio facets or dropdown-based facets), with two exceptions: the Hierarchy facet and the A-Z Listing facet.

Alternative output hooks to consider

There are a few other hooks that can be used to influence the front-end facet output:

Supported facets

The facetwp_facet_display_value hook can be used to customize the choice label output of the following facet types:

Facet type Remarks
Checkboxes
Dropdown
Radio
fSelect
Hierarchy
Autocomplete
Pager FacetWP v4.6+ required. Only supported for the “Per page” Pager type. To customize the output of the pager links of a “Page number” type Pager type facet, you can use the facetwp_facet_pager_link hook.
Sort FacetWP v4.6+ required.
Hierarchy select Hierarchy Select add-on v0.5.5+ required.
Range List
Time Since
A-Z Listing A-Z Listing add-on v1.5+ required.
Color
Exclude

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
  'disabled' => false, // [bool] - true if this choice is disabled, meaning it is 'ghost' choice that would return zero results. Available in FacetWP v4.6+.
  '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, e.g.:
    'ui_type' => 'checkboxes', // [string] - The facet's UI type (only in Time Since, Range List, and Exclude facets) 
  ],
  '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
    // + facet-type-specific parameters, e.g.:
    '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)
  ],
  // + facet-type-specific parameters, e.g. only in A-Z Listing facets:
  'aliases' => [
    '#' => [0,1,2,3,4,5,6,7,8,9],
    'A-C' => ['A','B','C'],
  ],
  'results' => ['5','A','C','F','G']
];

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

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

Add a prefix or suffix to facet choice labels

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

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

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 three examples.

The following example uses the boolean $params['selected'] parameter to prepend a bold ✓ check mark icon 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 icon to each selected facet choice label in this facet
    }
  }
  return $label;
}, 20, 2 );

The following example uses the boolean $params['disabled'] parameter (available in FacetWP v4.6+) to prepend a bold ✗ cross icon to the disabled choices (= “ghost” choices) of a specific facet. This only works for facet types that can show ghosts, and have their “Show ghosts” 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 ( 'my_facet_name' == $params['facet']['name'] ) { // Replace "my_facet_name" with the name of your facet
    if ( $params['disabled'] ) {
      $label = '<strong>&cross;</strong> ' . $label; // Prepend a "✗ " cross icon to each disabled facet choice (=ghost) label in this facet
    }
  }
  return $label;
}, 20, 2 );

The following example appends m2 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 );

Customize labels using facet-type specific parameters

The following examples show how to use parameters that are specific to certain facet types:

Customize Hierarchy facet labels

This facet type has a unique parameter $params['row']['is_choice'], which is true if the choice is a “real” clickable choice. So not the “Any” choice or the (unclickable) selected choice. In the example below, we are using this parameter to wrap these choices in a span tag with class “choice”.

Like other taxonomy-based hierarchical facet types, it has a $params['row']['depth'] parameter that contains the hierarchical depth. This can be used to customize labels for choices with a specific depth.

Like the A-Z Listing facet, and unlike all other facet types, it has the option to customize the “Any” choice label, by using if ( '' === $params['row']['facet_value'] ) as check.

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

  // Skip if the facet type is NOT a Hierachy facet
  if ( 'hierarchy' !== $params['facet']['type'] ) {
    return $label;
  }

  // Customize the label if the choice is a "real" clickable choice. So not to the "Any" choice or the (unclickable) selected choice.
  if ( isset( $params['row']['is_choice'] ) ) {
    $label = '<span class="choice">' . $label . '</span>';
  }

  // Customize the label if the choice's hierachical depth is 2
  if ( isset( $params['row']['depth'] ) && $params['row']['depth'] == 2 ) {
    $label = '<small>' . $label . '</small>';
  }

  // Customize the label of the "Any" choice
  if ( '' === $params['row']['facet_value'] ) {
    $label = 'reset all';
  }

  return $label;
}, 20, 2 );

Customize A-Z Listing facet labels

The following example shows how to customize labels of the A-Z Listing facet.

This facet type has several unique parameters, like $params['results'], which contains the characters that will return results, and $params['aliases'] which contains all defined character aliases.

By using these parameters as checks, you can customize labels of specific characters. For example, add a custom prefix to those that are aliases, those that are selected or not, or those that have results or not.

Note that unlike in all other facet types (except Hierarchy facets), you can also target the “Any” choice, by using if ( '' === $params['row']['facet_value'] ) as a check.

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
// Note: A-Z Listing add-on v1.5+ required.
add_filter( 'facetwp_facet_display_value', function( $label, $params ) {

  // Skip if the facet type is NOT an A-Z Listing facet.
  if ( 'alpha' !== $params['facet']['type'] ) {
    return $label;
  }

  // Add a text prefix if the choice is an alias.
  if ( array_key_exists( $label, $params['aliases'] ) ) {
    $label = 'alias: ' . $label;
  }

  // If the character is selected, make it bold.
  if ( $params['selected'] ) {
    $label = '<strong>' . $label . '</strong>';
  }

  // Change the label if it is the "Any" choice.
  if ( '' === $params['row']['facet_value'] ) {
    $label = 'reset all';
  }

  // Prefix the character with a check mark icon if the choice label is in the array of results (the clickable/available characters and numbers in the facet for which there are posts in the listing), otherwise, add a cross icon.
  if ( in_array( $label, $params['results'], true ) ) {
    $label = '&check; ' . $label;
  } else {
    $label = '&cross; ' . $label;
  }

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

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

See also

Last updated: October 20, 2026