FacetWP - WordPress Plugin

How to Set Up FacetWP for Smart Filtering in WordPress

FacetWP works best not as "just another filter," but as a system made up of three connected parts: your site data, the facets users choose from, and the dynamic results they see without a full page reload. This guide focuses on the practical side of that setup: how to prepare your site, create your first facets, connect them to a list of posts or products, verify the index, and understand why a filter sometimes fails to show the expected options.

This guide is written for site owners, webmasters, and developers who already know which posts, products, recipes, directory items, or other content need to be filtered, but do not want to build the solution by guesswork. It does not cover purchasing or licensing. The focus is on setting up a plugin you already have, verifying the result, handling common mistakes, and deciding when FacetWP is the right fit and when another tool would make more sense.

One important point up front: FacetWP does not turn messy data into a clean directory on its own. It works well when your posts already use clean taxonomies, custom fields, WooCommerce attributes, or other well-structured data sources. If your content structure is weak, fix that first. Otherwise, any filter system will feel inconsistent and create a poor user experience.

Where FacetWP Delivers Real Value

FacetWP is used when visitors need to narrow down a large set of content using several criteria. Common examples include online stores, real estate listings, recipe databases, car catalogs, job boards, document libraries, portfolios, expert directories, event listings, and map-based directories. All of these projects share one thing: users do not want to scroll through a long archive. They want to choose a few conditions and immediately see the matching results.

The plugin is built around faceted search. In practical terms, each facet is one way to narrow the result set. That might be a category checkbox, a brand dropdown, a price slider, a keyword search field, a date range, a rating selector, geographic proximity, a map, or another interface type. The value is not in how many controls you place on the page, but in the fact that those controls understand the current results and show only relevant choices.

In practice, this matters most on pages where multiple filters depend on one another. For example, if a visitor chooses a car brand, the list of models, body styles, and price ranges should immediately update based on the remaining listings. If someone selects a recipe flavor profile, the cooking methods and categories should not send them into empty results. FacetWP is specifically designed for these connected filtering states.

Another strength is how well it works with existing WordPress data. The official documentation describes data sources such as post types, custom fields, taxonomies, author data, publish dates, WooCommerce attributes, and other structured sources. That means a strong FacetWP project starts not with styling the filters, but with a more important question: which fields and taxonomies already exist, how consistently they are filled in, and whether they make sense to visitors.

When the Plugin Is Especially Useful

FacetWP is worth considering if your site has a listing where visitors need two to six meaningful ways to refine the results. In an online store, that might be price, brand, size, availability, and category. In a recipe database, it could be dish type, ingredients, cooking method, and diet. In an expert directory, it might be city, specialty, work format, and experience level. If the user can describe the task as "show me only the items that match these conditions," faceted filtering is a natural fit.

The plugin is also useful when your theme or page builder already displays content cards but does not provide good connected filtering. FacetWP can work with WordPress archives, its own Listing Builder, custom WP_Query setups, blocks, and some builders through add-ons. Do not assume that means universal magic. You still need to verify your specific listing type in the documentation and on a test page.

When FacetWP Might Be Overkill

If your site contains only a small number of items, standard categories, search, or a simple menu may be enough. If visitors need to search through long-form text, PDFs, attachments, relevance scoring, and weighted fields, FacetWP alone does not replace a dedicated search engine. It can work alongside SearchWP, but its main job is to filter structured data, not rank complex full-text results.

The plugin can also be excessive on a site where the data is unstable, fields are entered manually without rules, and editors use different names for the same attribute. In that case, normalize the content first: standardize your taxonomies, remove duplicate terms, review numeric fields, and decide which attributes actually matter to users.

Quick reality check before you decide: take 20 real posts or products and try filtering them manually using the facets you plan to build. If the attributes are filled in consistently and the results are genuinely useful, FacetWP will have a solid foundation. If half the fields are empty or named inconsistently, start with the content structure instead.

How FacetWP Connects Facets, Data, and Results

To configure FacetWP correctly, you need to understand how it works under the hood. In most cases, problems are not caused by a button in the admin panel, but by a broken connection between the facet, the index, and the listing. A facet does not know on its own which cards it should filter. It needs a FacetWP-enabled listing template, meaning a dynamic list of posts, products, or items to which it can apply the selected conditions.

The official materials emphasize that facets filter posts of any indexable post type, but they do not filter categories or terms as standalone entities. They filter posts by those categories and terms. That distinction matters in directory-style projects: if you want to display brands, categories, or authors themselves as separate cards, that is a different task from filtering products or posts by brand, category, or author.

The Facet

A facet is an interface element with a type, a data source, and behavior settings. For example, a brand facet might be a checkbox list based on a brand taxonomy, while a price facet might be a slider tied to a numeric price field. In the FacetWP admin panel, each facet has a human-readable label and a technical name. The technical name is used in shortcodes, URLs, and JavaScript, so it is best to keep it short, in Latin characters, and free of non-Latin text.

A common mistake in Russian-language projects is to make the facet's technical field name either non-Latin or excessively long. The documentation explains that this name is sanitized because it becomes part of the URL and internal logic. A safe practice is to keep the user-facing label readable, such as "Brand," "Price," or "Property Type," while using technical names like brand, price, or property_type.

The Index

The index is a service table that FacetWP creates to make filtering fast. During indexing, the plugin analyzes posts, fields, terms, and other sources, then stores pairs in the form of "facet - value - post." That is why filtering can remain fast even on complex pages: when a visitor clicks a filter, the system does not need to recalculate every possible value from raw content.

After adding or changing a facet, you need to run Re-index. Regular edits to individual posts are usually picked up by automatic indexing, but there are important exceptions: bulk imports, changes to term hierarchy, changes to facet settings, edits to indexing hooks, clearing the index table, or changing which post types are indexable. This is not just a formality. If the index is outdated, the interface may look correct while the filter options remain empty or incomplete.

The Listing

