Plugin Documentation

XC Product Filter Pro

Advanced faceted product filtering for WooCommerce β€” real-time AJAX results, SEO-friendly clean URLs, a full SEO Rules engine, and a CSS inherit-theme system that adapts to any storefront design.

⚑ AJAX Filtering πŸ” SEO Rules Engine 🎨 CSS Inherit Mode βœ… HPOS Compatible WordPress 6.0+ WooCommerce 7.0+ PHP 8.0+
πŸ“‹

Requirements

WordPress
6.0 or higher
Tested up to 6.8
WooCommerce
7.0 or higher
Tested up to 9.6
PHP
8.0 or higher
8.1 / 8.2 recommended
Permalinks
Non-plain
Required for Clean URLs
WP-Cron
Enabled
License & cache tasks
MySQL / MariaDB
WP standard
No extra extensions
βœ…

WooCommerce HPOS (High-Performance Order Storage) is fully supported and declared compatible. The plugin works with both classic and HPOS order storage modes without any additional configuration.

Optional Integrations

  • Advanced Custom Fields (ACF) β€” enables automatic field-name discovery when creating custom meta filters.
  • Yoast SEO β€” the SEO Rules engine hooks into Yoast's title, description, canonical, and robots filters.
  • Rank Math β€” same coverage as Yoast, via Rank Math's equivalent hooks.
  • Page caching plugins (WP Rocket, LiteSpeed Cache, W3 Total Cache, etc.) β€” compatible when Lazy Load Filters is enabled in Performance settings.
πŸ“¦

Installation

Method 1 β€” WordPress Admin Upload (recommended)

  1. 1
    Download the plugin zip

    Obtain xc-product-filter-pro-x.x.x.zip from your XaniaCode account dashboard or purchase confirmation email.

  2. 2
    Open the plugin uploader

    In your WordPress admin go to Plugins β†’ Add New β†’ Upload Plugin.

  3. 3
    Select and install

    Click Choose File, select the zip, then click Install Now.

  4. 4
    Activate

    After installation, click Activate Plugin. The plugin initialises immediately.

Method 2 β€” Manual FTP / SFTP

  1. 1
    Extract the zip

    Unzip the file on your computer to get a folder named xc-product-filter-pro.

  2. 2
    Upload via FTP

    Upload the entire folder to /wp-content/plugins/ on your server.

  3. 3
    Activate in WordPress

    Go to Plugins β†’ Installed Plugins, find XC Product Filter Pro, and click Activate.

βœ…

Upon first activation the plugin registers its post types, schedules a rewrite flush, and automatically creates a starter filter set containing Categories, Price, and any existing WooCommerce product attribute taxonomies. You can edit or delete this set at any time.

⚠️

WooCommerce must be installed and active before activating this plugin. If WooCommerce is absent an error notice appears and the plugin will not initialise.

What Happens on Activation

  • Custom post types xcfp_filter_set and xcfp_seo_rule are registered.
  • WordPress rewrite rules are scheduled for a flush on the next page load.
  • A welcome notice flag is set β€” visible to admins on first visit.
  • A starter filter set is auto-created if none already exist.

Uninstalling

Deactivate the plugin then click Delete in the Plugins list. The uninstall.php routine runs automatically and removes all plugin data from the database β€” filter sets, SEO rules, settings, and transient cache entries.

πŸ”‘

License & Activation

XC Product Filter Pro uses the XaniaCode License Manager for licence validation and automatic plugin updates. Your licence key is issued at purchase and linked to your XaniaCode account.

Entering Your Licence Key

  1. 1
    Open the Licence page

    In the WordPress admin sidebar navigate to XC Filters β†’ Licence.

  2. 2
    Paste your key

    Copy the key from your purchase email or XaniaCode account and paste it into the licence key field.

  3. 3
    Activate

    Click Activate. The system contacts the XaniaCode server to verify the key and a success or error notice is displayed inline.

ℹ️

The plugin supports a trial mode β€” features are not hard-locked on first install. Entering a valid licence key enables automatic updates and confirms your licence status with the XaniaCode server.

Automatic Updates

Once a valid key is active, new plugin versions appear in Dashboard β†’ Updates exactly like any WordPress.org plugin. Click Update β€” no manual file replacement is needed.

πŸ—‚οΈ

Admin Menu

