Beaver Builder

This add-on lets you display facets alongside a range of Beaver Builder listing modules. These modules are available when using Beaver Builder and (optionally) Beaver Themer, or one of the mentioned Beaver Builder add-on plugins.

With this add-on installed, FacetWP also adds three modules of its own, for adding facets, Listing Builder listings, and three FacetWP-related buttons.

Supported modules

The following modules are supported and can be used to create FacetWP compatible listings. Note that all modules need to be enabled for FacetWP to be filterable by facets.

The FacetWP Beaver Builder add-on (v1.5+) adds the following modules:

Usage

Download the Beaver Builder add-on from your account. After installation and activation, add one of the supported modules to you page and enable it for FacetWP. Or add a FacetWP Listing module and select one of your previously created FacetWP listing templates. Then, add some facets with a Facet module.

Enable FacetWP on the module

All supported Beaver Builder listing modules (except FacetWP’s own modules) will display a “FacetWP” setting in their settings. Enable this setting on the module that you want to be filtered with the facets on the page.

After choosing a query source and saving, the module will render in the editor.

Choose a query source

In the module’s “Source” setting, choose a query source that queries posts (of any post type). Other source options like taxonomy queries or ACF repeaters are not supported, as FacetWP cannot filter those.

Choose “Custom Query” to create your own custom query, or “Main Query” if the module is in an archive template. The WooCommerce modules will show product-related options to use.

Note that in archive templates, facets may work even without enabling the “FacetWP” setting, because of FacetWP’s query autodetection. However, to prevent issues with pagination, make sure to always enable the “FacetWP” setting, also in archive templates.

In some of the supported modules, you may also see your FacetWP Listing Builder listings in the “Source” dropdown. This happens if you were already using one before updating to v1.5+ of the add-on, or if you explicitly re-enabled them. After choosing one, the module will use the query settings of that listing template (but not its layout and styling settings). However, using a FacetWP listing template like this is deprecated, and you will see a deprecation message in the module settings. If you need a FacetWP listing to be displayed, including its layout and styling, we recommend using a FacetWP Listing module instead (available in v1.5+ of the add-on).

Add one or more facets

After adding a FacetWP-enabled module, add some facets to the page that will filter this module. The recommended way is to add them with a Facet module. You can also use a shortcode in an HTML module.

FacetWP modules

Since v1.5, the FacetWP Beaver Builder add-on comes with three built-in modules:

1. Facet – adds a facet.
2. Listing – adds a Listing Builder listing.
3. Button – adds an Apply button, a Flyout button or a Submit button.

To quickly find these modules in the module selector, filter by “FacetWP Modules” in the Group dropdown.

The FacetWP Facet module

With a “Facet” module, you can add an existing facet to your page. It is the recommended alternative to adding facet shortcodes with an “HTML” module.

After dragging the Facet module to your page, use the “Facet” setting dropdown to select one of your existing facets.

The dropdown will show all previously created facets. At the bottom, you can select the User Selections facet (which does not need to be created, and does not appear in the facet overview screen of FacetWP’s settings).

Optionally, add a facet heading by entering a text in the “Heading” field and selecting the HTML tag (<h1> – <h6>) for it in the “Heading tag” field.

Most facet types will render in the Beaver Builder editor, after saving their settings. Before saving, and for some facet types, a placeholder with the facet label is shown:

All FacetWP modules will automatically display their (customizable) labels in the sidebar Outline, after saving.

Facets will display but not actually function in the Beaver Builder editor. Check your front-end page to see if your facets are functioning correctly. If they are not appearing, make sure you have also added a listing to the page. This can be a supported FacetWP-enabled Beaver Builder module, a Listing Builder listing (added with a Listing module), or any other supported listing template type.

If you want to hide empty facets (facets with no choices left after filtering), including their heading, you can use this code snippet.

The FacetWP Listing module

With a “Listing” module you can add an existing Listing Builder listing template to your page. It is the recommended alternative to adding listing shortcodes with an “HTML” module.

After dragging the Listing module to your page, use the “Listing” setting dropdown to select one of your existing Listing Builder listings. The dropdown will show all previously created listings.

The Listing module will render your listing, including its full layout, in the Beaver Builder editor. (Most) facet types will render, but not actually function. Check your front-end page to see if your facets are correctly filtering your listing.

All Listing modules will automatically display their (customizable) label in the sidebar Outline, after saving.

