FacetWP Flyout - WordPress Plugin

A Practical Guide to Configuring FacetWP Flyout

FacetWP Flyout is best understood not as a separate search form, but as a mobile layer for an existing faceted filtering system. It does not create its own categories, prices, or product attributes, and it does not replace the results list. Its purpose is different: on narrower screens, it moves existing filters into a slide-out panel, leaves a compact entry point on the page, and prevents visitors from scrolling through a long column of checkboxes before they reach the first product.

This guide focuses on the decisions that determine whether the setup is easy to understand and reliable: how to prepare the listing, add an open button, align the mobile breakpoint, define the panel contents, display active selections, and test the behavior in a real catalog. It also covers cases where the panel opens but does not change the results, shows duplicate conditions, or appears as an empty area.

The name FacetWP Flyout is often used for the add-on that is called Mobile Flyout in the official documentation. In this guide, the name refers to the add-on for the main FacetWP plugin. It works on top of facets already configured for one filterable listing on the page, so the quality of the mobile panel begins not with button styling, but with a correct connection between the facet and the listing.

What Changes on the Page When You Add a Mobile Panel

A useful way to understand the setup is as three layers. The first layer is the filterable listing: a product catalog, real-estate archive, recipe list, portfolio, or another post listing. The second layer is the FacetWP facets, such as category, price, color, stock status, search, and reset. The third layer is Flyout, which places suitable facets into a sidebar panel opened by the visitor. If either of the first two layers is missing or configured incorrectly, Flyout cannot fix that problem. It only presents the interface for filtering that already exists.

After the initial page load, FacetWP identifies the facet elements and the listing container, collects active values, and updates them through AJAX. FacetWP documentation describes the response as a set of HTML updates for the listing and each facet. Mobile Flyout uses those same data and frontend elements; it does not create a second independent catalog request. As a result, a filter selected in the panel should update the product cards, the available choices in other facets, and the URL parameters at the same time.

This explains two important details. First, by default, the panel receives facets in the same order in which they appear on the page. Second, those facets must be present in the source HTML so the add-on JavaScript can find them. You can hide the regular sidebar with CSS at mobile widths, but you cannot physically remove it from the markup, render it only after a click, or replace it with an unrelated copy. Otherwise, visitors may see the button, but Flyout will have no source elements to use.

Which Elements Are Added to Flyout Automatically

The standard approach works well for a catalog with several conditions: the page contains checkbox, dropdown, range, and search facets, and the add-on gathers them into one panel. Pager, Map, and User Selections are not included automatically by default. That exclusion is sensible: pagination normally stays near the results, a map needs its own space, and active selections are best added deliberately to the panel template when they are needed there.

Automatic inclusion does not mean the order is already optimal for a phone. On a mobile screen, the conditions that narrow the listing most effectively should come first, followed by secondary refinements and only then reset or apply actions. If the desktop blocks follow a different order, do not rebuild the entire page just for mobile. It is safer to keep the desktop layout and create a dedicated Flyout template with the {content} placeholder described below.

When This Approach Fits and When Another Option Is Better

FacetWP Flyout suits a site where filtering is already useful, but becomes difficult to use on mobile because of limited space. Typical examples include stores with attributes, service catalogs, property databases, specialist directories, and content libraries. Visitors see the cards, click a clear button, and get the conditions without a sidebar taking up the entire above-the-fold area. The approach works especially well when there are relatively few active facets and their labels are clear without extra instructions.

Do not enable Flyout as a decorative replacement for poorly designed search. If the catalog has no suitable data sources, facets return empty results, two competing queries affect the listing, or the page contains only one toggle, the panel adds an unnecessary click. In that case, it is more useful to fix FacetWP, the listing, and the card content first. For a single simple condition, leaving the filter directly above the results can be more honest and efficient. For a large set of conditions, Flyout does not eliminate the need to work on labels and ordering: a panel with twenty unstructured fields remains difficult to use even if it slides in elegantly.

Preparation: What to Check Before Installing the Add-On

Start with a real page rather than a test button. Open the target catalog at desktop width and select each condition one at a time. After every selection, verify three signs: the listing cards changed, nearby options reflect available values, and the page URL gained or changed selection parameters. This short test reveals problems before the mobile layout disguises them as a panel issue.

The main FacetWP plugin must be installed and have a working listing. Product documentation emphasizes that a page can contain multiple listings, but only one should be enabled for FacetWP and respond to facets. In most cases, this is either a WordPress or WooCommerce archive, Listing Builder, or a supported editor or page-builder integration. If the page contains two dynamic listings, first decide which one visitors should actually filter, then make the others static or move them to a separate URL.

Check Data Sources and the Index