The listing is the content area FacetWP is meant to filter. It might be a WordPress archive, a WooCommerce shop page, a Listing Builder template, a Query Loop block via add-on, an Elementor/Beaver/Bricks listing through integration, a custom WP_Query, or another supported setup. The page should contain one active FacetWP-enabled listing. If there are several competing listings, the plugin may not know which one it is supposed to update.

In the rendered HTML, FacetWP usually relies on the facetwp-template container or a supported integration. If that container is misplaced, the filter may refresh the wrong part of the page, break the layout, or fail to react at all. That is why the first version of the page should be as simple as possible: one listing, two or three facets, and one display method. Once that works, you can add sorting, pagination, a mobile panel, and more advanced scenarios.

What to Check Before Installation and Initial Setup

Your prep work before installing FacetWP should be short, but strict. The plugin is not sensitive to how "pretty" your theme is. It is sensitive to whether WordPress outputs the listing correctly and whether the data is structured cleanly. If you check a few things in advance, the setup will go faster and troubleshooting will not turn into guesswork.

Content Structure

Start with the future filter page. Define exactly what each card will represent: products, posts, recipes, properties, jobs, documents, or a custom post type. Then list the attributes visitors will actually use to refine the results. For each attribute, decide where the data is stored: taxonomy, custom field, WooCommerce attribute, numeric field, date, coordinates, ACF field, or another source.

If an attribute has a fixed set of choices, a taxonomy or product attribute is usually the better option. If the value is numeric, such as price, square footage, year, rating, or distance, it needs a numeric source. If the value is a date, do not mix text strings with date data. If the field contains free-form text, do not expect it to produce a clean facet without extra preparation.

The Listing and the Theme

Review how the listing page is built right now. Is it a standard theme archive, a WooCommerce shop page, an editor block, an Elementor loop, a custom template, or a manual WP_Query? The answer determines how FacetWP should be connected. The documentation lists supported listing templates, but you still need to open a test page and confirm that FacetWP detects the correct query for your specific theme.

If the page is built with a non-standard builder, verify ahead of time whether there is an official integration or a clear way to add the facetwp-template class. The FacetWP FAQ explicitly separates supported builders from unsupported ones. Some unsupported setups can still be handled manually, but those workarounds are better left to a developer instead of becoming part of the default setup.

Cache, Optimization, and JavaScript

FacetWP updates results through Ajax, so cache plugins, delayed script loading, minification, HTML comment stripping, and aggressive CDN settings can affect the outcome. During setup, simplify optimization on purpose: disable script combining or delayed loading for the test page, avoid removing HTML comments, and test filtering in a clean browser tab.

That does not mean FacetWP cannot run on a cached site. It only means you should first get a stable baseline configuration, then turn optimization settings back on one at a time and verify that filters, pagination, and listing updates still work. That order can save hours of debugging.

Permissions and a Test Environment

For the first implementation, you need WordPress admin access, the ability to enable and disable plugins, access to the browser console, and, if needed, access to server logs. If the site is live and the catalog matters to revenue, start on a staging copy. FacetWP changes listing behavior, not just page decoration, so testing on a copy of the site is standard practice.

Quick prep checklist before installing FacetWP

What to Check	Why It Matters	Good Sign
Post types and fields	Facets pull data from real sources	Each planned filter has a clear field or taxonomy behind it
One main listing on the page	FacetWP needs to know which results area to filter	The page has one primary dynamic listing
Cache and optimization	Ajax updates can break because of script handling or HTML optimization	The test page works without aggressive optimization
A verification scenario	After setup, you need a fast way to tell whether the filter works	You have 5 to 10 test items with different values

Installation, Activation, and the First Check

Technically, installing FacetWP is similar to installing any WordPress plugin from a ZIP file, but the first validation step is different. It is not enough to see a menu item appear in the admin area. You need to confirm that the plugin can create a facet, build the index, and render an element on the page. Do not start with ten filters. Start with one simple facet based on a reliable data source and one test listing.

Basic Sequence

1. Install the plugin ZIP file via Plugins - Add New - Upload Plugin, then activate it with Activate.
2. Open Settings - FacetWP and confirm that the tabs for facets, templates, and settings are available.
3. Create one facet using a simple data source: category, tag, product attribute, or another field that is definitely populated on several posts.
4. Save the facet and click Re-index if FacetWP indicates that the index needs to be rebuilt.
5. Display the facet on a test page using a shortcode or a supported block, and place a supported listing next to it.
6. Open the public page in a new tab and select a facet value. The listing should change without a full page reload.

If your first facet does not show any choices, do not build a second or third one "just to test." First walk through the base chain: the data source is populated, the index is built, the page contains a valid listing, FacetWP sees the right query, and caching is not breaking the scripts. Otherwise, you will add noise and make diagnosis harder.

What Counts as a Successful First Check

A successful start is not about the final design. It is about working mechanics. The page should show the facet, the facet should display meaningful choices, selecting one should change the listing, the URL may receive FacetWP parameters, and any other facets on the page should react to the current result set. If a visitor selects a value that no longer exists in the current results, a good configuration should not send them into a meaningless empty state.

Test with real data. A setup with two demo posts can be misleading. For your initial configuration, 10 to 20 items are enough, but they should cover different categories, prices, statuses, and field values.

Configuring Facets: Data Sources, Types, and Behavior

After installation, the main part of the job is creating facets. This is where mistakes happen easily, because the interface offers many options and users naturally want to build a polished sidebar right away. The better order is different: first choose the data source, then the interface type, then the behavior, and only then think about appearance.

The Data Source Matters More Than the Interface Type

The data source answers the question of which value FacetWP will index. For example, if you want a brand filter, the source should be the place where the brand is actually stored. If brand is stored as a WooCommerce attribute, use that. If it exists as a taxonomy for a custom post type, use that taxonomy. If it is stored as a free-text custom field, consider moving it into a taxonomy to avoid duplicates like Nike, NIKE, and nike.

