Frequently Asked Questions

FacetWP requires PHP 7.0+ (since FacetWP v4.0) and WordPress 5.0+ (fully compatible with WordPress 6.4.2).

No, FacetWP is a plugin for self-hosted WordPress installs.

Yes, FacetWP fully supports PHP 8.x.

The minimum supported version is PHP 7.0 (since FacetWP v4.0). The PHP Stats page helps us determine when to drop support for older PHP versions.

We offer a free trial version, with the following limitations:

• A maximum of 2 facets will display on a page;
• A persistent admin notice will appear in the WP admin dashboard;
• We cannot provide any support.

No, we do not offer refunds. Please use our free trial to see if FacetWP is right for you.

See our Getting Started screencast. If the video doesn’t make sense to you, then you’ll probably need to find a developer to assist you.

We do not current offer paid implementation services. For custom development (site buildouts, design tweaks, other customizations) we recommend Codeable.io.

Probably. There’s tens of thousands of themes out there. If you tell us which theme, and we’ll try to figure out whether the theme is compatible.

FacetWP integrates with Bricks, Elementor and Beaver Builder.

FacetWP does not officially integrate with Divi, WP Bakery, or Oxygen Builder. Depending on your template setup you may get things to work, but these builders are not officially supported.

On these non-supported builders, you could always use FacetWP’s built-in Listing Builder to build your post listing. Or you could use Gutenberg blocks, or a custom WP_Query, or the WP archive page itself (if your post listing is an archive).

Yes! FacetWP supports any plugin that uses post types to store products. WooCommerce, Easy Digital Downloads, and Jigoshop are all compatible.

One caveat: some page components (e.g. pagination and sorting) may need to be replaced with FacetWP facets for paging and sorting, although FacetWP has built-in support for WooCommerce’s default pagination and sorting.

Yes, if you install the Blocks add-on, you can use facets alongside the following block types, in classic and block themes:

Source/Plugin	Block name
WordPress	Query Loop Posts List Latest Posts
WooCommerce	Products (Beta)
GenerateBlocks	Query Loop
Kadence Blocks	Posts

Consequently, with this add-on installed, you can also use FacetWP with these supported blocks in .html templates in block themes.

Yes, FacetWP supports listing and filtering of posts, pages, and any custom post type (as long as it is searchable).

Additionally, with a Professional license you can install the User Post Type add-on, which allows you to map users to a post type, and therefore filter users.

Yes, FacetWP supports listing and filtering of posts, pages, and any custom post type (as long as it is searchable).

Additionally, with a Professional license you can install the User Post Type add-on, which allows you to map users to a post type, and therefore filter users.

No. FacetWP does not support filtering of taxonomy terms. But you can filter posts, pages and custom post types by category or taxonomy term(s), by setting a taxonomy as a facet’s data source.

Besides posts, pages and custom post types, you can filter users, if you install the User Post Type add-on, which comes with a Professional license.

Yes! Professional licenses include the User Post Type add-on, allowing you to map users to a post type, and therefore filter users.

FacetWP can be installed on sub-sites in a WordPress multi-site network setup. But FacetWP cannot filter across different sites.

Please also remember that each sub-site counts against your license’s site limit.

Since version 4.1.8 FacetWP displays admin notices when you have certain plugins installed and the necessary integration add-ons are missing.

These notices were added because many users are unaware of the fact that some plugins do not work with FacetWP unless the related add-on is installed. For example, WPML needs the Multilingual add-on installed to work with FacetWP.

There are certain situations however in which you don’t need the integration add-ons. In these cases you can permanently disable these notices by adding 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_filter( 'facetwp_dismiss_notices', '__return_true' );

Yes, automatic updates are enabled for sites with an active license key.

FacetWP will continue to work, but you will no longer receive plugin updates or support.

We offer a 20% renewal discount on the normal price.

Make sure that you’ve activated your license (Settings > FacetWP > Settings). If you’re still not seeing updates, go to Dashboard > Updates, then click the Check again button. Sometimes WP’s update cache need to be flushed.

Depending on your licence type, you can use your license up to 3 or 20 live sites.

You are also allowed to use it on as many local / dev / staging sites as needed.

You can see in your account which sites are considered as staging sites.

The most common cause of facets disappearing is because your facet shortcodes are inside of the facetwp-template container element. The element with that class will be dynamically replaced when using facets, so facets need to be outside of it to keep functioning properly.

In listings made with the Listing Builder, this issue will never happen, because the class will be automatically placed on the right element.

But if you are using a WP Archive or a custom WP_Query, or a setup with a page builder query/posts block for your listing, your facets may end up inside the element that has the facetwp-template class.