A facet does not read the text visible on a card. It reads a specific source: a taxonomy, post field, custom field, WooCommerce attribute, or another selected source. Create or open a facet and check its Data source. Then take two clearly different items and confirm that their data actually contains the expected value. For example, you cannot reliably build a "Brand" filter from arbitrary text in a product description if the facet is configured to use a brand attribute that is empty for those products.

After adding facets or making bulk data changes, run a full FacetWP re-index. The index stores values for fast filtering separately from normal WordPress output. Automatic updates help when an individual post is saved, but they do not replace a deliberate full check after a catalog import, source change, or bulk term update. During testing, do not merely confirm that the process has finished. Make sure the new option appears in the filter and leads to the expected card.

Aligning Interface Widths

Flyout does not have a magic width that works equally well with every theme. The official example separates desktop and mobile interfaces at around 780 pixels, but that is a guideline for a coordinated pair of rules, not a required number. Measure the point at which the desktop filter column starts crowding the listing. At that same width, the Flyout button should appear and the regular column should disappear or stop taking up space. If the button becomes visible before the column is hidden, visitors will see duplicates. If it appears later, there will be a range where filters are both inconvenient and unavailable.

Test not only a narrow phone width, but also an intermediate tablet width. That is where misalignment often appears: the theme has already rearranged the card grid, but the Flyout rule has not yet activated, or the slide-out panel overlaps the heading. A good checkpoint is a state where the page shows a button, a count, or a short selection summary along with the first results, while full conditions appear only after a deliberate user action.

Do not hide facets with a condition that removes them from the DOM. Mobile Flyout requires the source facets to remain in the page HTML. Hide the desktop container with CSS at the appropriate width instead of removing blocks through a builder, inserting them later, or loading them separately.

Installation and an Initial Test Without Unnecessary Theme Changes

The installation order should be straightforward: first install the main FacetWP plugin, then the Mobile Flyout add-on, and then make sure both components are active in the WordPress admin area. Use the add-on file intended for your FacetWP installation and do not edit its folder. Any changes inside the add-on will disappear during an update and make troubleshooting harder. If the admin screen does not show the expected options after installation, first make sure the add-on is actually active instead of trying to compensate with custom code.

Next, open the page where the listing already works and add a minimal button. For the first test, a regular HTML button with the class specified in the documentation is enough. Use a human-friendly label: "Filters," "Find Products," or "Refine Search," depending on context. Do not call the action "Menu" if it does not contain site navigation. Visitors should understand in advance that it will open listing conditions.

<button class="facetwp-flyout-open" type="button">Filters</button>

Place the button near the listing heading, results count, or above the card grid. This position creates a clear cause-and-effect relationship: visitors change conditions for the results displayed below. The button can work technically inside a hero section, site-wide header, or separate mobile menu, but it explains its role less clearly there. After saving, clear only the usual server and browser caches if that is part of your workflow, then test the page in a new private window.

First Test: Open, Select, Close, Return

1. Open the catalog at a width where the button should already be available.
2. Click the button and confirm that a sidebar panel appears with the same clear conditions as the working desktop version.
3. Select one option, wait for the listing to update, and verify that the visible card list actually changed.
4. Close the panel and make sure the selected condition has not been lost and visitors can still understand how to change or reset the selection.
5. Refresh the page and use the browser's "Back" button to verify that the URL preserves the state.

If the first three steps work, do not rush to add effects, counters, or extra scripts. At this point, the main chain is already confirmed: the opening element triggers Flyout, the facet changes FacetWP state, and the AJAX response redraws the listing. Any later customization should preserve this chain rather than create a second one alongside it.

Using Elementor and Beaver Builder

When the FacetWP add-on for Elementor is installed, you can use the FacetWP button widget and select the Flyout button type. In Beaver Builder, the FacetWP button module with the same type serves the equivalent role. This is convenient when a page builder manages the markup and you do not want to add an HTML block just for one class. However, the widget itself does not create facets or fix the connection to the listing. After adding it, repeat the same selection-and-results-update test.

In the block editor and in a theme with custom markup, a regular button with facetwp-flyout-open remains the clearest starting point. A visual builder makes sense for spacing and placement, not for duplicating conditions. If the builder creates an automatic link with an empty address or #, replace it with a real button. That hash changes the URL and can interfere with FacetWP updates.

The Button, Breakpoint, and Desktop Facet Visibility

The most common design issue is not Flyout itself, but two uncoordinated styles. The panel opens correctly, but the same conditions from the desktop column remain above or below it. Visitors see two identical sets and cannot tell which one is primary. The solution is one source of conditions with two presentation modes: visible in a column on wide screens and available through a slide-out panel on narrow screens.