Use a FacetWP Listing module on a WP archive template

Generally, on archive templates, it would be better not to use a Listing module, because by default, FacetWP uses the archive’s query, not the Listing module’s custom query. Using a Listing module in this case will cause a mismatch between your facets and the posts displayed in the listing.

The recommended setup is to choose another supported module, with its query source set to use the “Main Query”.

However, if you don’t want or cannot change the way things are set up, and want to keep using a Listing module on a WP archive template, you have to tell FacetWP explicitly which query (not) to use. Two ways to do this are described here (option 1 and 2).

Add a static listing

Using the “Static” setting, you can add a static Listing Builder listing with the FacetWP Listing widget. A “static” listing is a listing that does not react to facets.

You can even add multiple static listings to a page, also to a page that already has a “normal” filterable (non-static) listing. But there should be only one filterable (non-static) listing on a page.

Note that static Listing Builder listings can also be added with a shortcode. When using a shortcode, you can add them with an “HTML” module.

The FacetWP Button module

With a “Button” module, you can add three types of buttons to your page:

1. An Apply button – disables auto-refresh and applies facet selections on button click.
2. A Flyout button – opens the Mobile Flyout panel. This option is only available with the Mobile Flyout add-on installed.
3. A Submit button – redirects facet selections to a separate results page. This option is only available with the Submit button add-on installed.

After dragging the Button module to your page, use the “Button type” setting to select the desired button type. Then change the button text, icon, and other styling settings as needed.

FacetWP button modules will automatically display their button type in the sidebar Outline, after saving.

Add an “Apply” button

When you add an “Apply” button to your page, it will disable FacetWP’s auto-refresh function and apply facet selections only when the button is clicked.

Adding this button type does exactly the same as explained in our tutorial on how to disable facet auto-refresh and add an apply/submit button. It will also automatically add the mentioned JavaScript snippet that disables auto-refresh to your page. As described in this tutorial, this button will disable auto-refresh for all facet types, except for Pager facets and Reset facets. If needed, you can re-enable auto-refresh for individual facets or facet types with FWP.refresh(), for example when using a Sort facet.

Add a “Flyout” button

To be able to create a Flyout button, first install the Mobile Flyout add-on. When you then add a “Flyout” button to your page, the button will open the Flyout panel, as described here.

Add a “Submit” button

To be able to create a Submit button, first install the Submit button add-on.

The Submit Button module is a convenient alternative to adding the Submit button manually or with a shortcode, as described in the Submit button add-on’s setup instructions.

After following the setup instructions and adding the Submit Button module, clicking the button will redirect the page to the URL specified in the “Listing page” setting field of the module. When facets on the page have selections, they will be included in the redirect.