After activation, an XC Filters top-level menu entry appears in the WordPress admin sidebar (position 56, between WooCommerce and Appearance). It contains four sub-pages:

β–Ό XC Filters
πŸ—ƒοΈ Filter Sets
🏷️ SEO Rules
βš™οΈ Settings
πŸ”‘ Licence
Menu PageDescription
Filter SetsCreate, edit, duplicate, delete, import, and export filter sets. This is the primary plugin workspace.
SEO RulesDefine custom H1 titles, meta descriptions, robots directives, and SEO text blocks per filter combination.
SettingsGlobal plugin settings in five tabs: General, Display, SEO, Performance, and CSS Customizer.
LicenceEnter and manage your XaniaCode licence key. Required for automatic updates.
ℹ️

All admin pages require the manage_woocommerce capability, held by WordPress Administrators and WooCommerce Shop Managers by default.

βš™οΈ

Settings β€” General

Navigate to XC Filters β†’ Settings. The page is divided into five independent tabs β€” each tab saves only its own fields, leaving the others unchanged.

AJAX Filtering
Enabled

Enables real-time filtering without a full page reload. When a visitor interacts with a filter the product grid updates instantly via AJAX. Disable only if you experience JavaScript conflicts with your theme or other plugins.

Show Count
Enabled

Displays the number of matching products next to each filter option β€” e.g. Red (12). Counts reflect the active filter context, not the full catalogue.

Hide Empty
Enabled

Automatically hides filter options with zero matching products given the current active filters, keeping the panel free of dead-end choices.

Submit Mode
Instant

Instant β€” filters apply on every click or change, triggering an AJAX call immediately.
Button β€” an Apply Filters button must be clicked before results update. Recommended for stores with many filter groups to batch changes and reduce server load.

Scroll to Top
Enabled

After each AJAX filter update the page scrolls back to the top of the product grid so visitors immediately see the updated results.

πŸ–ΌοΈ

Settings β€” Display

Auto Display on Shop
Enabled

Automatically injects the matching filter set above the product grid on all WooCommerce Shop and archive pages β€” no shortcode or widget required. Disable to control placement manually.

CSS Mode
Inherit Theme

Inherit Theme (recommended) β€” filters adopt your theme's form styles with no extra CSS.
Light Mode β€” loads the plugin's built-in light stylesheet (light-mode.css).
Dark Mode β€” loads the plugin's built-in dark stylesheet (dark-mode.css).

Mobile Drawer
Enabled

On mobile viewports the filter panel is hidden and replaced by a Filter button. Tapping it opens a fullscreen slide-in drawer. Uses real DOM synchronisation β€” not a clone β€” so state is always consistent across viewport sizes.

Chips Bar
Enabled

Shows active filter values as dismissible chip tags above the product grid. Each chip has a human-readable label and a Γ— remove button. A Clear All chip appears when two or more values are active.

Pagination
Classic

Classic β€” standard numbered page links.
Load More β€” a button that appends the next page below existing products.
Infinite Scroll β€” products load automatically as the user scrolls down.

Manual Placement Shortcodes

When Auto Display is disabled, use these shortcodes to place filter elements anywhere in your theme or page builder:

[xc_filters]

Full filter panel. Auto-detects the matching filter set for the current archive page.

[xc_filters set_id="123"]

Renders a specific filter set by its numeric ID.

[xc_chips]

Active filter chips bar only. Outputs nothing when no filters are active.

[xc_sorting]

WooCommerce product sorting dropdown.

πŸ”

Settings β€” SEO

Clean URLs
Enabled

Converts query-string filter parameters into clean, readable permalink segments:

Before
/shop/?filter_color=red&filter_brand=nike
After
/shop/color-red/brand-nike/

Requires non-plain WordPress permalinks. Automatically detects rewrite bases for product_cat, product_tag, and all attribute archives.

URL Separator
–

Character placed between the filter URL prefix and its value. Allowed values: - (hyphen) or _ (underscore). The dot is excluded to avoid conflicts with file-extension routing on some server configurations.

XML Sitemap
Disabled

Auto-generates an XML sitemap for all filter pages marked as SEO indexable. Each entry includes a real lastmod date derived from the most recently modified product in that filtered result. Submit this sitemap URL to Google Search Console alongside your main sitemap.

ℹ️