Below is a small example based on the official approach. It does not change data, interfere with FacetWP JavaScript, or make rollback difficult. Change the width values only in both rules at the same time if your theme needs a different threshold. The .catalog-filters selector should be added to the desktop facet container, not to every individual element. This keeps the behavior clear and does not break the content that Flyout reads from the markup.

/* The button is needed only at mobile widths */
@media (min-width: 780px) {
  .facetwp-flyout-open {
    display: none;
  }
}

/* Source facets stay in the HTML but do not take up space on mobile */
@media (max-width: 779px) {
  .catalog-filters {
    display: none;
  }
}

Place the CSS in a child theme, in the theme's designated custom-styles field, or in a safe CSS mechanism already accepted for your project. Do not edit parent-theme files or insert rules into FacetWP files. After making the change, first inspect the page source: the facet container must still exist. Then, at mobile width, confirm that it is visually hidden while the same conditions still appear in Flyout.

Why the Opening Element Should Be a Button

A button has natural action semantics: it does not promise navigation to another address, but opens an interface on the current page. For that reason, <button> is safer than a link when the only goal is to open the panel. The official documentation also allows a link with href="javascript:;", but you should not replace it with an empty href or #. In the mobile workflow, FacetWP uses URL parameters to represent selection state, and an extra hash can conflict with that behavior.

If the site needs localized button text, do not mix translation with styling. First make sure a simple English button works. Then, when the text is output from a PHP template, use the FacetWP internationalization method and translate the string. This is especially important for multilingual sites: the technical class stays unchanged while visitors receive a clear localized label. Do not translate the CSS class or change its letter case.

Facet Labels: What Visitors Will See in the Panel

Mobile Flyout adds its own h3 heading above each facet, based on the facet's FacetWP label. It is useful to account for this while configuring facets, not after the layout is complete: a name such as "price_range" or "pa_color" may make sense technically to an administrator, but the panel should display "Price" and "Color." Open the page in mobile mode and look at the first two or three lines in each group. If the heading does not make it clear what the selection will narrow without further explanation, fix the facet label itself instead of adding a long instruction next to it.

In a multilingual catalog, this adds another checkpoint. The button label and facet headings are separate strings: translating one does not guarantee that the other is translated. After switching languages, check not only the word "Filters," but also the condition names, User Selections, and reset action. The technical facet name used in settings remains stable; only the visible label changes. This allows a link with selected conditions and the mobile panel to use one configuration without giving visitors a mixed-language interface.

Sometimes a repeated label genuinely gets in the way, for example when a block is styled as a separate card with an already visible name above the control. For that narrow case, FacetWP lets you hide a specific row heading with a class such as .flyout-row.name-myfacetname h3. Before doing so, make sure a clear visible name for the condition remains nearby. Do not hide every heading with one rule just to create a shorter panel: checkboxes, ranges, and dropdowns serve different purposes, and without labels visitors can easily apply a condition to the wrong attribute.

The testable workflow here is simple. Take the "Category," "Price," and "Availability" facets, open Flyout in English and in the site's second language, then select one value at a time. At every step, the heading should remain associated with its control, the selected value should appear in active conditions, and the cards should respond to that exact attribute. If the listing works but a heading is missing or translated incorrectly, that is a separate label-and-styling task, not a reason to change the index or query.

Positioning the Panel on the Left or Right

By default, a panel that appears from the side feels familiar to most visitors. FacetWP documentation shows how to move Flyout to the right using CSS rules for body .facetwp-flyout and an initial translateX(100%) offset. Choose the side based on the interface, not personal preference: if the theme has a right-side quick-access block on mobile, the panel may conflict with it; if the catalog's established hierarchy already uses left-side slide-outs, keep the expected pattern.

Do not change the side before testing the basic workflow. First confirm opening, selecting, closing, and restoring state, then change the direction. After this adjustment, separately test the back gesture, closing through the available interface control, and the absence of horizontal page scrolling. If the outcome is worse, rollback is simple: remove the custom CSS rule without changing facet settings.

A breakpoint is an agreement between the theme and the filters, not a cosmetic number. The button and the desktop-container hiding rule must switch at the same point.

How to Define Panel Contents with a Flyout Template

Automatic contents are useful for an initial launch, but a catalog almost always develops additional requirements. For example, you may need to show active selections above the conditions, add a short hint below them, or avoid displaying an expensive search in the same context. For these cases, Mobile Flyout uses a template that is hidden on the page and has the facetwp-flyout-tpl class. Inside it, the {content} placeholder indicates where FacetWP will insert facets.