For numeric filters, it is especially important that the value really be numeric, not a string with units attached. A price slider, square footage range, or year filter should operate on predictable values. If the same field contains "100," "100 sq ft," and "around 100," the index cannot produce clean numeric logic. That kind of cleanup needs to happen before you configure the facet.

Choosing the Facet Type

FacetWP includes many facet types: checkboxes, dropdowns, radio buttons, hierarchy, sliders, search, autocomplete, date range, number range, rating, proximity, map, pager, sort, reset, and user selections. Some are built in, and others are available through add-ons. You do not need to enable everything that looks interesting. A good filter interface usually consists of a few controls that users immediately understand.

For a taxonomy with 5 to 12 options, checkboxes or radio buttons are often the easiest to use. For a long list, dropdown or fSelect is usually better. For nested categories, hierarchy or hierarchy select works well. For prices and other numbers, slider or number range is the natural choice. For location-based items, proximity and map can be useful if the posts contain coordinates and visitors truly search by geography. For searching within filtered results, use a Search facet, and if ranking quality matters, consider combining it with SearchWP.

AND, OR, and Selection Logic

If a facet allows multiple choices, you need to decide how those choices should combine. OR logic works when the user means "red or blue." AND logic works when the result must match several attributes at the same time. The FacetWP recipe demos show the difference clearly: some facets broaden selection, while others create a stricter combination. On a real site, that choice directly affects how often users land in empty results.

Show Ghosts and User Expectations

Some interfaces can display options that would not currently return results, but show them as disabled or "ghosted." That can be useful when you want users to understand the full structure and see why certain options are unavailable right now. In an online store, it is often better to hide irrelevant options so users are not encouraged to produce empty results. In a directory or knowledge base, showing the full structure can sometimes be more useful.

Technical Name and Label

Each facet has a label and a technical name. The label is visible to the administrator and, depending on how the facet is rendered, to the visitor as well. The technical name is used in shortcodes like [facetwp facet="brand"]. Keep the technical name short and stable: brand, price, city, body_type. If you change it after launch, old links containing filter parameters may stop working.

What to Check After Saving

After creating or editing a facet, save the settings, rebuild the index, open the test page, and verify three things: the options appear, selecting one changes the listing, and the URL and other facets behave as expected. Only after one facet works should you add a second. This step-by-step approach is especially important for WooCommerce and custom post types, where the number of possible data sources is much larger.

The Indexer: When to Click Re-index and How to Keep the Site Fast

The indexer is one of the key parts of FacetWP. It makes filtering fast, but it also requires discipline. If the index is missing or built from outdated data, your facets may be empty, show incorrect counts, or ignore new posts. If you index an unnecessarily broad set of data, the process can take longer and push your server harder than needed.

When a Manual Re-index Is Required

The official documentation lists the cases when the index must be rebuilt. For everyday use, the five most important are these: you added a new facet, changed facet settings, imported content programmatically, changed term hierarchy or term fields, or modified code or hooks that affect indexing. A re-index is also required after clearing the index table or fixing index-related issues.

After a normal edit to a single post or term, FacetWP may update the index automatically. But bulk operations, imports, and structural changes should not be left to chance. If you imported 500 products through WP All Import or changed WooCommerce attributes, plan for a manual re-index and a listing check afterward.

How to Tell the Index Is Outdated

The first sign is when a facet does not show options that definitely exist in your data. The second is when the filter still shows old values after terms were deleted or renamed. The third is when new products or posts do not participate in filtering. The fourth is when counts and actual results do not match: the facet shows a value, but selecting it leads to empty results for no clear reason. The index is not always the culprit, but it should be one of the first things you check after the data source itself.

Performance and Large Catalogs

On large catalogs, the index can become very large because each index row represents a combination of facet, value, and post. If you have many post types, many products, many variations, many facets, and many choice values, the table grows quickly. The official performance guidance recommends limiting indexing to only the post types you actually need, reducing the number of facets and choices, avoiding unnecessary variation indexing, and not including out-of-stock products unless they matter to the user.

For WooCommerce, it is especially important to decide whether product variations and out-of-stock items should appear in filters at all. If the store does not show unavailable products, there is little reason to index them just for facets. If visitors need to filter by an attribute that exists only at the variation level, the setup becomes different. There is no universal answer called "the best FacetWP settings for every site." What matters is the relationship between the store's commercial logic and the index.

What to Do If the Indexer Gets Stuck

If the indexer seems stuck at one percentage value, first wait a few minutes and keep the settings screen open. The documentation describes built-in resume logic. If the process consistently stalls, check server errors, PHP memory limits, blocked self-requests, basic authentication, security rules, and hosting-specific restrictions. Do not jump straight to reinstalling the plugin. In many cases, the real issue is a server limit or the site's inability to send requests to itself.

A safe habit: after every major import or facet change, run a short verification sequence: re-index, open the page, select two or three values, check counts, open the console, and confirm there are no Ajax errors.

Displaying Results: Shortcodes, Blocks, Listing Builder, and Archives

FacetWP can be rendered in several ways, and this is where many first implementations break down. You can place a facet with a shortcode, in a widget, inside an editor block, in a PHP template, or through a builder integration. But the correct listing has to be there as well. If a facet appears on a page without a FacetWP-enabled listing, it cannot function as a real filter.

Shortcodes

The documentation describes the basic facet shortcode as [facetwp facet="the_facet_name"]. For a Listing Builder template, use [facetwp template="the_template_name"], and for active selected conditions, use [facetwp selections="true"]. These shortcodes can be inserted into the page editor, a text/HTML widget, a Shortcode block, or a builder module if it renders shortcodes correctly.

Shortcodes are convenient for getting started quickly, but they do not solve the listing question by themselves. If you inserted only the facet and there is no listing that FacetWP can recognize, the facet may show no options. If the listing exists but FacetWP detects a different query, the filter will behave unpredictably. That is why the first test page should be as transparent as possible.