Saving the SEO tab automatically schedules a WordPress rewrite flush β€” Clean URL rules take effect on the very next page load without any manual action.

⚑

Settings β€” Performance

Transient Cache
Enabled

Caches filter term counts using WordPress transients, significantly reducing database queries on high-traffic stores. Automatically invalidated whenever a product is saved or deleted, or when taxonomy terms change.

Cache TTL
3600 s

How long (in seconds) cached counts are retained before recalculation. Range: 60–86,400 s. For stores with frequent product updates reduce this to 300–600 s.

Lazy Load Filters
Disabled

When enabled, the filter panel HTML is fetched via a separate AJAX call after the main page loads. This lets full-page caching plugins (WP Rocket, LiteSpeed Cache, W3 Total Cache, etc.) cache the product page while still delivering accurate, fresh filter state to each visitor. Recommended when using any full-page cache plugin.

βœ…

The AJAX filtering endpoint is always excluded from page cache regardless of the Lazy Load setting. Enable Lazy Load only if you also need the initial filter panel HTML served fresh per visitor.

🎨

Settings β€” CSS Customizer

Fine-tune the visual appearance of filter panels without writing code, or use the Custom CSS textarea for full control.

Accent Color

Primary highlight color applied to checked states, active labels, range slider handles, and interactive focus rings. Default: WordPress blue #2271b1. Replace with your brand color.

Text Color

Overrides the default text color inside the filter panel. Leave empty to inherit from the active CSS Mode.

Background Color

Overrides the panel background color. Leave empty to inherit.

Custom CSS

A free-form CSS editor. Styles entered here are output in a <style> block after all plugin stylesheets, so your rules always take precedence.

🎭

Inherit Theme

No plugin colors applied. Filters adopt your theme's native form styles. Best for tightly integrated designs.

β˜€οΈ

Light Mode

Loads light-mode.css β€” clean white and light-grey design with visible borders. Use when theme styles conflict.

πŸŒ™

Dark Mode

Loads dark-mode.css β€” dark background with light text. Suitable for dark-themed storefronts.

πŸ—ƒοΈ

Filter Sets

A Filter Set is the core building block of the plugin β€” a named, reusable collection of filter rules that is displayed on a specific location of your WooCommerce store. You can create as many sets as needed: one general set for the shop page, a tailored set for the "Electronics" category, another for "Clothing", and so on.

Key Properties of a Filter Set

  • Title β€” admin-only internal label (e.g. "Shop Filters", "Electronics Category").
  • Location β€” where the set appears: Shop Page, All WooCommerce Archives, Product Categories, Product Tags, or Attribute Archives.
  • Location Terms β€” optionally restrict the set to specific taxonomy terms. Leave empty to match all terms of that location type.
  • Priority β€” when multiple sets match the same page, the one with the lowest number wins (e.g. priority 5 beats priority 10).
  • Filters β€” one or more individual filter rows, each with its own source type, view type, and display options.

Available Actions on the Filter Sets List Page

ActionDescription
Add NewOpens the filter set editor to create a new set from scratch.
EditOpens the editor for an existing set.
DuplicateCreates an identical copy of a filter set. Useful for creating similar sets for different categories without starting from scratch.
DeletePermanently removes the filter set (nonce-protected).
ExportDownloads all filter sets as a single .json file.
ImportUploads and imports a previously exported .json file.
βž•

Creating a Filter Set

  1. 1
    Go to XC Filters β†’ Filter Sets and click Add New

    The filter set editor opens with an empty form.

  2. 2
    Enter a title

    Provide an internal admin name such as "Shop Filters" or "Clothing β€” Size & Color". Visitors never see this.

  3. 3
    Choose a location and optional terms

    Select where this set should appear. For category-, tag-, or attribute-based locations a multi-select appears allowing you to restrict to specific terms β€” leave it empty to match all terms of that type.

  4. 4
    Set a priority

    Default is 10. Assign lower numbers to more specific sets so they take precedence over general ones when multiple sets match the same page.

  5. 5
    Add and configure individual filters

    Click + Add Filter to add filter rows. Configure each row's source type, view type, label, URL prefix, and additional options. Grab the ☰ handle to drag rows into the desired display order.

  6. 6
    Save and copy the shortcode

    Click Save Filter Set. After saving, the editor displays a shortcode for this specific set β€” click it to copy it to the clipboard automatically.

ℹ️