An important detail: the template is not a second set of source facets. It defines the contents and surrounding context that Flyout should display. The element is placed on the page but automatically hidden by the add-on styles. This preserves one data system, lets you control the order, and adds useful context without manually copying checkboxes.

<div class="facetwp-flyout-tpl">
  [facetwp selections="true"]
  <p>Choose conditions and review the results.</p>
  {content}
</div>

In this example, active selections appear above the facets. Visitors immediately see why the listing became smaller and can remove an unnecessary condition. Text before or after {content} can be replaced with a short instruction, an availability notice, or another suitable shortcode. Do not turn the panel into a promotional block: every extra paragraph pushes useful conditions farther down. For a long catalog, it is better to keep one calm line and the active selections.

Order: Strong Constraints First, Refinements Second

Consider a furniture catalog. Room type, category, and price range work well at the top of the panel because they quickly reduce the number of cards. Color, material, and availability belong below them. A filter with dozens of rare values or technical codes is better made searchable or kept behind a separate disclosure if the facet design allows it. Conditions that are almost never selected should not enter the panel merely because they exist in the admin area.

On a real-estate site, the priorities are different: transaction type, property type, neighborhood, and price range matter more than room count, floor area, and additional characteristics. In a recipe database, dish type, key ingredient, and preparation time should come first, followed by difficulty and dietary tags. These are not universal FacetWP rules, but editorial decisions. Flyout makes ordering especially visible because visitors read the panel from top to bottom rather than scanning a wide desktop column.

Active Selections and an Apply Button

User Selections is not included in Flyout automatically, so it must be added deliberately through the template. This is justified when several conditions are active on the page and visitors need to see the current set quickly. After every change, make sure the element reflects the selections and that removing one value updates the listing. If the active-conditions block is visible but its values do not match the cards, the cause is usually lower in the stack - an incorrect query or facet source, not the template.

If the project uses the Submit Button add-on, the documented option allows its button to be placed after {content}. This fits a workflow where visitors choose several conditions and then deliberately go to a results page or trigger one combined update. Do not add that button to a regular instant-update catalog just because the word "Apply" feels familiar: it changes user expectations. With standard behavior, selecting a facet already triggers an update, and a separate action may appear mandatory even though it does nothing new.

For an instant-update setup, it is more useful to explain the change with text near the listing or support it with a count. After selecting an option, visitors should see not only a changed checkbox, but also a new listing. If the panel closes automatically due to theme styling or visitors close it themselves, leave a clear state signal on the page: User Selections, a concise count, or an available reset button.

Two Different Meanings of an "Apply" Button

In this setup, "Apply" can mean two different things, and they should not be mixed. The first is to delay updating the currently open listing: visitors select several conditions, click the button, and only then does FWP.refresh() run. The second is to pass the selection to a separate results page through Submit Button. In the latter case, the template button receives a results-page address, such as data-href="/listings/", and visitors go there with the selected parameters after clicking. Choose one route before implementation, otherwise one page may end up with two buttons carrying the same label but producing different outcomes.

Delayed updating is reasonable for a heavy catalog where people normally set several attributes at once: neighborhood, room count, floor area, and budget, or category, size, color, and availability. In that case, four AJAX updates after every touch can distract users and make the interface feel unstable. However, enabling this mode affects the entire faceted page, not only the mobile panel. The official approach requires disabling automatic updates and adding an apply action to the desktop interface as well. You cannot keep instant filtering on desktop and quietly delay it only inside Flyout: visitors would receive different rules for the same set of facets.

Before publishing, run a repeatable test for the chosen model. For instant mode, open the panel, select price and color, wait for a response after each value, then remove color and verify that cards return. For delayed mode, select the same conditions and confirm that the listing does not change until the button is pressed, after which it changes once and active selections match the result. For redirection, start on the source page, select two values, click Submit, and verify three things: the correct results page opens, parameters remain in the URL, and the listing itself matches them. This distinguishes a workflow error from an ordinary facet problem.

In any of the three options, do not close Flyout through an arbitrary click handler before checking the result. Documentation provides open and close events, as well as options for automatically closing after a selection or after applying conditions, but these are finishing enhancements rather than the core feature. If the panel closes immediately after a touch and visitors cannot see whether results changed, restore the basic behavior. Then decide based on observation: after one quick selection, closing after an update can be acceptable; when comparing several conditions, it is usually better to keep the panel open until an explicit close or apply action.

Opening, Closing, and Long Condition Lists Without Losing Context

Once basic filtering works, Flyout has another responsibility: preserve the meaning of the action while visitors work through a long list. On a regular page, people can see some products beside the filters. In a sidebar panel, the result sits outside its boundaries, so the interface must clearly show what happened after a selection. For a small catalog, calm instant updates and visible active conditions can solve this. For a complex form, it is more important to choose a closing rule, disclosure order, and path back to results in advance than to add animations.

