WPXFacets Documentation

Getting Started

This guide walks you through a full setup from a fresh install to a working filter on the frontend.

Install the Plugin

Download the WPXFacets .zip file from your account dashboard on wpxfacets.com.
In your WordPress admin, go to Plugins → Add New → Upload Plugin.
Select the downloaded .zip and click Install Now.
Click Activate Plugin.

After activation, a new XFacets menu item appears in the WordPress admin sidebar.

Connect Your Elastic Server

Go to XFacets → Settings → Elastic Server.
Enter the Elastic Server URL, Elastic Server User and Elastic Server Password from your account dashboard on wpxfacets.com.
Click Test Connection, then save.

On the Free plan you can skip this step — WPXFacets runs on WordPress database queries and needs no Elasticsearch infrastructure. If a connected server later becomes unreachable, product queries fall back to WP Query automatically and return to Elasticsearch when it recovers.

Choose the Query Engine

Go to XFacets → Settings → General.
In the WooCommerce Products card, confirm Enable filtering is on.
Set the query engine to Elastic search. WP Query (default) is the Free-plan path.
Save.

Run Your First Sync

During the 15-day Starter trial, Elasticsearch indexing is limited to 1,000 products.

Before facets can return results, your product catalog needs to be indexed.

Go to XFacets → Sync.
Click Start Sync.
Wait for the sync to complete. Progress is shown inline.

Run a sync whenever you make significant changes to your catalog — new products, updated attributes, new taxonomies. Small individual changes (single product saves) are picked up automatically.

Create a Filter Form

Go to XFacets → Filter forms.
Open an existing form, or create a new one.
Name the form in the header field.
Click Save Form.

A form’s own shortcode, with its ID filled in, is shown at the top of its editing screen.

Add Facets to the Form

A facet is one filter dimension inside the form: where it reads its values from, how it presents them, and when it is displayed.

In the form editor, click Add new facet.
Fill in Facet Title — the heading shown above the control. Facet Slug is generated from it and becomes the facet’s URL parameter.
Choose a Facet source, then the Facet value that source requires.
Choose a Facet type — the UI control shown to the visitor.
Set Display this filter, and the “show more” behavior for list-type facets.
Click Save, then Save Form.

Available facet types update dynamically based on the source you choose. Invalid combinations are disabled automatically — see the Source → Display Type Reference below.

Display on the Frontend

WPXFacets renders through three shortcodes, each with an equivalent block.

Shortcode	Block	Renders
`[xfacets_filter_form]`	XFacets Filter Form	The filter controls for one filter form.
`[xfacets_search_results]`	XFacets Search Results	The product grid, filtered by the current URL state.
`[xfacets_search_bar]`	XFacets Search Bar	The global catalog search bar with autosuggest.

A standard filtered catalog page contains the first two. Create a page (or edit an existing one) and add them to the content:

[xfacets_filter_form]
[xfacets_search_results]

Place them side by side in a two-column layout for a standard filter + results UI.

Shortcode attributes

Shortcode	Attribute	Default	Notes
`[xfacets_filter_form]`	`form-id`	the site default form	The ID shown in the filter form editor. Omit it and the default form is used.
`[xfacets_filter_form]`	`mobile-display`	`drawer`	`drawer` renders a “Filters” button that opens a slide-in panel on small screens. `inline` renders the controls in the flow of the page.
`[xfacets_search_bar]`	`class`	—	Extra class names on the wrapper, for theme styling.

From a theme template, call xfacets_filter_form( 84 ); instead of writing the shortcode.

Where WPXFacets Renders

WPXFacets serves two things: the WooCommerce Shop page, automatically, once filtering is enabled for products; and any page containing the shortcodes or blocks above.

Taxonomy archives — product category, product tag, and attribute archives — are served by WooCommerce. WPXFacets does not replace their product loop, and a filter form placed in a global sidebar will not filter them. This is a boundary of the current release, not a design preference: a category archive takes its scope from the term being viewed, and WPXFacets has no mechanism yet for carrying that scope into its own query, so rather than half-apply it, it leaves those pages alone. Scoped filtering on taxonomy archives is planned.

Settings

License

Field	Description
`License key`	Provided in your wpxfacets.com account dashboard.
`License token`	Paired with the license key.
`Plugin access secret`	Provided alongside the key and token in your account dashboard.

Elastic Server Connection

Field	Description
`Elastic Server URL`	Elasticsearch URL, auto-generated at subscription activation.
`Elastic Server User`	Elasticsearch username, auto-generated at subscription activation.
`Elastic Server Password`	Elasticsearch password, auto-generated at subscription activation.
`Sync Batch Size`	Products sent per request during indexing. Raise it on strong hosting; lower it if requests time out.

Credentials are tied to your WooCommerce subscription. If your subscription lapses, access is automatically revoked.