The shortcode displayed after saving β€” e.g. [xc_filters set_id="42"] β€” can be pasted into any page, post, or widget to render this specific filter set regardless of the Auto Display setting.

πŸ“Š

Filter Source Types

The Source Type determines what product data a filter reads from the database.

Taxonomy Custom Field (Meta) Price Rating Product Status Author Date Search
Source TypeData SourceTypical Use Case
TaxonomyAny registered WordPress taxonomy β€” product_cat, product_tag, pa_color, pa_size, and any custom attribute taxonomies.Filter by product category, tag, or WooCommerce attribute.
Custom Field (Meta)Any product post meta key, including ACF fields. Enter the field name directly (e.g. brand_name, _custom_weight).Filter by text, numeric, or select fields attached to products.
PriceWooCommerce product price (_price). Reads WooCommerce decimal precision automatically.Price range slider or min/max numeric inputs.
RatingWooCommerce product average star rating.Filter products by minimum rating (e.g. "4 stars and above").
Product StatusWooCommerce stock status β€” in stock, out of stock, on backorder.Let shoppers filter by product availability.
AuthorThe WordPress user who created the product post.Multi-vendor setups or stores organised by product author.
DateProduct publish date. Renders a From / To date-range picker on the frontend.Filter new arrivals or seasonal collections by publication date.
SearchKeyword text search against product titles and content within the current archive.Add a live search box to the filter panel for keyword filtering.
πŸ‘οΈ

Filter View Types

The View Type controls the visual control rendered on the frontend for each filter.

Checkboxes Radio Buttons Dropdown Labels / Buttons Color Swatches Image Swatches Range Slider Range Input (min/max) Rating Stars Text Search
View TypeBest Used WithNotes
CheckboxesTaxonomy, Meta, Status, RatingMost versatile view. Multiple terms can be selected simultaneously. Supports OR / AND logic.
Radio ButtonsTaxonomy, Meta, StatusEnforces single selection. Re-clicking the selected option deselects it.
DropdownTaxonomy with many terms, MetaSaves vertical space for long option lists. Collapses into a select menu.
Labels / ButtonsTaxonomy (size, brand), MetaClickable pill buttons β€” visually prominent; ideal for size or fit options.
Color SwatchesTaxonomy (color attributes)Circular color patches per term. Color values read from _xcfp_color term meta, set per term in the Taxonomy admin.
Image SwatchesTaxonomy (pattern, material)Small thumbnail images per term. Image URLs read from _xcfp_image term meta.
Range SliderPrice, Meta (numeric)Dual-handle drag slider for a min–max range. Respects WooCommerce price decimal settings.
Range Input (min/max)Price, Meta (numeric)Two text inputs for entering exact minimum and maximum values.
Rating StarsRating source type onlyClickable star icons (1–5) for filtering by minimum product rating.
Text SearchSearch source type onlyLive search text input. Results update with each keystroke within the current archive.
πŸ”§

Per-Filter Options

Each filter row in a filter set exposes the following configuration fields in the editor.

FieldDescription
Source TypeThe type of product data this filter reads. Changing this field shows or hides the Taxonomy selector and Meta Key input accordingly.
Taxonomy / Meta KeyWhen source is Taxonomy, select from a dropdown of all available product taxonomies. When source is Custom Field, enter the meta key name (e.g. _custom_weight).
LabelHeading shown above this filter group on the frontend (e.g. "Color", "Price Range"). If left empty, the label is auto-derived from the taxonomy or meta key name.
View TypeThe visual control rendered for this filter. See View Types above.
URL PrefixThe slug segment used in Clean URLs for this filter. A prefix of color produces /color-red/ in the URL. Must be unique within the filter set.
LogicOR β€” products matching any selected term are shown (union / inclusive). AND β€” products must match all selected terms (intersection / exclusive). Applies to Taxonomy and Meta source types.
Order BySort order for filter terms: Name (alphabetical), Count (highest first), Menu Order (WP term order), or Custom (reads the order term meta value).
TooltipOptional helper text displayed next to the filter label. Useful for explaining filter behavior to shoppers.
Collapsed by defaultRenders the filter group collapsed on page load. Visitors can expand it by clicking the header. Reduces visual clutter on panels with many filters.
Hide empty termsPer-filter override β€” hides terms with zero matching products for this specific filter regardless of the global setting.
Show countPer-filter override β€” controls whether product counts are shown next to options for this specific filter.
SEO indexableMarks this filter as eligible for SEO indexing. Indexable filters produce Clean URLs that search engines can crawl and are included in the XML sitemap. Non-indexable filters remain functional but are excluded from the sitemap.
πŸ“€