Listing Builder

Listing Builder is useful when you need to assemble cards quickly without building a separate theme template. It gives you a controlled listing inside FacetWP that can be displayed with a shortcode. This works well for directories, smaller catalogs, and pages where the theme does not provide a good loop template. At the same time, Listing Builder does not need to replace everything your theme already does well. If you already have a strong WooCommerce archive or custom template, connecting FacetWP to that existing output may be the better choice.

In Listing Builder, pay attention to the Query tab, the number of posts, sort order, card content, and the "No results" text. If the page is meant to serve as an SEO landing page or a content-heavy catalog, think not only about how the cards look, but also about how the page behaves when nothing matches. A blank page with no guidance frustrates users more than a clear message suggesting that they reset the filters.

WordPress and WooCommerce Archives

FacetWP can work with WordPress and WooCommerce archives when it detects the correct query. In WooCommerce, it is often enough to place the facets in a sidebar while the shop loop is detected automatically. But themes, custom templates, and builders can change the structure. If the filter does not react, review the documentation for your listing template type and enable Advanced query detection if it fits your case.

Custom WP_Query

If the listing is built manually with WP_Query, FacetWP may not detect it automatically. The documentation on the right query explains that a custom query should include the argument "facetwp" => true, and the listing container must be marked correctly. This is already developer territory: a misplaced facetwp-template class or multiple active queries on the same page can create subtle problems that are difficult to trace.

A Minimal Container Check Template

If you are working with a developer, ask them to confirm that the facetwp-template class wraps the entire loop, including the no-results branch. There is no need to copy a large theme template into this article, but the logic should look like this:

<div class="facetwp-template">
  <!-- The main loop or result cards should go here -->
</div>

After that change, inspect the page source and verify that the class appears only once for the active listing. If it appears multiple times, FacetWP may end up filtering the wrong list.

Post-Install Settings Worth Reviewing Before Launch

Once your first facet works, it is worth doing a separate pass through the settings. This is not the stage where you "turn on everything good." The goal here is different: make filtering behavior predictable for visitors, understandable for editors, and safe for site performance. FacetWP offers a lot of flexibility, but some options only make sense with a certain kind of content structure.

Review the Global FacetWP Settings

Open the FacetWP settings tab and review which options are already enabled. Debug Mode should be off in normal operation. If you used it for troubleshooting, leave yourself a note and disable it after the issue is resolved. Automatic indexing is usually helpful because individual edits to posts and terms are picked up without a full re-index. But on large import-heavy projects, it can make more sense to manage indexing manually, on a schedule, or after a batch import. That decision should be made by a technical specialist who understands the data volume and server load.

If the settings include a WooCommerce section, do not enable product variations or out-of-stock indexing mechanically. First ask whether those objects are part of the visitor's actual selection flow. If visitors filter parent products and the variations matter only on the product page, extra indexing can increase table size without visible benefit. If variation attributes are a key filtering dimension, then they should be included deliberately, followed by a fresh index rebuild.

Set Up Active Selected Conditions

When you have more than two facets, visitors need to understand why the result set suddenly became shorter. That is what user selections are for. This block shows the currently active values and lets the user remove one condition at a time. It is especially important on mobile, where the filter panel may be hidden inside a slide-out drawer. Without user selections, someone may see only three products and have no idea which filters caused it.

Place user selections near the listing heading or above the cards. If they appear below the list or inside a hidden panel, they become much less useful. You can place a reset control nearby, but do not make reset the only way to manage state. Users should be able to remove one condition without losing all the others.

Think Through Sorting and Pagination

Sorting and pagination often conflict not because FacetWP is weak, but because the theme, WooCommerce, and the plugin are all trying to control the same part of the page. If your theme's default sorting works correctly, keep it. If Ajax updates cause it to lose state or show the wrong order, consider a Sort facet. The same applies to pagination: your theme's built-in pagination may work, but on more complex pages, FacetWP's pager or load more control is often more reliable if it matches the UX you want.

After changing sorting, always test the full sequence of "apply a filter - go to the next page - change the filter - reset." A common failure mode is that the visitor remains on a pagination page where the new combination has no results, and concludes that the filter is broken. A good configuration sends them back to the logical start of the listing or recalculates the state correctly.

Match the Empty State to the Tone of the Site

An empty result is not just a technical edge case. It is part of the interface. In an online store, the message can be short: "No results found. Remove one of the filters or reset your selection." In a knowledge base, you might add a suggestion like "Try selecting fewer topics or use search instead." In a directory, it can help to recommend nearby categories. Listing Builder includes a "No results text" setting, and for custom output you can use a documented hook, but check the built-in option first.

Make Sure Editors Understand the Data Rules

FacetWP has to keep working long after launch day. A month later, an editor will add a new product, a content specialist will change a category, a manager will import a spreadsheet, and a developer will update a template. To keep the filtering from degrading over time, document a few simple rules: which fields are required, which values must be chosen from a predefined set, which values should never be entered freely, when a re-index is required after an import, and who verifies the filters after bulk changes. This matters especially for WooCommerce attributes and ACF fields.

Settings and decisions after the first successful setup

Decision	When to Enable It	What to Check After Enabling
User selections	When the page has more than two facets or filters are hidden on mobile	Active conditions are visible and each can be removed individually
Reset facet	When visitors can build a strict filter combination	Reset restores the full listing and clears the URL state
Sort facet	When theme sorting conflicts with Ajax or you need a single FacetWP sorting logic	The order stays consistent after filtering and pagination
Mobile Flyout	When facets take up too much space on phones	The panel opens, closes, applies the selection, and does not cover the results
Caching add-on	When filtering is genuinely slow on a large site and baseline optimization is already in place	Speed improves and the options and counts do not become outdated after data changes

Integrations with Blocks, Builders, ACF, and Search

FacetWP is often added to sites that already use ACF, WooCommerce, SearchWP, editor blocks, or visual builders. That is completely normal, but each integration changes the point where something can go wrong. The core principle stays the same: the plugin must understand both the data source and the listing. The integration simply helps it fit into a specific environment.