The solution in all cases is removing the facetwp-template class from where you placed it (if you did), and manually placing it on an element that (directly) surrounds the post loop.

For further explanations about the role of the facetwp-template class in FacetWP’s automatic query detection, and ways to fix issues with it, see the sections about it on the Using a WP Archive and Using a custom WP_Query pages.

• Have you hit the Re-index button?
• Does a valid listing template exist on your page?
• Is your post type searchable? (is the exclude_from_search parameter set to false when the post type is registered)?
• Does your facet show any rows after indexing? If not, there could be something wrong with the facet’s selected Data Source. Make sure that you select a valid data source and check if your posts have (valid) values saved for the selected field. After making corrections, re-index again to see the updated row counts. To check if a facet is working okay in general, you can test with its Data Source set to “Post Type” and re-index.
• Are there any JavaScript errors in your browser’s console?
• Turn on Debug Mode and make sure that FacetWP is using the right query.
• For some specific types of custom fields — like serialized data or relationship fields — you may need to tell FacetWP’s indexer how to properly index the data.
• Do you have post IDs higher than 4294967295? If so, your posts cannot be properly indexed because of the limitations of the database field that stores these post IDs. Implement this fix to increase this limit.

FacetWP itself is very fast. It normally takes a fraction of a second to load results. However, every WordPress request (including AJAX) is only as fast as the slowest plugin.

The AJAX requests that FacetWP uses on pages with filters are ignored by most caching plugins, so the load time you’re seeing with FacetWP is your server’s and website’s true speed.

If FacetWP takes a while to load, there’s likely a larger underlying issue. Make sure to disable any unnecessary plugins, and ensure that your server has sufficient resources.

You can read more about the possible causes of slow filtering, and FacetWP’s speed and limitations when indexing, filtering and searching in our performance article, which also lists things you can do to speed up the filtering process itself.

If you want to increase the (true, uncached) loading speed of you pages, check out our tutorial about how to use Query Monitor to optimize performance by optimizing your database queries.

And see our guide on how to make your website load faster for an overview to get you started with increasing server and website performance.

We also have a free Caching add-on that caches FacetWP’s AJAX requests, which may help on high-traffic sites.

Some plugins and themes use JavaScript to modify the layout, load images, or apply animation effects. Some examples include masonry or isotope layouts/grids, image lazy loading, and sliders/carousels.

These scripts run on the initial page load, but do not usually run after each FacetWP AJAX refresh, meaning that they’ll likely need to be manually re-triggered within a facetwp-loaded event.

Some theme and plugins offer a setting that (re-)triggers these scripts on AJAX refresh.

If you are seeing duplicate posts in your listing, especially in combination with a Pager/Load more facet or Sort facet, the cause is almost always the way the posts are ordered in the query, which is determined by the orderby query argument.

If results are ordered by a value that is the same (or empty) for multiple posts, or by a random value, MySQL does not have a fallback and will often sort erratically.

In this tutorial you can read which scenarios can cause this, and how to fix it quickly by adding a secondary, fallback sort order to the listing query.

If you’re using a caching plugin, in general make sure that HTML minification and script deferring are disabled.

FacetWP has built-in support for WP Rocket.

Also, see our tips and tricks for using Cloudflare and Fast Velocity Minify.

FacetWP’s indexer can stall occasionally: the server/WordPress ran out of memory, there was a power outage, etc. Fortunately, FacetWP includes built-in resume functionality. It should resume automatically after a minute or two, assuming you keep the FacetWP settings screen open.

If your site is behind a .htpasswd login, the indexer might be blocked from resuming. In these cases, you’ll need to pass the access credentials to FacetWP.