Import / Export

Filter set configurations can be exported as JSON and re-imported on any other WordPress installation running the plugin β€” ideal for staging-to-production deployments or sharing configurations across sites.

Exporting

  1. 1
    Go to XC Filters β†’ Filter Sets

    Click the Export action link above the table.

  2. 2
    Download the JSON file

    A file named xcfp-filter-sets-export.json is downloaded containing all published filter sets with their full configurations.

Importing

  1. 1
    Click Import on the Filter Sets page

    A file upload form appears.

  2. 2
    Upload the JSON and submit

    Select the exported .json file and click Import.

  3. 3
    Review and adjust

    Imported sets appear in the list immediately. Verify that taxonomy slugs (attribute names, etc.) match the target site's configuration β€” these may differ between WordPress installations.

πŸ€–

Auto Display

When Auto Display on Shop is enabled (the default), the plugin injects the matching filter set above the WooCommerce product grid on every archive page automatically.

How Matching Works

  • The set's location type must match the current archive type.
  • If the set specifies location terms, the current archive's term must be in that list. Empty term list means "all terms of this location type".
  • Among all qualifying sets, the one with the lowest priority number is rendered.

When no filter set matches the current page and the visitor is a WooCommerce manager, an admin diagnostic notice appears instead of filters β€” useful during setup to identify missing configurations.

⚠️

When Auto Display is disabled you must place [xc_filters] shortcodes or the XC Product Filters widget manually on every page or layout where you want filters to appear.

πŸ“

Shortcodes

All three shortcodes work in any WordPress context: classic and block editor pages/posts, Elementor text widgets, Divi modules, and any widget area that supports shortcodes. Plugin CSS and JavaScript are enqueued automatically when any shortcode is rendered on the page.

[xc_filters]

Renders the complete filter panel. On WooCommerce archive pages the plugin auto-detects the best matching set. When used outside an archive specify a set_id.

AttributeDefaultDescription
set_idautoForce a specific filter set by numeric ID. Omit to use auto-detection.
locationemptyOptional location hint for matching on non-standard pages.
[xc_filters]
[xc_filters set_id="42"]

[xc_chips]

Renders only the active filter chips bar. Outputs nothing when no filters are active. Use this to place the chips bar in a different position from the filter panel β€” for example, above the product count line.

[xc_chips]

[xc_sorting]

Renders the WooCommerce product sorting dropdown. Useful when Auto Display is disabled but you still want the sorting control in a specific template location.

[xc_sorting]
🧩

Widgets

Three widgets are registered and available in Appearance β†’ Widgets (classic widget screen) and in the Block Editor's Widget block for block-based themes.

Widget NameEquivalent ShortcodeDescription
XC Product Filters[xc_filters]Renders the complete filter panel in any sidebar or widget area. Plugin assets are enqueued automatically when the widget is active.
XC Active Filter Chips[xc_chips]Renders the chips bar. Outputs nothing when no filters are active.
XC Product Sorting[xc_sorting]Renders the WooCommerce sorting dropdown. Useful when Auto Display is disabled.
🏷️

SEO Rules Engine

The SEO Rules Engine lets you define custom metadata for specific filter combinations β€” turning filtered product pages into properly indexed landing pages with unique H1, title, description, and robots directives instead of sharing generic archive metadata.

How Rules Are Matched

When a visitor loads a filtered page the engine reads the active filter values and evaluates all published rules. The first rule whose URL pattern matches the active state is applied. If no rule matches, default WordPress or SEO plugin metadata is used unchanged.

SEO Rule Fields

URL Pattern

Defines which filter combination this rule targets. Written as filter key-value pairs, e.g. color=red or color=red&brand=nike. Evaluated against the active filter state of the current page.

H1 Title

Replaces the archive's main H1 heading visible to visitors. Integrated with WooCommerce page titles, Yoast SEO, and Rank Math heading filters.

Meta Title

Overrides the HTML <title> tag shown in browser tabs and search result titles. Passed to Yoast SEO and Rank Math title filters when active.