When It Makes Sense to Keep the Panel Open

Keep Flyout open when visitors usually combine several conditions or need to compare available options. This is common in searches for housing, cars, complex equipment, and B2B catalogs: users choose one criterion, see which values remain in the next one, and then adjust a previous choice. Forcing the panel to close after the first touch turns this path into a series of repeated openings without making the listing easier to understand. In this workflow, User Selections at the top of the template and a close button that returns visitors to already updated cards are especially useful.

Test this with more than checkboxes. Open the panel, change a price range, select a value in a dropdown facet, and reset it. After each action, the panel should retain its scroll position well enough for users to understand what they are editing. If the theme unexpectedly moves focus to the top of the page or resets Flyout scrolling during an AJAX update, do not compensate by closing the panel automatically. First disable the conflicting smooth-scroll or animation script and repeat the basic test. Closing does not fix lost state; it only hides the symptom.

Automatic Closing Only for a Clear, Short Action

Automatically closing the panel makes sense in a different workflow: the screen contains one obvious toggle, such as "In Stock," and visitors should see the catalog immediately after selecting it. FacetWP provides Flyout open and close events, and the documentation describes ways to close it after using a facet or after an explicit apply action. Before adding such code to a child theme or Code Snippets, write the rule in plain language: "the panel closes after selecting availability status" or "the panel closes only after clicking Apply." The phrase "close after filtering" is too vague: it can make selecting a price, several checkboxes, or sorting inconvenient.

After implementation, test the difference between an initial load and a repeat load. Open a catalog with no parameters, apply a short filter, and confirm that the panel closes only at the agreed moment. Then open a saved URL with conditions already selected. Flyout should not repeatedly open and close just because FacetWP restored state from the address. If you need to open the panel when a prepared selection first loads, use this documented technique only for that page or template and test the browser's "Back" button separately. For a normal store page, a calm closed initial state is usually clearer.

How to Shorten a Long Panel Without Inventing Duplicates

When there are genuinely many facets, the first solution should be ordering and excluding irrelevant conditions, not creating a second set of fields. Mobile Flyout already moves facets from the source markup. For a precise list, FacetWP provides a JavaScript filter where you can define facet names and their order, and the list should include only facets that actually exist on that page. This matters when multiple templates are used: a shared name list containing a missing facet can cause a console error and disrupt the panel. If catalog sections use different conditions, limit the configuration to the specific page instead of applying it site-wide without testing.

The next step is to make secondary groups expandable. The official example uses the existing h3 headings in Flyout rows: when clicked, a row receives the expanded class and its nested element becomes visible. This approach is suitable only after checking the input device and providing a clear visual state indicator. Do not turn the first two or three key filters into an accordion, or visitors will not see the main constraint without an extra click. A practical balance for a furniture catalog is to keep category, price, and availability open, then reveal color, material, and rare properties lower down when the assortment genuinely requires them.

The final check for this section consists of two paths. In the first, a new visitor opens the panel, immediately finds three main conditions, and understands within one screen what can be filtered. In the second, an experienced visitor expands an additional group, selects a value, closes the panel, and opens it again: the selected value and disclosure behavior should not turn the group into an unreadable list. If that test improves only appearance while making the path to the needed condition longer, return to a simple flat order. For FacetWP Flyout, the best interface is the one that confirms a selection through updated results, not the one that fits every technical capability into one sidebar.

Condition Order, Empty Facets, and State After Returning

Mobile Flyout becomes especially useful when the catalog does not overwhelm visitors with misleading options. FacetWP facets know about the current listing state and can display only relevant values. But that is not a reason to hide the meaning of the interface behind excessive automation. If a visitor selects a category and the "Material" condition temporarily has no values afterward, they should either see a clear absence of options or avoid encountering an empty area that takes up space. The worst state is a filter heading with no choices, which looks like an error.

The official Mobile Flyout documentation notes that empty facets already hidden before the panel opens retain that state when it opens and closes. Therefore, visibility settings should not be tested only in the source column. Open the page with no conditions, choose a limiting attribute that makes one secondary facet empty, open Flyout, and inspect the sequence. Then remove the attribute and reopen the panel. The state should recover without empty headings, duplicate blocks, or an unexpected scroll jump.

How to Order Conditions Without Making the Panel Longer Than the Product List

Evaluate each facet using two questions: how early does it help eliminate unsuitable cards, and how easily can visitors understand its meaning without help? Clear, strong constraints should go at the top: type, category, purpose, neighborhood, price range, availability. Refinements stay below: color, material, secondary characteristics. Place the reset action at the end and, if your workflow genuinely needs one, an additional apply button.