ACF and Custom Fields

Advanced Custom Fields is often used for catalog-style sites: square footage, city, event date, difficulty level, coordinates, checkboxes, relationship fields, and repeaters. FacetWP can build facets from ACF fields, but the quality of the result depends heavily on the field type. For ranges, use numeric values. For selectable options, store normalized choices. For relationship or repeater fields, check both the documentation and a test index carefully, because complex fields may behave very differently from a basic taxonomy.

If editors can enter values freely, the facet quickly turns into a junk list. For example, "New York," "NYC," "new york," and "New York City" may become separate choices. For the front end, a select field or taxonomy is usually a better fit. ACF is convenient as an input layer, but you still need data rules behind it.

WordPress Blocks and Query Loop

On block-based sites, it is important to verify support for the specific block you plan to use. The official FacetWP documentation covers the Blocks add-on and supported blocks, including some Query Loop and Product Collection scenarios. Do not assume that any custom block displaying cards will automatically become a FacetWP-enabled listing. If a block is unsupported, it may be easier to use Listing Builder, a theme archive, or a custom WP_Query.

With a block-based setup, a dedicated test page is especially valuable. Create a draft, add one supported listing, add one facet, and verify the Ajax behavior. After that, move the solution into the template. If you begin directly inside a production template, it becomes much harder to tell whether the problem comes from the block, the theme, caching, or a specific facet.

Elementor, Beaver Builder, Bricks, and Other Builders

FacetWP offers add-ons for certain builders. If you are using Elementor, Beaver Builder, or Bricks, open the relevant FacetWP documentation first and install the matching integration add-on. Do not try to fake the integration with shortcodes alone if the page renders cards through a specialized loop builder. The facet may appear, but it still may not connect to the correct listing.

For unsupported builders, manual workarounds are sometimes possible, such as adding facetwp-template to the right container, but that is not a universal guarantee. In those cases, decide early who will maintain the setup after future builder updates. If the project is commercial and the catalog matters, a supported rendering pattern is usually a better foundation than a one-off workaround.

SearchWP and Search Relevance

FacetWP can filter search results, and integrating it with SearchWP is useful when native WordPress search is too limited. SearchWP can handle relevance, custom engines, and deeper searching across fields, documents, or eCommerce data. In that setup, FacetWP refines the results returned by the search engine.

The important thing is to keep the roles separate. If the visitor enters a text query, the Search facet can use the selected SearchWP engine. If the visitor chooses a category, brand, or numeric range, that is FacetWP's filtering logic. After setup, test the scenarios separately: empty search, search with one filter, filtering without search, resetting search, and reopening the URL. That will show you exactly where relevance ends and structured refinement begins.

Multilingual Sites

FacetWP includes a multilingual add-on for WPML and Polylang. On a multilingual site, it is not enough to translate the labels. You also need to rebuild the index after configuration. Confirm that facet values match the current language version, that the URL stays in the correct language, and that user selections and the No results text do not mix languages. If the project includes ACF fields, clarify whether those fields are translated as separate values or shared across languages.

FacetWP in WooCommerce: Product Filters, Attributes, and Availability

WooCommerce is one of the clearest use cases for FacetWP, because stores almost always need filters. At the same time, WooCommerce introduces many of the most important nuances: attributes, variations, stock status, sorting, pagination, the shop archive, and theme behavior. A problem in any one of those areas can look like "FacetWP is not working," when the real issue is the product data or the listing query the plugin sees.

Which Data to Use

The official WooCommerce documentation lists sources such as price, sale price, regular price, average rating, stock status, on sale, featured, product type, product categories, product tags, and product attributes. In practical terms, that means you can usually build a clean store sidebar without inventing new fields: category, brand or attribute, price, stock status, rating, discounts, and product type are often enough.

But not every store should show all of them. For a clothing catalog, size, color, category, and price may be the right set. For digital products, it might be license type, compatibility, category, and update date, if that data exists. For a B2B catalog, manufacturer, technical parameters, availability, and industry may be more useful. Too many facets increase cognitive load and can bloat the index without helping users.

Stock Status and Out-of-Stock Products

WooCommerce can hide out-of-stock products from the catalog through a global setting. By default, FacetWP does not index out-of-stock products, but the WooCommerce integration settings let you enable that behavior if it matches the store logic. After changing the setting, run a re-index.

The right choice depends on the business model. If the store does not sell unavailable products and does not show them in the archive, there is no need to index them. If products are temporarily unavailable but visitors should still see the assortment, you may want to keep them in the catalog and label the status clearly. The key is that the WooCommerce listing and the FacetWP index should follow the same logic. Otherwise, users may apply a filter and fail to see the products they expect.

Product Variations

FacetWP can work with variable products, but one limitation matters: the facet filters posts, and the parent product remains the main object in the listing. Variation attributes can participate in filtering parent products, but that is not the same thing as displaying each variation as its own card. If your business logic requires separate variations to appear as separate results, you will need additional architecture and a separate compatibility review.

A Practical Starter Set for the First Shop Page

For the first store setup, do not begin with a full filter panel. Start with three or four facets: category, price, one key attribute, and stock status. Add user selections and reset if visitors need clear visibility into active filters. Verify that WooCommerce sorting and pagination do not conflict with FacetWP. If the theme's standard sorting behaves unpredictably, replace it with a Sort facet or use the integration method recommended in the documentation.

Practical Example: A Product Catalog Filtered by Brand, Price, and Availability

Let us look at a concrete scenario. We have a WooCommerce store with products, categories, a "Brand" attribute, prices, and stock status. The goal is to build a shop page where the visitor chooses a category, brand, and price range, then sees only matching products without a full page reload.

Goal

Create working product filtering on the shop archive: the facets appear in a sidebar or above the product list, the selected conditions are visible to the user, the results update through Ajax, the empty state shows a clear message, and reset returns the user to the full product list.