Make sure to enter a full URL (starting with https://) in the “Listing page” setting field, or at least start it with a forward slash, e.g. /my-result-page/.

Add FacetWP shortcodes with an HTML module

Instead of using FacetWP modules (which is recommended), facets, listing templates and other features can also be added with their shortcode in Beaver Builder HTML module.

Just copy the shortcode from the FacetWP overview page or facet/listing settings page, and paste it into the module.

Supported pagination

In most scenarios, FacetWP will automatically detect numbered pagination of supported modules, and make it work with FacetWP’s AJAX refresh.

You can also set the module’s pagination to “None”, create a Pager facet instead, and add it with a Facet module. The Pager facet also has a “Load more” pager type.

Using modules on archive templates

Beaver Themer allows you to design layouts for archive pages (blog posts archive, taxonomy archives, etc).

If you add a supported module to an archive template, make sure to set its Source setting to “Main Query“. This ensures the WordPress archive query is used for both Beaver Builder and FacetWP.

Using a Listing module in an archive template is not recommended, because it creates a custom query. If you do this, make sure to read this section about how to make sure FacetWP is using the right query.

Note that in archive templates, facets may work even without enabling the “FacetWP” setting, because of FacetWP’s query autodetection. However, to prevent issues with pagination, make sure to always enable the “FacetWP” setting, also in archive templates.

Using a FacetWP Listing module on a WP archive template

This is not recommended. See the explanation above.

Customize a module’s query arguments

If you need to adapt or override the query arguments of a supported module (except FacetWP’s Listing module), you can use Beaver Builder’s fl_builder_loop_query_args hook. For example, if you want to display only specific custom post types, change the order, or use a meta query.

This hook works similar to WP’s pre_get_posts hook. It exposes the WP_Query object and allows you to customize the query in any way you want.

The following example adds a fallback sorting method by overriding the original orderby query argument, on the front page only:

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
function my_query_order( $query_args ) {
  if ( is_front_page() ) {
    $query_args['orderby'] = array(
      'date'  => 'DESC', // Primary sort: by post date
      'title' => 'ASC'   // Secondary, fallback sort: by post title
    );
  }
  return $query_args;
}
add_filter( 'fl_builder_loop_query_args', 'my_query_order' );

For more examples of how to use this hook, including how to apply it only to a specific module, see this Beaver Builder tutorial.

For an overview of all available Beaver Builder hooks, see this page.

Customize a Listing module’s query arguments

To change the query arguments of a Listing module, you can just change its settings. Or, if you need more flexibility, use the listing’s Dev mode. Or you can use the facetwp_query_args hook.

Prevent unwanted scrolling

Beaver Builder, by itself, automatically scrolls the page to the top of the module when the page loads.

On pages with FacetWP-enabled modules, you will normally not see this scroll, because the JavaScript in FacetWP’s Beaver Builder add-on prevents it from happening. So if you do see the page scrolling when it loads, something is wrong.

When you open your browser Console on the page with the scroll, you’ll likely see one of the following errors, or something similar referencing FLBuilderLayout:

Uncaught ReferenceError: FLBuilderLayout is not defined
-or-
ReferenceError: Can’t find variable: FLBuilderLayout

This error is caused by Beaver Builder rendering its JavaScript assets inline in the footer, after FacetWP’s Beaver Builder add-on front.js script that prevents the scrolling. FacetWP’s script expects Beaver Builder’s JavaScript to load before it.

There are three possible causes of Beaver Buildering rendering its JavaScript inline in the footer:

1. 

   If the “Render CSS/JS assets inline” setting is enabled. This setting can be found in Settings > Beaver Builder > Advanced > Frontend. Disable this setting to fix the error and the page scroll.

2. If you are using Beaver Builder’s fl_builder_render_assets_inline filter in your (child) theme’s functions.php, or in a code snippets plugin. To fix the error and page scroll, just remove this filter:

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
// DON'T use this. REMOVE it if you have this in your functions.php
add_filter( 'fl_builder_render_assets_inline', '__return_true' ); 

3. The same situation can also be caused by a caching/optimization plugin. To fix the issue, check its settings and make sure to not load JavaScript deferred, and don’t combine scripts. To fix the issue, FacetWP’s Beaver Builder add-on’s front.js script needs to load after all Beaver Builder scripts.

Prevent PowerPack Content Grid module scrolling

If you are using any PowerPack Content Grid modules on a page that also has (any type of) FacetWP-enabled post listing, depending on your setup, you may see unexpected automatic scrolling to the top of these PowerPack modules when the page is (pre-)loaded with a facet selection. To prevent these automatic scrolls, add the following code to your (child) theme’s functions.php:

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( 'pp_cg_before_posts', function( $settings, $query ) {
  $paged = $GLOBALS['wp_the_query']->get( 'paged' );
  $paged = ( $paged < 2 ) ? 0 : $paged;
  $GLOBALS['wp_the_query']->set( 'page', $paged );
  $GLOBALS['wp_the_query']->set( 'paged', $paged );
}, 10, 2 );

Deprecated FacetWP modules and features

In v1.5 of the add-on, two things were deprecated:

• A range of older FacetWP modules
• Selecting FacetWP Listing Builder listing templates in supported modules, other than the Listing module

Migrate deprecated FacetWP modules

In pre-v1.5 versions of the add-on, there were seven FacetWP modules, as shown on the right.

In v1.5, the Facet module was updated, and the Template module was renamed to Listing module. The other five modules are now deprecated. Their functionality can now be added with a Facet module.

After updating the add-on to v1.5+, any pre-existing old modules will display in the sidebar Outline as deprecated modules, like in the image on the right. They will be non-functional, with no way to change any settings or add new ones.

It is possible to re-enable these depreccated modules, but we highly recommend migrating them to the new modules, as outlined in the table below:

Find all used deprecated modules to migrate

To find all deprecated modules to migrate in all your posts, pages, and templates, you can (temporarily) add the facetwp_bb_enable_deprecated hook to your (child) theme’s functions.php:

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
// Re-enable deprecated FacetWP modules, and
// re-enable FacetWP listings in some module's "Source" settings dropdown
add_filter( 'facetwp_bb_enable_deprecated', '__return_true' );

This hook re-enables the deprecated FacetWP modules, which also lets them show up in Beaver Builder’s Modules tab, found in Settings > Beaver Builder > Modules. This makes it easier to find them all.

To also see the number of times a module is used, on how many posts, pages, and templates, add the is_module_disable_enabled hook, as shown below.

The Modules tab will then look like the image on the right.

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
// Re-enable deprecated FacetWP modules, and
// re-enable FacetWP listings in some module's "Source" settings dropdown
add_filter( 'facetwp_bb_enable_deprecated', '__return_true' );

// Show the number of times each module used and on how many pages/posts/templates, in Settings > Beaver Builder > Modules
add_filter( 'is_module_disable_enabled', '__return_true' );

After you finish migrating, you can remove both hooks.

Re-enable deprecated FacetWP modules

We recommend migrating all deprecated modules to the new modules, as outlined in the table above.

However, if you have reasons to want to keep using these old modules, you can re-enable them by adding the following hook to your (child) theme’s functions.php:

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
// Re-enable deprecated FacetWP modules, and
// re-enable FacetWP listings in some module's "Source" settings dropdown
add_filter( 'facetwp_bb_enable_deprecated', '__return_true' );

After adding this hook, the deprecated modules will look like the images on the right. They will keep a “Deprecated” label, but will be fully functional again.

In each module’s settings, you’ll also see a deprecation message with instructions for migrating.

The deprecated modules will appear in a separate tab in the “FacetWP Modules” group in the Module selector, and you can add new instances of them.

Migrate FacetWP listing templates in the Source dropdown

In add-on versions older than v1.5, the following supported modules will display all available FacetWP Listing Builder listing templates in their settings’ “Source” dropdown:

• Posts
• Advanced Posts (UABB)
• Woo – Products (UABB) – only product-based listing templates will work
• Content Grid (PowerPack)
• Product Grid (PowerPack/WooPack) – only product-based listing templates will work

If you choose one of your listing templates as source, that listing template’s query arguments will be used in the module (not its layout or styling).

In version v1.5+ of the add-on, using FacetWP listing templates as module source is deprecated. You will now only see listing templates in the Source dropdown if one was already selected before updating to v1.5+, or if you re-enabled this feature.

We recommend selecting “Custom Query” in the dropdown and recreating your listing template’s query arguments. Or, if you want to display a listing template, including its layout and styling, switch to a Listing module.

Re-enable FacetWP listing templates in the Source dropdown

If you need to re-enable the display of FacetWP listing templates in the Source dropdown, add the facetwp_bb_enable_deprecated hook to your (child) theme’s functions.php.

If you use the hook without any arguments, it will also re-enable deprecated FacetWP modules:

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
// Re-enable deprecated FacetWP modules, and
// re-enable FacetWP listings in some module's "Source" settings dropdown
add_filter( 'facetwp_bb_enable_deprecated', '__return_true' );

If you want to only re-enable FacetWP listing templates in the “Source” dropdown, use the hook 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
// Only re-enable FacetWP listings in some module's "Source" settings dropdown
add_filter( 'facetwp_bb_enable_deprecated', function( $enabled, $type) {
  if ( 'query_options' == $type ) {
    return true;
  }
  return $enabled;
}, 10, 2 );

After using one of these two hook, listings will show up again in the dropdown, but with a “Deprecated” label.

Note that if a Listing Builder listing template is selected in the “Source” dropdown, a deprecation message is shown in the module settings, as can be seen in above image.

Known issues, incompatibilities, and unsupported module settings

There are a few things known to not work with this add-on:

WooCommerce module

• 

  The WooCommere module only works with the setting: Layout > Multiple Products. For the Products Source child setting, all options are supported.

Fix gaps in the WooCommerce module layout after using a Load More Pager facet

If you are using a Beaver Builder WooCommerce module, you’ll notice gaps in the layout after using a Load more type Pager facet. These gaps are caused by the module’s CSS, which sets float, clear, and margin-right rules based on classes added to the first and last item in the retrieved posts.

To fix these gaps, you can use one of the solutions below.

The first approach is to fix the wrong clearing and right margins. The following example is for a 4-column layout. Adapt 4n in line 20 and line 25 for other numbers of columns. The code only applies to min-width: 768px, like the default CSS does. Add other media queries for other widths if needed.

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>
    @media (min-width: 768px) {

      /* Reset some of the default styles */

      .woocommerce[class*="columns-"] ul.products li.product  {
        clear: none !important;
      }

      .woocommerce[class*="columns-"] ul.products li.product.last {
        clear: none !important;
        margin-right: 3.8% !important;
      }

      /* New styles for 4 columns  */

      /* Clear every 5th item */
      .woocommerce[class*="columns-"] ul.products li.product:nth-child(4n+1)  {
        clear: both !important;
      }

      /* Remove right margin for every 4th item */
      .woocommerce[class*="columns-"] ul.products li.product:nth-child(4n)  {
        margin-right: 0 !important;
      }

    }
  </style>
  <?php
}, 100);