Meta Description

Overrides the meta description tag used in search snippets. Integrated with Yoast SEO and Rank Math description filters.

Robots

Sets the robots directive for this page: index (default), noindex, or noindex,nofollow. Integrated with the WordPress wp_robots filter and Yoast / Rank Math canonical filters.

SEO Text

Optional rich text block rendered below the product grid on matched pages. Acts as keyword-rich on-page content for the specific filter combination. Supports basic HTML formatting.

SEO Plugin Integrations

  • Yoast SEO β€” H1, meta title, meta description, canonical, and robots filters are all hooked.
  • Rank Math β€” same coverage as Yoast via Rank Math's equivalent filter hooks.
  • Default WordPress β€” wp_title, document_title_parts, wp_head, and wp_robots are hooked when no SEO plugin is active.

Navigate to XC Filters β†’ SEO Rules and click Add New Rule to create a rule. The rules list shows all published rules with their URL patterns and H1 values. The first matching rule wins β€” order matters.

πŸ”—

Clean URLs

Clean URLs convert ugly query-string filter parameters into readable, permalink-style URL segments that are user-friendly, shareable, and crawlable by search engines.

Query-string URL (before)

https://example.com/shop/?filter_color=red&filter_brand=nike&filter_size=xl

Clean URL (after)

https://example.com/shop/color-red/brand-nike/size-xl/

Each active filter contributes one {url_prefix}{separator}{value} segment appended to the base archive URL. The separator (default -) is configurable in Settings β†’ SEO. The plugin automatically detects rewrite bases for product_cat, product_tag, and all attribute archives β€” custom bases set in WooCommerce Permalink settings are supported without any extra configuration.

⚠️

Clean URLs require WordPress permalinks to be set to something other than Plain. Enable a permalink structure at Settings β†’ Permalinks before turning on this feature. A rewrite flush is triggered automatically on the next page load after enabling.

πŸ—ΊοΈ

XML Sitemap

When the XML Sitemap setting is enabled the plugin auto-generates a dedicated sitemap containing all indexable filter pages.

  • The sitemap is registered within WordPress's built-in sitemap system and accessible at a standard sitemap URL.
  • Each entry includes a real lastmod date calculated from the most recently modified product in that filtered result set.
  • Only filter combinations where at least one filter has SEO indexable checked are included.
  • Combinations with zero matching products are automatically excluded.
  • Submit the sitemap URL to Google Search Console alongside your main sitemap for fastest indexing of filter landing pages.
πŸ“±

Mobile Drawer

On mobile viewports the filter panel is hidden by default and replaced by a prominent Filter button. Tapping it opens a fullscreen slide-in drawer containing the complete filter panel.

  • Real DOM synchronisation β€” the same filter panel DOM node is moved into the drawer rather than cloned. Filter selections, slider positions, and state are always perfectly consistent between desktop and mobile views.
  • The Filter button shows a count badge indicating how many filters are currently active.
  • Full keyboard accessibility: Tab, Enter, Space, and Escape are handled correctly. The drawer is marked with ARIA dialog attributes (role="dialog", aria-modal="true") for screen reader support.

Enable or disable the Mobile Drawer at Settings β†’ Display β†’ Mobile Drawer. When disabled the filter panel renders inline on all viewport sizes.

🏷️

Chips Bar

The Chips Bar is a visual summary of all currently active filters displayed as a row of dismissible chip tags above the product grid.

  • Each chip shows the filter label and human-readable value β€” e.g. Color: Red, Size: XL, Price: $20 – $80.
  • Clicking Γ— removes that specific filter value and triggers an immediate AJAX update.
  • A Clear All chip appears when two or more filter values are active for one-click reset.
  • Range filter chips (price, date) display the selected range in a readable format rather than raw URL values.
  • Can be placed separately from the filter panel using the [xc_chips] shortcode or the corresponding widget.
πŸ”Œ

ACF Integration

If Advanced Custom Fields (ACF) is installed and active the plugin automatically discovers ACF field groups attached to the product post type and surfaces their field names in the Custom Field (Meta) source type selector.

Supported ACF Field Types

Text Number Select Checkbox Radio Date Picker