Preparation

• The store has at least 20 products with different categories, brands, and prices.
• The brand is stored as a WooCommerce attribute or a clean taxonomy, not as free text inside the description.
• The shop archive is rendered by the theme or a supported integration so FacetWP can detect the listing.
• Aggressive script optimization is disabled on the test page during setup.

Setup Steps

1. Open Settings - FacetWP and create a category facet. Use product categories as the source and choose checkboxes or dropdown depending on how many categories you have.
2. Create a brand facet. The data source should be the brand attribute or the related taxonomy. Use checkboxes for a short list, or dropdown/fSelect for a longer one.
3. Create a price facet. Use WooCommerce price as the source and choose slider or number range. Keep the labels simple if the store uses one currency and the price is already clear from the product cards.
4. Create a stock-status facet if visitors need to exclude unavailable products. Keep that decision in sync with the WooCommerce Out of stock visibility setting and the FacetWP setting for indexing out-of-stock items.
5. Add the facets to the shop page. In a theme with a sidebar, you can use a text/HTML widget or a shortcode block. In a custom layout, use the supported builder method.
6. Add reset and user selections if you have more than two filters. This helps visitors understand why the list became shorter.
7. Save the changes, run Re-index, clear the cache for the test page, and open the shop archive in a new tab.

Verifying the Result

Select a category, then a brand, then a price range. In a good setup, the product count drops predictably, unavailable choices disappear or become disabled based on your settings, the URL reflects the selected conditions, user selections show the active filters, and reset restores the full listing. Check more than the first screen. Test pagination too: after a filter is applied, the user should not remain on a pagination page where there are no longer any results.

A Common Obstacle

If no products appear after selecting a brand even though those products exist, do not check only FacetWP. The attribute may be set on variations while the listing shows parent products. WooCommerce may be hiding out-of-stock products while FacetWP indexes them differently, or not at all. The theme may also be using a non-standard query. Work through the chain from data to output: product - attribute - index - archive query - facet - public check.

Use Case Ideas for Different Types of Sites

FacetWP is not limited to online stores. Its real value appears anywhere visitors need to find the right item quickly among many similar ones. The ideas below are not abstract "features." They are practical scenarios that can be turned into real facets once the underlying data has been verified.

Real Estate or Property Listings

For real estate, natural facets include city, neighborhood, property type, price, square footage, number of rooms, status, parking availability, and a map. The interface should not be overloaded. Users usually set their main constraints first, then refine the details. If coordinates are available, map or proximity filtering may be more useful than a simple neighborhood list, but only if distance-based selection really matters to the audience.

Recipe and Content Databases

For recipes, categories, ingredients, cooking method, diet, time, difficulty, and seasonality often work well. Here, AND/OR logic matters a lot: selecting two ingredients may mean "both must be present," while selecting cooking methods may mean "any of these works." That decision should be made with the content editor before launch, otherwise the filter may be technically correct but logically confusing for the audience.

Document or Knowledge Libraries

For a document library, useful facets may include content type, topic, department, year, format, difficulty level, and search. If searching inside the document content is critical, FacetWP should be paired with a stronger search engine. In that setup, FacetWP handles filters and structure, while the search engine handles text relevance.

Portfolios and Case Studies

In a portfolio, facets should help potential clients find relevant work: industry, service type, technology, budget range, region, and outcome. There is usually no point in filtering by every blog tag. A strong portfolio filter reflects how a client actually evaluates work: "show me projects in my niche with a similar business problem."

Expert Directories or Job Boards

For expert directories, useful facets may include city, specialization, appointment format, experience, language, availability, and rating if the rating is genuinely used. For job boards, think city, work format, level, department, salary range, and tech stack. On these pages, the empty state matters especially: users should understand how to broaden their search instead of seeing a blank screen.

How to Verify the Setup After Configuration

Once your facets are in place, do not stop at a visual check. FacetWP changes the listing, the URL, Ajax requests, the state of other facets, and sometimes the interaction with caching. A short verification protocol is worth repeating after every major change.

The Public Front End

Open the page as a regular visitor, not as an administrator. Select one facet, then a second one, then clear the selection. Confirm that the listing updates quickly, the card layout stays intact, pagination remains logical, active selections reflect the current state, and the reset button truly clears the filters. Repeat the check in another browser or in a private window so the admin session does not affect the result.

URL and Reload Behavior

FacetWP uses URL parameters for active facets. Copy the link after selecting filters and open it in a new tab. The page should restore the same conditions. This matters for users who share links, return to a filtered set later, or open the page from an email. If the URL does not restore state correctly, check caching, script conflicts, and the correctness of your facet names.

Console and XHR

Open developer tools and check the console. There should be no JavaScript errors triggered when clicking a facet. In the Network tab, you can filter by XHR and confirm that FacetWP requests return successfully. If you see 401, 403, 404, or 5XX responses, do not keep changing facets blindly. Investigate permissions, REST/API access, firewall rules, server errors, or memory limits first.

Debug Mode Only During Troubleshooting

FacetWP includes a Debug Mode that can show query arguments, SQL, template data, pager details, and other information in the console. That is useful when the wrong listing is being filtered or when queries are conflicting. But the official documentation recommends disabling Debug Mode after troubleshooting because it exposes part of the setup and may affect performance. It is not meant to remain enabled in normal operation.

Mobile Testing

If the page contains many filters, test the mobile scenario separately. A sidebar that works well on desktop may fall below the product list on a phone and become effectively invisible. For those cases, FacetWP offers the Mobile Flyout add-on, but it should be enabled only if the mobile audience truly cannot use the filters comfortably. Sometimes a better facet placement in the theme is enough.

Safe Enhancements and Small Customizations

FacetWP has a developer-friendly reputation and a large set of hooks, but that does not mean every project needs custom code. Code is useful when the built-in settings are not enough for a specific small task. Below are two safe directions: styling the facet panel with CSS and customizing the empty-state text with a documented hook.