The second approach is to remove the floating behavior and let the layout use CSS grid.

In this example we apply a 4-column grid. Adapt the number in line 22 for other numbers of columns. The code only applies to min-width: 768px, like the default CSS does. Add other media queries for other widths if needed.

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>
    @media (min-width: 768px) {

      /* Reset some of the default styles */

      .woocommerce[class*="columns-"] ul.products:before  {
        display: none !important;
      }

      .woocommerce[class*="columns-"] ul.products li.product  {
        margin-right: 0 !important;
        float: none !important;
      }


      /* New styles for 4 columns with CSS grid */

      .woocommerce[class*="columns-"] ul.products  {
        display: grid !important;
        grid-template-columns: repeat(4, 1fr); /* 4 columns */
        grid-gap: 3.8%; /* Adapt as needed */
      }

      .woocommerce[class*="columns-"] ul.products[class*="columns-"] li.product  {
        width: auto !important;
      }

    }
  </style>
  <?php
}, 100);

PowerPack Content Grid module

• The Content Grid module is only supported with the setting: Content > Layout > Grid. Carousel layout is not supported.
• FacetWP does not work with Taxonomy Filters, located under Content > Content Settings > Post Taxonomy Filter > Enable Post Filter. To filter taxonomies, use facets added in a Facet module instead.