If your site is hosted on WP Engine, try adding the following line to wp-config.php (not to 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
define( 'WPE_GOVERNOR', false );

Also, reach out to WP Engine support and ask them to add the below URL to your account’s custom cache exclusion list:

/wp-json/facetwp

For an overview of all common indexing issues, see our page about indexing.

Value modifiers need to be entered like this:

The following two things often go wrong:

The values you enter in a facet’s “Value modifiers” field need to be each on a separate line in the form field. Do not put them on one line with commas or add commas to each line.

The values also need to match the label (not the slug) of the value exactly, including spaces and capitalization.

For example, if you have a category called “Fall Collection”, the value entered in the “Value modifiers” field needs to be exactly that: Fall Collection.

If you have not modified the facet values with output hooks like facetwp_facet_display_value, the quickest way to determine the labels is to look at the facet value labels themselves: the labels beside the checkbox or radio button, or the options in the dropdown. Make sure to check if capitalization is not changed with CSS, for example with text-transform: lowercase.

The Listable and Listify themes both have FacetWP integration that, at the time of writing, is incompatible with FacetWP 3.9.x.

Listable and Listify are using deprecated FacetWP functions, causing facets and the submit button on the homepage to malfunction.

read more

See this explanation on how to add headings above facets, and how to customize them.

See this explanation on how to hide empty facets.

How to hide the counts depends on the facet type and how general or specific you want to target facets to hide the counts for.

Facets with a dropdown UI type need a different approach than facets with checkboxes or radios. Some facets can have different UI types, so the method varies.

How to hide counts for facets of type:

• Checkboxes
• Dropdown
• Radio
• fSelect
• Hierarchy
  
• Hierarchy Select
  
• Range List
  
• Time Since
  

Introduced in FacetWP v4.0 is the possibility to add more than one listing template to the same page.

Each listing template can have its own grid layout, styling, and query. But only one of them can be “dynamic” and will react to the facets on the page. The others have to be “static” listing templates and will not react to facets.

Alternatively, you could also add more than one custom query / post listing to the page (e.g. using WP_Query), but these also wouldn’t be tied to FacetWP filtering.

No, FacetWP does not support infinite scroll, which is intentional.

Plugins that add any form of infinity load / infinite scroll will not work as expected.

The closest thing is the Pager facet, which has a pager type that generates a “load more” button, working similar to infinite scroll.

FacetWP was built with performance in mind and is very fast itself. We’ve structured and highly optimized our data storage and have analyzed every query to make sure that it runs as efficiently as possible.

So ultimately, FacetWP’s speed depends on your server, the theme setup, your plugins, and the amount of content. If your server is overloaded (i.e. too many heavy plugins or other users) or underpowered (too little memory or CPU power), then obviously FacetWP will not run at its peak.

See our guide on how to make your website load faster for an overview to get you started with increasing server and website performance.

Factors that determine the speed of filtering itself:

• the type of listing template used
• the total number of results in your listing
• the number of posts per page
• the number of queries and amount of HTML per post item
• the number of active facets on the page
• the facet types in use
• caching of FacetWP’s AJAX requests

You can read more about each of these factors in our performance article, which also describes the possible causes of slow filtering, and FacetWP’s speed and limitations when indexing, filtering and searching.

If you want to increase the (true, uncached) loading speed of your pages with facets, check out our tutorial about how to use Query Monitor to optimize performance by optimizing your database queries.

We also have a free Caching add-on that caches FacetWP’s AJAX requests, which may help on high-traffic sites.

Check out our performance article about FacetWP’s speed, limits and scalability when indexing, filtering and searching.

We are occasionally asked whether FacetWP supports pretty URLs, e.g. /make/audi/model/a4/ instead of ?_make=audi&_model=a4.

FacetWP only supports GET-based permalinks. “Pretty” permalinks quickly lose their appeal as more selections are made. Plus it may actually be bad for SEO, since search engines would see many different URLs with the same content.

That’s probably why most large eCommerce sites stick with GET-based permalinks.

For more info about FacetWP’s URL, see this page.

FacetWP’s query variables use a _ prefix to prevent conflicts with WordPress and other plugins.

WordPress has many reserved terms and reserved query variables. Unexpected things would happen if FacetWP would use them.

For more info about FacetWP’s URL variables, see this page.

This page explains how to track pageviews of facet pages with Google Analytics 4.

No, when using multiple facets, they are always compared using “AND” logic. FacetWP is designed to “filter down” in the results.

Using “OR” logic is possible for individual facets. If you are using a Checkboxes facet or an fSelect facet, you can use “OR” logic by setting the “Facet logic” setting.

A frequently asked question is if it is possible to show all facet choices (for example all terms in a taxonomy), also if there are no results for some of those choices.

The answer is no; FacetWP only indexes and displays facet choices that have results.

Note that some facet types (like Checkboxes, Radio and fSelect) have a “Show ghosts” setting, which will show “ghost” (dimmed) choices if there are no results for them. But the same applies for these ghost choices: they need to appear in the unfiltered results, and can only become ghosts after being filtered out. If a facet choice has no associated posts, then it will never appear.

An often-asked question is how to automatically scroll the page to the results (or to the top of the page or another target) when using facets, a specific face (type), or even a specific facet choice.

Our page scrolling tutorial shows a range of examples that should cover most scenarios.

For pagination scrolling, see this section on the Pager facet page.

This tutorial explains how to add a loading text or spinner icon to the listing template during facet refresh.

You can also fade the listing template during refresh, or hide it until facets are selected.