Overview

This hook lets you modify the choices within the Data source dropdown of facets and Listing Builder items, in the FacetWP settings. This filter can also be used to add custom data sources to these dropdowns.

If you’re adding new data sources for facets, depending on the data, you may have to use the facetwp_index_row hook to control how the data gets saved to the index table.

This hook can also be used to add virtual, non-existing data sources for facets, as long as you tell FacetWP how to handle them when indexing the facets that use them.

Parameters

  • $sources | array | An associative array of data sources
  • $context | string | (optional) default for facet data sources, builder for Listing Builder item data sources
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
$sources = [
  'posts' => [
    'label' => 'Posts',
    'choices' => [
      'post_type' => 'Post Type',
      'post_date' => 'Post Date',
      'post_modified' => 'Post Modified',
      'post_title' => 'Post Title',
      'post_author' => 'Post Author',
      // etc...
    ],
    'weight' => 10
  ],
  'taxonomies' => [
    'label' => 'Taxonomies',
    'choices' => [
      'tax/category' => 'Categories',
      'tax/post_tag' => 'Tags'
      // etc...
    ],
    'weight' => 20
  ],
  'custom_fields' => [
    'label' => 'Custom Fields',
    'choices' => [
      'cf/horsepower' => 'horsepower',
      'cf/mpg_city' => 'mpg_city',
      'cf/mpg_highway' => 'mpg_highway',
      'cf/torque' => 'torque'
      // etc...
    ],
    'weight' => 30
  ],
  'woocommerce' => [
    'label' => __( 'WooCommerce', 'fwp' ),
    'choices' => [
      'woo/price' => __( 'Price' ),
      'woo/sale_price' => __( 'Sale Price' ),
      'woo/regular_price' => __( 'Regular Price' ),
      'woo/average_rating' => __( 'Average Rating' ),
      'woo/stock_status' => __( 'Stock Status' ),
      'woo/on_sale' => __( 'On Sale' ),
      'woo/featured' => __( 'Featured' ),
      'woo/product_type' => __( 'Product Type' ),
      // etc...
    ],
    'weight' => 5
  ],
  'acf' => [
    'label' => 'ACF',
    'choices' => [
      'acf/my_acf_field' => 'my_acf_field',
      'acf/my_acf_field2' => 'my_acf_field2',
      // etc...
    ],
    'weight' => 5
  ],
  'upt' => [
    'label' => 'User Fields',
    'choices' => [
      'upt/my_user_field' => 'my_user_field',
      'upt/my_user_field2' => 'my_user_field2',
      // etc...
    ],
    'weight' => 10
  ],
];

Notes

  • Each $sources array key is its own <optgroup> in the data source dropdown. For example: $sources['posts'] for Posts fields, $sources['taxonomies'] for Taxonomies, and $sources['custom_fields'] for “normal” Custom fields.
  • Plugins that FacetWP integrates with have their own array key and <optgroup>. For example: $sources['woocommerce'] for WooCommerce fields, $sources['acf'] for Advanced Custom Fields fields, and $sources['upt'] for User Post Type fields.
  • Each type/group of fields has a label value for its <optgroup> heading, a choices array containing its fields, and a weight value determining the order in the data source dropdown.
  • Each field in a group’s choices array is a key/value pair, where the value is the field’s dropdown option label, and the key is the field name, prefixed with the field type: tax/ for taxonomies, cf/ for “normal” custom fields, woo/ for WooCommerce fields, acf/ for Advanced Custom Fields, and upt/ for User Post Type fields. Posts fields do not have a prefix.
  • By adding new items to $sources, each with a label value, choices array, and weight value, you can create your own custom <optgroup> groups of fields in the dropdown.

Examples

Add custom fields

The following example adds an existing custom field named my_data to the custom_fields choices of the dropdown.

Note the cf/ prefix that we need to use in the key of “normal” custom fields, as explained in above notes.

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_sources', function( $sources, $context ) {
  $sources['custom_fields']['choices']['cf/my_data'] = 'my_data';
  return $sources;
}, 20, 2 );

The following example adds “Post Status” to the posts choices:

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_sources', function( $sources, $context ) {
  $sources['posts']['choices']['post_status'] = 'Post Status';
  return $sources;
}, 20, 2 );

This may be helpful if you want to index, filter, and display posts with a post_status other than “publish”, like draft, future, pending, or private posts.

Customize the indexed data for added custom fields

Depending on the custom field that are adding, you may have to use the facetwp_index_row hook to control how the data gets saved to the index table.

Here is an example that uses the facetwp_index_row hook to customize the value of an indexed post_mime_type, in a Media Type facet.

The example below does something similar, with a facetwp_indexer_post_facet hook:

Add a (non-existing) custom field/option and handle its indexing

It is also possible to add a custom field/option that does not exist, as long as you tell FacetWP how to handle it when indexing a facet that uses it as its data source.

The following example adds a (non-existing) “Price (incl. tax)” field to the woocommerce choices in the dropdown.

In line 2 we use 'default' == $context as a check, so that the field is only added to facets’ Data source dropdowns, not to Listing Builder item dropdowns.

Because woo/price_incl_tax is not an existing field, FacetWP needs directions on how to get and index its value correctly. In this example, we are using the facetwp_indexer_post_facet hook to get the price including tax with WooCommerce’s wc_get_price_including_tax() function:

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_sources', function( $sources, $context ) {
  if ( 'default' == $context ) { // Only in facets' Data source dropdowns, not in Listing Builder item dropdowns
    $sources['woocommerce']['choices']['woo/price_incl_tax'] = __( 'Price (incl. tax)' );
  }
  return $sources;
}, 20, 2 );

// Handle the new data source when indexing
add_filter( 'facetwp_indexer_post_facet', function( $return, $params ) {
    $facet = $params['facet'];
    $defaults = $params['defaults'];
    $post_id = (int) $defaults['post_id'];

    if ( 'product' == get_post_type( $post_id ) && 'woo/price_incl_tax' == $defaults['facet_source'] ) {
        $product = wc_get_product( $post_id );
        $price = wc_get_price_including_tax( $product );
        $defaults['facet_value'] = $price;
        $defaults['facet_display_value'] = $price;
        FWP()->indexer->index_row( $defaults );
        return true;
    }

    return $return;
}, 20, 2 );

Remove custom fields

The following example removes custom fields that start with _stcr from the custom_fields choices of the dropdown:

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_sources', function( $sources, $context ) {
  foreach ( $sources['custom_fields']['choices'] as $key => $value ) {
    if ( 0 === strpos( $value, '_stcr' ) ) {
      unset( $sources['custom_fields']['choices'][ $key ] );
    }
  }
  return $sources;
}, 20, 2 );

Below is another example that removes all custom fields that have a meta key starting with cf/_.

In line 3 we use custom_fields as $key, to target the custom fields dropdown group. And we use default as $context to target facet data source dropdowns only. For Listing Builder data sources, you’d have to use builder as $context.

In line 5, we need to use the cf/ prefix to target the key of “normal” custom fields, as explained above.

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_sources', function( $sources, $context ) {
  foreach ( $sources AS $key => $value ) {
    if ( 'custom_fields' == $key && 'default' == $context ) {
      $choices = array_values( array_filter( $value['choices'], function( $value, $key ) {
        if ( str_starts_with( $key, 'cf/_' ) ) {
          return false;
        }
        return true;
      }, ARRAY_FILTER_USE_BOTH ) );
      $sources[$key]['choices'] = $choices;
    }
  }
  return $sources;
}, 20, 2 );

More examples

See also

Last updated: April 1, 2026