UABB Advanced Posts module

• The UABB Advanced Posts module does not work with a Load More Pager facet when the Post Appearance setting is set to Carousel layout.
• The Advanced Posts module does not work with the Taxonomy Filter setting that can be set under the Query tab for Grid and Masonry layouts (set under Post Appearance). This feature adds AJAX filters that do not work together with FacetWP.

UABB Woo Products module

• The UABB Woo Products module does not work with a Load More Pager facet when the Layout setting is set to Carousel layout.

Scroll- or Load More type pagination in all modules

• FacetWP does not support any “Scroll” and “Load more” type pagination that some of the supported modules offer in their settings. Use a Pager facet instead, which includes a “Load more” option, and add it with a Facet module.

Translate Facet module headings and Button module labels in WPML

If you are using FacetWP with the Beaver Builder add-on v1.5+, WPML, and the Multilingual add-on, and you are translating your page(s) with the WPML Advanced Translation Editor (chosen with the middle option in the “Translation this Document” page setting — as shown in the image on the right), the following items will show up in the Translation Editor to be translated:

• Heading texts set in any FacetWP Facet module on the page.
• Button text labels set in any FacetWP Button module on the page.
• Listing page URLs set in any FacetWP Button module on the page that is set to the “Submit button” button type.

These translatable items will look like this:

The alternative is to translate these items in the Beaver Builder editor of the translated page itself (with the “Translate this Document” page setting set to “WordPress Editor” (the right option)).

See also

• What are facets?
• Using the Listing Builder
• Using the Listing Builder in Dev Mode
• How to disable facet auto-refresh and add an apply button
• The Mobile Flyout add-on
• The Submit Button add-on
• How to customize WordPress archive queries
• Using FacetWP with WordPress blocks
• Using FacetWP with Bricks Builder
• Using FacetWP with Elementor
• Using FacetWP with Breakdance
• How to scroll the page on facet interaction
• How to use sticky posts with FacetWP
• How to use the offset query argument with FacetWP
• The facetwp_query_args hook
• The Pager + Load more facet type
• The Sort facet type
• The User Selections facet type
• Using FacetWP with WPML or Polylang