The order does not have to be identical on desktop and mobile. On a wide page, people can see the condition column and cards at the same time, so they can scan more freely. In Flyout, reading is more sequential: first the top of the panel, then the next screen. A template with {content} helps the panel follow its own useful order without breaking the familiar desktop block order. If you change the order, verify not only that the panel looks good, but also that selecting each facet still updates the same listing.

Why One Active Listing Matters More Than It Seems

A page often contains a main catalog, a "Related Products" block, a new-arrivals carousel, and footer cards. To visitors, these are simply several groups of content. For FacetWP, the boundary is critical: one listing should respond dynamically. Official materials allow static listings on the same page, but warn that only one listing can be enabled for FacetWP. If some cards change after filtering while others remain unchanged, it may look as though Flyout is broken even though the panel is correctly controlling only the intended listing.

Before launch, label page zones for yourself. "This block changes when filters are applied," "this carousel is always static," "this block is not part of the catalog." Then test the behavior on a small screen, where visitors see less context. If a static collection sits directly below the results, add visual separation or a short heading so visitors do not mistake it for a continuation of the filtered listing. This is an editorial adjustment, but it prevents many unnecessary support requests.

Browser Back Navigation and Preselected Conditions

The FacetWP URL stores selection parameters, making it useful as a testable record of state. Follow the workflow in order: open a page with no conditions, enable two filters, open a card, return with the browser, close and reopen Flyout. At every return point, active values should match the listing. Do not judge only the appearance of the button: more importantly, URL parameters, User Selections, and cards must all tell the same story.

Mobile Flyout documentation describes a separate option for automatically opening on initial load when the URL already contains selections. This may suit a link to a prepared collection if facets are hidden inside the panel itself. But do not make it the default setting for every catalog page. Visitors should first receive a calm listing and a clear button. Reserve automatic opening for a confirmed prefilled-link workflow and test it after the normal path, because it has a stronger effect on first impressions and browser back navigation.

If normal state works but empty or stale data appears specifically after returning, do not add a forced page reload. Check add-on updates, custom scripts, caching, and whether the source facets remain in the markup. Updated official Mobile Flyout notes specifically mention fixes for browser back navigation and the combination of Reset with preselection, so this symptom is best reported with an exact reproduction route rather than a vague statement such as "filters sometimes reset."

Catalog Workflow: From WooCommerce Cards to a Usable Mobile Listing

A practical example is easiest to follow with a WooCommerce catalog because its data, cards, and pricing are immediately visible. The goal is to let visitors narrow a product list by category, price, availability, and color on a phone without leaving a tall filter column above the products. Assume that the cards already have correct categories, a color attribute, and stock status, and that the main store page or another supported listing already works with FacetWP.

Preparing the Workflow

First choose four conditions, each answering a different shopper question. Category answers "what am I looking for," price range answers "what is my budget," availability answers "is the product ready to order," and color answers "which option do I need." In FacetWP, create a clear label for each facet and select the corresponding WooCommerce data source. If the catalog uses variable products and facets must account for variations, enable the appropriate variation support in FacetWP settings and then run a re-index. Otherwise, an attractive Flyout may show a color choice that does not lead to the expected parent product.

Before placing the panel, test these facets in the wide-screen version. Select a category, then a particular color, and then remove the color. At every step, both the number and set of cards should be explainable. Choose one card that should remain and one that must disappear. This manual verification is better than a superficial "the page updated" check because it shows that the data sources actually describe the products.

Placement and Action Sequence

1. Keep one desktop facet container on the page and wrap it with a styling class such as catalog-filters.
2. Add a facetwp-flyout-open button next to the store heading with the label "Product Filters."
3. At mobile width, hide only the desktop container visually while preserving it in the HTML.
4. Place a facetwp-flyout-tpl template on the page with [facetwp selections="true"], a short hint, and {content}.
5. Open the panel, select category, color, and availability in sequence, then remove one selection through the active conditions.

With this order, visitors receive a clear funnel: first they open conditions, then quickly choose meaningful attributes, see updated products, and can correct their selections. In practice, do not try to fill the panel with every store attribute. For example, size may be more important than material in an apparel catalog, but if shoppers choose a size on a variation card, a separate facet must first be tested against variation data. In a furniture catalog, dimensions, material, and color are usually more useful instead.

Testing with Real Data, Not One Product

Create a small set of control cases. The first product should match every selected condition. The second should match only category and color but be unavailable. The third should have a different color. The fourth should not belong to the category. Set all conditions in the mobile panel and confirm that only the first product remains. Then remove them in reverse order. If the second product does not return after removing availability, check the facet source and re-indexing. If cards return but the active selection remains on screen, inspect the User Selections markup.