Setup

  1. 1
    Create your ACF field group

    In ACF β†’ Field Groups, create a group with location rule Post Type β†’ Product and add your fields.

  2. 2
    Add a Custom Field filter

    In the filter set editor click + Add Filter and select Custom Field (Meta) as the source type.

  3. 3
    Enter the field name

    Type the ACF field name (e.g. material) into the Meta Key input. When ACF is active, field names from product-attached groups are auto-suggested.

  4. 4
    Choose a view type and save

    Select the appropriate view type (Checkboxes, Dropdown, Labels, etc.) and click Save Filter Set.

πŸ—„οΈ

Cache & Rate Limiting

Transient Cache

Filter term counts are cached using WordPress transients to avoid expensive database queries on every page load. Cache entries are keyed by filter set ID, active filter state, and the current archive context.

  • Cache is automatically invalidated when a product is saved, updated, or deleted, and when taxonomy terms are created or modified.
  • Cache TTL is configurable from 60 s to 86,400 s (24 h), defaulting to 3,600 s (1 h).

AJAX Rate Limiting

The plugin's AJAX endpoint includes a built-in rate limiter to protect against excessive automated requests. The rate limit key is derived from a combination of the visitor's logged-in user ID and a hashed IP address. The IP detection correctly handles:

  • Cloudflare origin IPs via the CF-Connecting-IP header.
  • Reverse proxy setups via X-Real-IP.
  • Load balancers via the first IP in the X-Forwarded-For chain.
  • All IP values are validated with FILTER_VALIDATE_IP to prevent header-injection abuse.

Page Caching Plugin Compatibility

  • The AJAX endpoint is always excluded from page-level caching automatically.
  • Enable Lazy Load Filters in Settings β†’ Performance for full compatibility with WP Rocket, LiteSpeed Cache, W3 Total Cache, and similar tools.
❓

Frequently Asked Questions

Does the plugin work with my theme?

Yes. The default Inherit Theme CSS mode causes filters to adopt your theme's existing checkbox, input, label, and font styles automatically. If conflicts arise, switch to Light Mode or Dark Mode in Settings β†’ Display, or use the Custom CSS editor for targeted adjustments.

Can I filter by ACF custom fields?

Yes. Add a filter row, select Custom Field (Meta) as the source type, and enter your ACF field name (e.g. material). When ACF is installed and active, field names from product-attached groups are auto-suggested in the Meta Key input.

Do clean URLs work with caching plugins?

Yes. The AJAX endpoint is always excluded from page cache. Enable Lazy Load Filters in Settings β†’ Performance so that the initial filter panel HTML is also served fresh per visitor. This is compatible with WP Rocket, LiteSpeed Cache, W3 Total Cache, and similar tools.

How does the price slider handle decimal prices?

The range slider reads the Number of decimals setting from WooCommerce β†’ Settings β†’ General and adjusts the step value accordingly. Stores using decimal pricing (e.g. $9.99) will see appropriate precision on both the slider and the range input fields.

Can I use different filters on different category pages?

Yes. Create one filter set per category, set its location to Product Categories, and select the specific category in the Location Terms multi-select. Assign a lower priority number than your general shop set so the category-specific set takes precedence. AJAX filtering scopes results to the current archive automatically.

What happens when multiple filter sets match the same page?

The set with the lowest priority number is selected. Assign lower numbers to more specific sets (e.g. category-specific at priority 5) and higher numbers to general fallback sets (e.g. shop-wide at priority 10).

Can I place filters horizontally above the product grid?

Yes. Disable Auto Display in Settings β†’ Display, then place the [xc_filters] shortcode above the product loop in your page builder or template. Target .xcfp-filters-sidebar with custom CSS (e.g. display: flex; flex-wrap: wrap;) to arrange filters in a horizontal row.

Does the plugin support multilingual stores?

Yes. All user-facing strings are internationalised using the xc-product-filter-pro text domain. A .pot template is included in /languages/ for use with Poedit or Loco Translate. WPML and Polylang compatibility depends on those plugins' handling of WooCommerce taxonomies and custom post types.

How do I update the plugin?

With a valid licence key active, updates appear automatically in Dashboard β†’ Updates. Click Update β€” no manual download or file replacement is required. Updates are delivered securely from the XaniaCode update server.

How do I completely remove the plugin and all its data?

Deactivate the plugin then click Delete in the Plugins list. The uninstall.php routine runs automatically and removes all plugin data from the database: filter sets, SEO rules, plugin settings, and all transient cache entries.