Two screens are called Elastic Server. Settings → Elastic Server holds the connection credentials. The top-level XFacets → Elastic Server holds the search configuration: Fields, Synonyms, Analyzer and Search Bar.

General

The General tab shows one card per filterable post type. WooCommerce Products is the active one; a Posts card is present and marked Coming soon.

Field	Description
`Enable filtering`	Turns this post type on or off for all filter forms.
Query engine	`WP Query (default)` on the Free path, or `Elastic search` on Starter, Grow and Custom. Elasticsearch stays disabled until a server is connected.
`Index product variations`	Include variation attributes in facet values.
`Hide out-of-stock products`	Exclude them from results and from facet counts.

Elastic Server (Search Configuration)

XFacets → Elastic Server is where you configure what Elasticsearch searches and how it interprets a query. It has four tabs.

Tab	Purpose
`Fields`	Which product fields are searched, and how strongly each one counts toward relevance.
`Synonyms`	Query-time synonym rules, with CSV import/export and an explicit deploy step.
`Analyzer`	Reserved. Analyzer settings and mapping diagnostics are not available yet.
`Search Bar`	Configuration for the global search bar and its autosuggest dropdown.

The page shows the Elastic Server connection state at the top. When the server is unreachable you can still edit and save local configuration; only the operations that contact Elasticsearch — such as deploying synonyms — are unavailable.

Sync

The Sync screen triggers a full re-index of your product catalog into Elasticsearch.

When to run a manual sync:

After initial setup.
After a bulk product import.
After adding or renaming a taxonomy or product attribute.
After changing the analyzer or the index mapping.
After adding a meta or taxonomy value that existing products have not been re-saved with.

Editing a single product re-indexes it on save. Adding or removing a search field, or changing a field weight, applies to the next query and needs no sync.

Filter Forms

A Filter Form groups multiple facets into a single renderable unit. A site can have several.

Each form has a name, an ID, and an ordered list of facets.
Drag facets by the handle to reorder them. The order is what the frontend renders.
The form editor shows that form’s own shortcode, with its ID filled in.
Forms can be exported to JSON and imported from the same screen — useful for moving a configuration between staging and production.
You can create as many forms as you need.

Facets are created inside the form, not on a separate screen — use Add new facet in the form editor.

Facets

A facet defines a single filter dimension: what data it reads from (source), how it presents choices to the user (display type), and any additional configuration (display settings).

Source

The Source defines where the facet reads its values from.

Source	What it reads	Value you supply
`Search Fields`	The global search-field configuration under XFacets → Elastic Server → Fields.	None — the corpus is configured once for the whole site.
`Taxonomy`	Any registered non-builtin WordPress taxonomy, including product categories and tags.	The taxonomy.
`Post Meta Keys`	A post meta field attached to products.	The exact meta key.
`WooCommerce`	Native WooCommerce values.	Price, Rating, On sale, Favorites, or Stock.
`Product attributes`	WooCommerce global product attributes.	The attribute.

Search Fields replaced the older per-facet “WP Objects” source. A Search facet no longer carries its own list of searched fields; it uses the site-wide configuration, so one change updates every Search facet at once.

Display Type

The Display Type defines the UI component rendered for this facet.

Display Type	Description
Checkbox	Multi-select list of values. The visitor can select one or more options.
Radio	Single-select list. Only one option can be active at a time.
Slider	Dual-handle range slider, for numeric ranges.
Single custom range (min/max inputs)	Two manual input fields. An alternative to the slider for numeric ranges.
Search field	Text input that searches the fields configured under XFacets → Elastic Server → Fields.
Rating	Star-based filter. Matches products at or above the selected rating.

Source → Display Type Reference

Not all source and display type combinations are valid. The table below shows what is available for each source.

Source	Source value	Available facet types
`Search Fields`	—	Search field
`Taxonomy`	any	Checkbox, Radio
`Product attributes`	any	Checkbox, Radio
`Post Meta Keys`	any	Checkbox, Radio, Slider, Single custom range, Rating
`WooCommerce`	Price	Slider, Single custom range
`WooCommerce`	Rating	Rating, Slider, Single custom range
`WooCommerce`	Stock	Checkbox, Slider, Single custom range
`WooCommerce`	On sale	Checkbox
`WooCommerce`	Favorites	Checkbox

The facet editor enforces these constraints automatically — invalid display types are disabled when you select a source.

Display Settings

Every facet carries a display condition. List-type facets also carry a “show more” setting.

Setting	Description
`Display this filter`	Always — rendered everywhere. Never — never rendered. Search results only — rendered only on a page showing results for a global search query.
`Show a limited number of filter terms`	Truncates the list and adds a “show more” toggle. Available for Checkbox and Radio facets, except the on/off WooCommerce values (On sale, Favorites, Stock).
`How many items`	The number of terms shown before the toggle appears.

Display this filter controls rendering only. It never controls filtering. All three values are applied to the query, so a facet set to Never still narrows the results — that is what makes it useful for pinning a category to a page.