This test checks both the meaning of the filters and Flyout itself. Visitors do not need to know that AJAX or an index operates underneath. What matters is that a selected condition appears in the results, removing a condition expands the list again, and refreshing the page does not turn state into a mystery. Once this chain is stable with test products, move it to the real catalog data.

What to Do with URLs and Links to Prepared Selections

FacetWP adds selected values to the URL query string. This is useful for repeat testing, browser navigation, and linking to a prefiltered collection. Before publishing, copy an address with two or three conditions, open it in a private window, and make sure Flyout, active selections, and cards are consistent. Do not promise visitors "pretty" permanent URLs if your structure relies on GET parameters: FacetWP documentation explicitly describes that state mechanism.

For a campaign or internal navigation, you can link to a verified prepared selection, but do not generate links manually by guessing. First create the conditions through the interface, then copy the resulting URL. After changing a facet name or its source, repeat the check. This protects against a silent error where the page opens but a parameter no longer matches the facet's actual technical name.

A Verification Route for the Catalog Editor

After the initial setup, do not hand over an abstract task such as "check the filters." Instead, provide a specific route that can be repeated without knowing the admin area. For example: at mobile width, open the product category, click "Product Filters," select "Chairs," a range up to the chosen budget, and one color, close the panel, open the first remaining card, and then return with the browser's Back button. Next, remove the color through active selections and confirm that the set expands. This route checks the button, facet order, card connection, URL, state preservation, and the ability to correct a selection without reloading the catalog.

To keep testing independent of random inventory changes, maintain a small control-data table outside the interface. Five rows are enough: an item matching all conditions; an item excluded by category; an item with an unsuitable color; an item outside the budget; and an unavailable item. Editors do not need to see technical custom-field values. They only need to know the expected card count after each combination. If the test differs from the table, first inspect one specific data source and the index state, then repeat the same route. Do not change labels, CSS, queries, and data at the same time, or you will lose the ability to identify which change fixed the issue.

Also test the no-results state. Choose a combination for which the control set has no cards, then assess the page from the visitor's perspective: the panel still contains clear conditions, active values can be removed, and an empty result does not look like stalled AJAX. Then remove one condition and verify that cards return without a reload or duplicate facets. This negative test is especially important for Flyout: visitors may not see the source column and must have a way to escape an overly narrow selection directly from the panel or through active selections.

If several editors maintain the catalog, save an expected mobile-state screenshot and the URL of the prepared selection alongside this route. This does not replace automated testing, but it is reliable protection against subtle regressions after product imports, theme updates, or template changes. When someone reports an issue, ask for the screen width, source URL, selected facet, and expected card. These four details are far more useful than "it does not work on a phone" and help distinguish a Mobile Flyout failure from a change in the catalog itself.

How to Verify the Setup and Catch Regressions

Verification does not end when the panel opens. FacetWP Flyout has several observable states that need separate confirmation: the button is available at the intended width, the panel contains the right conditions, every condition changes the listing, active values remain after closing, the URL represents the selection, and browser back navigation does not break the interface. Record these steps as a short acceptance workflow for an editor or tester.

It is useful to test in two independent contexts. The first is a guest private window with no old cookies, developer extensions, or authenticated cache. The second is a normal session with sequential navigation through the catalog. This catches two different categories of failures: a clean page state and accumulated back-and-forward navigation. If the site has several languages, repeat the test in each language with its own facet labels.

Minimum Acceptance Matrix

The expected outcome is not merely a panel that opens, but a repeatable connection between "selection - updated listing - understandable state." Once that is confirmed, you can work on design details such as panel width, spacing, button label, and active-selection placement.

Troubleshooting FacetWP Flyout: Symptoms, Checks, and Safe Fixes

Do not try to fix every issue with CSS rules. Flyout has its own interface layer, but most failures relate to the FacetWP listing, data, or page markup. Troubleshooting becomes faster when you move from an observable symptom to one testable assumption, then repeat a short control workflow after every change.

The Panel Opens but Contains No Facets

Symptom: the button opens a sidebar area, but it is empty or contains only a decorative heading. Likely cause: facets are missing from the page HTML, exist in another template, or the current page does not have a valid FacetWP listing. Check: temporarily show the desktop container on that same page and confirm that it contains real facets rather than only a place where the builder is expected to add them later.

Fix: return the source facets to the page markup, verify that one working filterable listing is nearby, and hide the container on mobile only with CSS. If you recently moved a template, compare the working page and the problematic page for the presence of the listing and shortcodes. When to roll back: if the empty panel appeared after conditional rendering of a block in a builder, disable that condition until the main configuration is complete.