Clean Styling for the Facet Panel

If your theme displays the facets too tightly, start with CSS in a child theme or another safe place for custom styles. Do not edit plugin files. First add classes to the wrapper in the template or block, then style only the outer layer. The example below does not depend on the internal structure of a specific facet, which makes it safer than trying to target deep plugin classes.

.catalog-filters {
  display: grid;
  gap: 18px;
  padding: 18px;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  background: #ffffff;
}

.catalog-filters .facetwp-facet {
  margin-bottom: 0;
}

.catalog-filters .facet-title {
  margin: 0 0 8px;
  font-weight: 700;
}

The check is simple: clear the cache, open the page, select several filters, and make sure the Ajax refresh does not strip the styling. If the theme or optimization plugin changes CSS behavior after Ajax, enqueue the styles through the theme normally instead of placing them inline in the content.

Clear Text When There Are No Results

For Listing Builder, the documentation includes a "No results text" setting. If that is enough, use it. If you need full control over the output, FacetWP documents the facetwp_template_html hook. That code should be added through a child theme, Code Snippets, or the Custom Hooks add-on, not inside plugin files.

<?php
add_filter( 'facetwp_template_html', function( $output, $class ) {
  if ( $class->query->found_posts < 1 ) {
    $output = '<p class="facetwp-empty">No results found. Clear one of the filters and try again.</p>';
  }
  return $output;
}, 10, 2 );

After adding it, open the page, choose a deliberately strict combination of filters, and verify the message. Reverting is simple: disable the snippet or remove the filter from the child theme. If the site is multilingual, the string should be handled through the site's normal translation system instead of hardcoding one language for every version.

What You Should Not Try to Fix with Code

Do not use code to paper over a problem caused by messy data, the wrong query, or caching. If a facet is empty because the field is not populated, CSS or PHP will not fix it. If FacetWP is filtering the wrong loop, fix the listing template first. If the indexer is hitting memory limits, a decorative snippet only distracts from the real issue. Code-based enhancements should improve a system that already works, not hide a broken baseline configuration.

Why FacetWP Does Not Show Filters or Behaves Incorrectly

The easiest way to troubleshoot FacetWP is to follow the chain in order: data - index - listing - placement - Ajax - cache - third-party plugins. If you jump between those layers, it is easy to waste time chasing the wrong theory. Below are common symptoms, likely causes, and safe checks.

The Facet Shows No Options

Symptom: the facet appears on the page, but the value list is empty. Sometimes the container is visible, and sometimes it looks like the shortcode rendered nothing at all.

Possible causes: the data source is not populated, the wrong data source was selected, the index was not rebuilt, the page has no FacetWP-enabled listing, the post type is not being indexed, or the post type is excluded from search.

What to check: open several posts or products and confirm that the field is actually filled in. Then run Re-index. Make sure the page contains a supported listing. If this is a custom post type, confirm that it is searchable and participates in the relevant query.

How to fix it: choose the correct data source, rebuild the index, and simplify the page down to one listing and one facet. If the issue disappears, add the remaining elements back one at a time.

The Filter Exists, but the Listing Does Not Change

Symptom: the user selects a value, the URL or facet state changes, but the cards remain exactly the same.

Possible causes: FacetWP is not detecting the right query, the facetwp-template container is misplaced, the page contains multiple active listings, the builder outputs an unsupported loop, or the cache is serving stale HTML.

What to check: enable Debug Mode temporarily and inspect which template or query FacetWP is using. Check the page source for the number of facetwp-template instances. For a custom WP_Query, verify the "facetwp" => true argument.

How to fix it: keep one active FacetWP-enabled listing, enable Advanced query detection if it fits the case, or configure the container manually in the template. After troubleshooting, turn Debug Mode back off.

The Layout Breaks After an Ajax Refresh

Symptom: the cards look fine on initial page load, but after applying a filter, the grid, lazy load, Masonry, Isotope, or theme scripts stop working.

Possible causes: the theme or another plugin enhances the cards with JavaScript only on the initial page load. After Ajax, FacetWP replaces the HTML, but the third-party script is never reinitialized.

What to check: temporarily disable script optimization and any plugins that alter the grid or lazy loading. Check the browser console. If the issue disappears after disabling one specific enhancement, you have identified the source.

How to fix it: use a compatibility setting provided by the theme or plugin, disable the conflicting feature on the filtered page, or ask a developer to reinitialize the required script cleanly on the facetwp-loaded event. Do not add random JavaScript unless you understand exactly which script needs to be re-run.

The Indexer Gets Stuck

Symptom: re-indexing sits at one percentage for a long time or never completes.

Possible causes: low memory, an excessively large index, blocked self-requests, basic authentication, firewall restrictions, hosting limits, a server-side error, or a conflict related to imports.

What to check: wait a few minutes while keeping the settings screen open. Then check the error log, debug.log, REST/Ajax availability, security rules, and hosting restrictions. On a large catalog, review whether you are indexing unnecessary post types, variations, or out-of-stock products.

How to fix it: reduce the size of the index, limit unnecessary post types through documented methods, use cron or CLI only when justified, and address memory or request-blocking issues. If the site is protected with HTTP Basic Authentication, use the documented method for passing the necessary data with self-requests. Do not confuse that with your WordPress login.

The Filter Produces Empty Results Too Often

Symptom: users can easily select combinations that lead to no results, even though the interface is supposed to help them narrow things down.

Possible causes: incorrect AND/OR logic, too many facets, poor Show ghosts settings, fragmented data, choices that do not reflect the current results, or hidden active selections.

What to check: test 10 realistic user scenarios. Look for the point where the selection becomes too strict. Add user selections and reset if people do not understand the current state.

How to fix it: simplify the facet set, change the selection logic, hide irrelevant choices, or show ghost choices where they genuinely help users understand the system. In online stores, fewer facets often work better as long as they reflect meaningful buying criteria.