A Selection Changes the Checkbox but Cards Stay the Same

Symptom: the facet visually accepts a value, the URL may change, but the listing does not narrow or shows unexpected cards. Likely cause: FacetWP is using the wrong query, did not identify the listing container, or the facet points to an unsuitable data source. Check: enable Debug Mode in FacetWP settings and open the browser console on the problematic page. Official documentation recommends inspecting FWP.settings.debug and comparing the query in use with the expected post type, sorting, and results count.

Fix: first enable Advanced query detection if the setting is disabled. Then verify that the page has one facetwp-template container for the dynamic listing. For a custom WP_Query, do not guess at a solution: follow the official instructions for the correct query and add support only in the template or child theme. When to roll back: remove an experimental custom query filter if unrelated cards began responding to filters after it was added.

Duplicate Conditions Appear in Flyout

Symptom: the same condition appears two or three times, sometimes along with another copy after scrolling. Likely cause: the page contains several instances of the facet, or an Elementor Pro facet widget uses Sticky mode. Mobile Flyout documentation specifically warns that sticky settings on widgets containing facets can cause duplicates.

Check: disable Sticky for every widget containing a facet and temporarily leave one instance of every condition on the page. Open Flyout in a new window. Fix: keep one source for each facet or use a Flyout template to limit panel contents. When to roll back: if moving the panel into a separate copied block increases duplication, return to one source markup and configure ordering through facetwp-flyout-tpl.

The Mobile Button Adds # to the Address or Filters Behave Strangely After a Click

Symptom: after clicking, the address ends with #, the browser's Back button behaves unpredictably, or facet updates do not run correctly. Likely cause: a link with an empty href or href="#" was used instead of a button; some builders add the hash automatically. Check: inspect the element's actual markup, not only its settings in the visual editor.

Fix: replace the link with <button class="facetwp-flyout-open" type="button">. If a link is essential, use the documented option with href="javascript:;". After replacing it, test panel opening, facet selection, and the browser's "Back" button. When to roll back: do not add a third-party click handler if a simple button already works, because it may intercept the event again.

Both the Desktop Column and Flyout Are Visible on Mobile

Symptom: visitors see a long filter set in the document and a separate button that opens the same set. Likely cause: CSS breakpoints differ, the selector targets an individual facet rather than the shared container, or a theme rule overrides display. Check: use the inspector to view the container's computed styles at widths one pixel below and above the threshold.

Fix: use one class for the desktop facet container and one coordinated pair of min-width/max-width rules. Fix visibility first, then confirm that facets are still present in the DOM and available to the panel. When to roll back: if you hid every .facetwp-facet without accounting for the theme structure and the panel became empty, return to hiding the outer container.

Facets Disappeared After an Import, Data Update, or Source Change

Symptom: expected options are missing from the panel, empty conditions appear, or a selection returns zero cards despite the data. Likely cause: the index was built before a bulk change, the facet source changed, or post values are populated differently than the configuration expects. Check: open one specific card in the admin area, compare its field with the facet Data source, and run a full re-index.

Fix: correct the data or source, re-index, and repeat the control workflow with one known matching card and one known nonmatching card. When to roll back: if the new source produces unpredictable technical values, restore the previous saved facet configuration through the standard FacetWP import/export feature rather than editing database tables manually.

Filtering on Mobile Is Noticeably Slower Than the Initial Load

Symptom: the initial page feels fast, but a response takes a long time after conditions are selected. Likely cause: the FacetWP AJAX request goes through the full WordPress stack and reveals the actual speed of the listing: a heavy card template, many requests per product, server load, too many facets, or unoptimized data. Check: temporarily disable caching to measure the real response, inspect AJAX request time, and reduce the number of cards per page and heavy template blocks one at a time.

Fix: optimize the listing and server-side workload before enabling caching. For large catalogs, limit unnecessary post types, variations, and facets while following FacetWP performance documentation. When to roll back: if an aggressive optimization removes a needed card or option, revert the latest change and measure one factor at a time instead of disabling half the catalog at once.

When FacetWP Flyout Is a Good Choice

FacetWP Flyout is useful when the main faceted listing has already been tested and a mobile visitor needs to move quickly from cards to conditions and back. Its strength is not the effect of a slide-out panel, but preserving one data, URL, and AJAX workflow for two screen modes. Start with a working listing, add an honest button, align the breakpoint, build the template deliberately, and test several real combinations.

When the control chain "open - select - see results - change selection - return through the URL" works with real data, you can take the next step and download FacetWP Flyout for your project. Do not move an untested set of styles into production: first save the facet configuration, repeat acceptance testing at mobile width, and only then adapt the panel to the site's design.