Cache or CDN Interferes with Filtering

Symptom: everything works for the administrator, but visitors see frozen filters, outdated states, or missing Ajax requests.

Possible causes: page caching, removal of HTML comments, deferred FacetWP scripts, minification, firewall or CDN behavior, or an optimizer conflict.

What to check: clear the cache, disable optimization only for the test page, and inspect the Network tab and console. Make sure the cache is not stripping HTML comments that FacetWP needs in certain scenarios.

How to fix it: create exceptions for the filter page, disable defer or delay for the necessary scripts, preserve important HTML comments, and review CDN rules. Re-enable optimization one setting at a time and repeat your verification scenario after each change.

Performance, SEO, and Usability on Filtered Pages

FacetWP affects more than the interface. It changes how visitors move through a catalog, how URLs are formed, how Ajax requests behave, and how quickly the site responds to refinements. After the baseline setup is working, you should think about performance, search engine indexing, and overall UX.

Do Not Index Unnecessary Data

The more facets and choices you have, the more rows accumulate in the index table. If a filter by author does not help users, do not create it "just in case." If product variations do not appear in the listing, do not index them without a clear reason. If the catalog contains 50 terms but visitors only need the top 10 categories, rethink the hierarchy and interface instead of dumping a long list into the sidebar.

Filtered URLs and SEO

Filtered URLs are useful for visitors: they can be shared and reopened later. But not every filter combination should become an SEO page. If the site generates thousands of thin combinations, the search value may be very low. FacetWP improves the interface, but the indexing strategy for filtered URLs is a separate decision involving your theme, SEO plugin, canonical rules, robots directives, and overall site logic.

A good rule of thumb is to keep the main category or landing page indexable, while treating deeper filter combinations primarily as user tools. If a specific combination has real search demand, such as "Nike sneakers size 9," it is usually better to create a managed SEO landing page or a well-planned category than to rely entirely on a random facet URL.

Empty Results as a UX Task

An empty result is not always an error. Sometimes the user simply chose a combination that is too restrictive. But the interface should help them recover. Add a clear "No results" message, show active filters through user selections, provide a reset option, and do not hide the selected conditions too deeply. In more complex catalogs, think carefully about which facets should disappear and which should remain visible as ghost choices.

The Mobile Scenario

On mobile, filters often take up more space than the actual cards. If visitors cannot even tell where to open the filters, all the work you put into FacetWP is wasted. Check that the filter button is visible, the panel does not cover important elements, reset is accessible, and after applying a filter the user sees the updated results rather than staying inside a closed panel with no feedback.

Questions About FacetWP Setup and Limitations

Can you use FacetWP without a developer?

For a simple archive, WooCommerce shop page, or Listing Builder setup, often yes, as long as the data is already structured well and the theme does not interfere with the listing. But if the page is built with a custom WP_Query, a non-standard builder, or complex logic, a developer will save a lot of time during setup and troubleshooting.

Why do you need to click Re-index after creating a facet?

FacetWP uses an index table for fast lookups. When you add a facet or change its settings, the old index does not know about the new logic. That is why Re-index is required after those changes. Without it, the facet may be empty or show outdated choices.

Is FacetWP a good fit for WooCommerce filters?

Yes. The official documentation describes built-in WooCommerce support, including product categories, tags, attributes, price, rating, stock status, and other data sources. But the final result still depends on the theme, the shop loop, stock settings, variations, and how consistently product attributes are filled in.

Can it filter pages and custom post types?

FacetWP can work with posts, pages, and searchable custom post types as long as they participate in a supported listing. If the post type is excluded from search or rendered through a non-standard query without the right setup, the facets may not see it.

What should you do if FacetWP shows the wrong results?

Check which query the plugin is using. Turn on Debug Mode only while troubleshooting, inspect the console data, and confirm that the page has one active FacetWP-enabled listing. After troubleshooting, Debug Mode should be turned off again.

Do you need to enable every add-on?

No. Add-ons should be enabled for specific needs only: Blocks, Elementor, Beaver Builder, Bricks, Mobile Flyout, Conditional Logic, Caching, Map, or extra facet types. The fewer unnecessary moving parts you have, the easier the site is to maintain and troubleshoot.

Does FacetWP make the whole site faster?

It speeds up filtering specifically through the index table and Ajax updates, but it is not a general optimization plugin. On a large catalog, poor data sources, too many facets, a heavy theme, or a cache conflict can still slow the page down. Performance should be tested in a real usage scenario.

Can FacetWP be used together with SearchWP?

Yes. The official documentation describes integration with SearchWP. That is useful when you need not just structured filtering, but also stronger text-search relevance. In that setup, test the Search facet, the selected SearchWP engine, and the supported listing template separately.

When FacetWP Is the Right Choice

FacetWP is worth using when your site contains a large set of structured posts, products, or other items and visitors need to narrow the results quickly by several attributes. The plugin works especially well when you are ready to handle the data carefully: choose the right data sources, build the index, connect one clear listing, verify Ajax behavior, define a usable empty state, and avoid adding extra facets just for appearance.

Do not expect FacetWP to fix weak information architecture on its own. If fields are filled inconsistently, categories are duplicated, product attributes are mixed into free text, and the listing page is built with an unstable builder, clean up the foundation first. Then FacetWP becomes a proper interface layer on top of clean data, not a workaround for a broken structure.

Before rolling it out fully, run a small pilot: one listing type, three or four facets, re-index, then verify the URL, mobile behavior, caching, and empty-state handling. If the pilot works, you can expand the panel and add user selections, reset, sort, pager, Mobile Flyout, SearchWP, or WooCommerce-specific refinements. If the pilot fails, do not add complexity before you diagnose the issue.

When you are ready to test the plugin on your own site, go to the download section and download the installation package. After installing it, begin with a test page and a short verification flow: create a facet, build the index, render the listing, apply a filter, verify the result, and only then move the setup to an important catalog page.