Getting started

Overview

Facets are filter controls that live outside the loop they filter. You place them anywhere on the page — a sidebar, a header bar, inside a Filter Panel — and they rewrite the loop's query over AJAX as the visitor clicks.

There are three kinds of element involved, and it helps to keep them straight:

Getting started

Requirements

Each facet element can be switched off individually under Settings → Phox Elements if you don't want it cluttering the builder's element list.

Getting started

Quick start

The fastest useful setup: a product grid with a category filter and a result count.

1. Start with a loop. Add a Products List, Shop Page, Posts List, Post Loop or Phox Product Grid to the page and configure its query as you normally would. Facets take over the filtering, not the query itself.
2. Add a facet. Drop a Facet — Checkbox next to it. Set Data Source to Taxonomy and pick product_cat.
3. Name it. Set Facet Name to something short and URL-friendly, e.g. category. This becomes part of the address bar, so keep it readable.
4. Add a Results Count above the grid so visitors can see the effect.
5. View the page. Tick a category — the grid refreshes in place, the count updates, and the URL gains ?_pf_category=shirts.

Getting started

How filtering works

Worth understanding, because almost every support question comes back to it. Facets run down two different paths that must produce identical results.

1. Full page load

Filter values are read from the _pf_* URL parameters. The loop runs as a normal query and the filters are applied to it before it executes. This is what happens when someone opens a shared link, hits back, or lands from Google.

2. AJAX refresh

Clicking a facet posts the current values to the server, which re-renders just that loop element and returns its HTML along with recalculated counts, ranges and pagination. The browser swaps the loop's markup and updates the URL.

Counts

Option counts use "OR-back" logic: each facet's counts are calculated against everything matching the other active filters, but not its own. That's why ticking one colour doesn't make every other colour read zero — you can still see what else is available, while counts still narrow as you filter on other facets.

Building filters

Loops & targets

These loop elements become filter targets automatically:

Other elements can be added by a developer — see Custom loop elements.

Target ID

Every supported loop gains a Target ID field (under the element's own Phox Facets section), and every facet has a matching Target ID under Advanced.

• Leave both empty when there's one loop on the page. Everything wires itself up.
• Set a matching ID on the loop and on each facet when a page has two or more loops — for example a "New in" grid and a "Sale" grid, each with its own filters.

Building filters

The facet elements

Input facets Filters

Display facets Output

Settings every facet shares

Building filters

Data sources

Option-based facets (Checkbox, Radio, Dropdown, Colour Swatch) all ask the same first question: where do the options come from?

Building filters

Terms, counts & order

Taxonomy-sourced facets share a set of controls for shaping the list:

Building filters

AND / OR logic

Multi-select facets (Checkbox, Colour Swatch) have a Logic setting that decides how several ticks combine:

OR is the default and is what shoppers expect from a colour or size filter. Reach for AND when the terms describe capabilities a single item can hold all of at once.

Facets are always combined with each other using AND: picking a colour and a size narrows to items matching both.

Building filters

Sorting

The Sort facet renders a dropdown of orderings you define. Each option carries a Label, a Value, an Order By, an Order and optionally a Meta Key for sorting on a custom field.

It also has a Default Option, which decides what's selected before the visitor chooses anything.

Building filters

Pagination & results count

Pagination

The Pagination facet replaces the loop element's own pagination with an AJAX version. Three types:

Scroll to Top returns the visitor to the top of the results after a page change, which matters most on long grids.

Results count

The Results Count facet has three templates, each using {count} as the placeholder:

The same live count drives the Filter Panel's footer button, so "Show 42 results" stays in step with the grid.

Building filters

Active filters & reset

Active Filters renders a chip for each applied filter, each with its own remove button, plus an optional Clear All. It can Hide When Empty so it takes no space on an unfiltered page.

Reset is a single button that clears every facet at once. Hide When No Filters keeps it out of the way until it's useful, and Show Icon adds a small clear icon.

The Filter Panel

Filter Panel New

The Filter Panel is a container that behaves like an ordinary div on desktop and collapses into an off-canvas drawer below a breakpoint you choose — so the same set of facets serves both layouts.

Before it existed, a responsive filter layout meant building your facets twice: once inline for desktop, once inside an off-canvas panel for mobile, with two sets of Facet Names to keep in step. The Filter Panel removes that duplication entirely.

Building one

1. Add the Filter Panel where the filters should sit on desktop — typically a sidebar column or a bar above the grid.
2. Put your facets inside it. It's a normal container, so drag in Checkbox, Range Slider, Sort, Reset and anything else, in any arrangement.
3. Choose the breakpoint at which it becomes a panel.
4. Add a trigger button anywhere on the page and give it the Open Class.
5. Style each state separately using the On-screen Div and Off-screen Panel sections.

The Filter Panel

Breakpoint & modes

Becomes a Panel At is the central setting. At or below the width you pick, the container turns into an off-canvas drawer; above it, it's a plain container in the page.

Panel Position slides it in from the Left, Right, Top or Bottom. Left and Right take a Width; Top and Bottom take a Height.

Open In Builder

The panel is closed by default, which makes it awkward to style. Switch the builder to a breakpoint below your chosen one and turn Open In Builder on to hold it open while you work.

What visitors get

In panel mode the drawer closes on the close button, on the backdrop, on Esc, and after tapping the footer button. The page behind it is scroll-locked while it's open — and if the window is resized back above the breakpoint while open, the panel closes itself and releases the lock rather than leaving the page stuck.

The Filter Panel

The trigger button

The panel has no button of its own — you build one from any element you like (a Button, a Fancy Button, a Div with an icon) and connect it with a CSS class.

1. Set the Open Class on the Filter Panel, e.g. openfilters (the default).
2. Add that class to your button under its own Advanced → CSS Classes.
3. Optionally set a Close Class and add it to any element that should close the panel.

Any number of elements can carry the Open Class, and because the binding is delegated, buttons added to the page later — including ones inside AJAX-refreshed markup — still work.

Hide Trigger Above Breakpoint

On by default. The trigger is usually only wanted where the panel exists, and this hides any element carrying the Open Class above the breakpoint, so you don't have to set its responsive visibility by hand.

The Filter Panel

Footer bar

Turn on Show Footer Bar and the panel gains a bar pinned to its bottom edge with a single button — the pattern every large retailer uses on mobile.

Footer Button Text accepts {count}, which is replaced with the live results total:

Show {count} results     →  "Show 42 results"

The count tracks the filtered loop as the visitor changes filters inside the panel, so they can see the effect before committing. Tapping the button closes the panel.

The footer's background, button colours and corner radius are all in Design → Footer Bar.

The Filter Panel

Styling both states

Because one element renders two quite different things, the design controls are split to match:

Two Layout controls

Each state has its own Layout popout, which is the point: a horizontal row of filters across the top of the page on desktop, and a vertical stack inside the drawer on mobile, from a single set of facets. Set each independently — direction, alignment and gap.

Widths

The two Width controls are separate for the same reason. The on-screen width sizes the container in the page — useful when it sits in a centred column and you want it to fill the available space. The panel width sizes the drawer. Both are responsive, and the on-screen width is capped at 100% of its column so a large fixed value can't overflow the page.

Special facets

Range slider

A two-handle slider for numeric filtering. Data Source chooses what it reads:

• Price — WooCommerce product price, sale-aware.
• Custom Field (Meta) — any numeric meta key.
• Taxonomy — numeric term names, for stores that store sizes or capacities as terms.

Min Value, Max Value and Step set the bounds; leave min and max empty to have them calculated from the current results and re-calculated as other filters narrow the set. Prefix and Suffix add units — £ or cm. Show Min/Max Inputs adds number boxes beside the slider for precise entry.

The slider fires on release rather than on every pixel of movement, so dragging doesn't flood the server with requests.

Special facets

Date range

Filters on a date stored in post meta. Fields chooses whether to show both a start and an end picker or just one.

Special facets

Colour swatches

Renders taxonomy terms as colour chips or image tiles instead of checkboxes. The colour or image comes from term meta, which the plugin adds to the term edit screen for you — open any term under Products → Attributes or a taxonomy and you'll find the swatch fields there.

Everything from Terms, counts & order applies here too — counts, hide empty, exclude, parent term, limit and ordering.

Special facets

A–Z listing

An alphabet strip that filters by the first letter of the post title — for directories, glossaries, brand indexes and staff listings.

• Post Type — which post type the letter pool is built from.
• Show Counts — the number of entries behind each letter.
• Show # (Numbers) — a # entry gathering titles that start with a digit.
• All Label — the text of the "show everything" entry.

Letters with no entries are rendered inactive rather than hidden, so the strip keeps a stable width as the visitor filters.

Special facets

Map

The Map facet works in both directions: it can filter the loop to whatever is inside the visible map area, and it shows the currently filtered results as pins.

Coordinates

Provider & appearance

Choose Leaflet / OpenStreetMap (no key required) or Google Maps (set the Phox Google Maps API Key under Breakdance → Settings → API Keys). Map Type offers Roadmap, Satellite, Hybrid and Terrain, and Default Zoom, Default Latitude and Default Longitude set the opening view.

Pins & clusters

Pins can be a coloured marker (with Pin Color, width and height) or an image, including a per-post pin image pulled from a meta key so each result can carry its own thumbnail — with border width, colour, radius, background and padding controls for framing it.

Marker Clustering groups nearby pins, with cluster colour, text colour and size, and an optional Vary Color by Count so busier clusters use a High-Count Color above a threshold you set.

Popups

Popup Content chooses between Title Only, Title + Excerpt, Title + Thumbnail + Excerpt, or no popup. Excerpt Format decides whether the excerpt renders formatted, exactly as it appears on the post, or as plain trimmed text with an Excerpt Length word cap.

Workflow

URLs & shareable filters

Every filter change is written to the address bar using the facet's own name with a _pf_ prefix:

/shop/?_pf_category=shirts,coats&_pf_price=20-80&_pf_sort=price_asc

Because state lives entirely in the URL, filtered pages can be shared, bookmarked, emailed to a customer, linked from an ad, or used as a landing page. Back and forward work as visitors expect — the browser's history is updated on every change and the page restores that exact state.

Workflow

Archives & category pages

Facets work on ordinary pages and on archive templates — a shop page, a product category, a taxonomy archive, a post type archive. On an archive, the archive's own scope is preserved: filtering inside Footwear narrows within Footwear rather than escaping to the whole catalogue.

This holds even when a facet filters the very taxonomy the archive is built on. A category facet on a category archive filters within that branch.

Per-category template overrides

If a specific category uses its own Breakdance template, make sure the loop in that template is one of the supported elements and that Target IDs don't collide with the generic template's. A page that resolves several templates can otherwise end up targeting a loop that isn't the one on screen.

Workflow

Caching

Filtered pages must not be cached, or visitors get someone else's results. The plugin handles this for you: when any _pf_* parameter is present it sets DONOTCACHEPAGE, sends no-cache headers, and disables WordPress's canonical redirect so filter parameters aren't stripped.

That covers every cache plugin that respects the standard constant, and most hosting page caches. If a host's edge cache still serves stale filtered pages, add an exclusion rule for URLs containing _pf_.

Workflow

Oxygen

The Phox Oxygen plugin carries the same facet elements and the same filtering engine, so everything in this document applies there too. The differences are cosmetic: element names appear in Oxygen's element panel, and the generated CSS uses Oxygen's class naming.

Configurations aren't portable between the two builders — a page built in Breakdance has to be rebuilt in Oxygen — but the facet settings themselves are identical, so there's nothing new to learn.

---

Developer reference

Architecture

PHP lives in includes/phox-facets/ under the PhoxFacets namespace; the front-end runtime is assets/phox-facets.js; the UI elements are elements/Facet_*.

Query types

Each facet resolves to one query type, either from its own configuration or by detection from its name:

tax_query · meta_query · search · orderby · price_range
on_sale · featured · tax_range · title_alpha · date_range · geo_bounds

Developer reference

Front-end config

The plugin prints a configuration object in the footer of any page carrying facets:

window.PhoxFacetsConfig = {
    ajaxUrl,            // endpoint
    targets,            // [{ postId, elementId, ssrPath, targetId, elementSlug }]
    initialPagination,  // { found_posts, max_pages, current_page }
    paramPrefix,        // '_pf_'
    archiveContext      // { type:'term'|'shop'|'post_type_archive', ... }
};

It's the first thing to inspect when debugging. An empty targets array means no supported loop was found; a missing or wrong archiveContext explains scope escaping on archive pages.

Each AJAX request posts postId, elementId, ssrFilePath, paged, facets, facetConfigs and archiveContext, and the response carries html, maxPages, foundPosts, currentPage, facets, facetCounts, facetRanges and mapMarkers.

Developer reference

Hooks & filters

// Add a loop element to the supported-target list.
add_filter( 'phox_facets_supported_elements', function ( $slugs ) {
    $slugs[] = 'MyPlugin\\MyLoop';
    return $slugs;
} );

// Tell the AJAX handler which ssr.php to render for it.
add_filter( 'phox_facets_element_ssr_path', function ( $path, $slug ) {
    return $slug === 'MyPlugin\\MyLoop'
        ? MY_PLUGIN_DIR . 'elements/MyLoop/ssr.php'
        : $path;
}, 10, 2 );

// Allow that path through the SSR allowlist.
add_filter( 'phox_facets_allowed_ssr_paths', function ( $paths ) {
    $paths[] = MY_PLUGIN_DIR . 'elements/MyLoop/ssr.php';
    return $paths;
} );

// Supply a config for a facet name the detector cannot resolve.
add_filter( 'phox_facets_detect_config', function ( $config, $name, $value ) {
    if ( $name === 'region' ) {
        return [ 'query_type' => 'tax_query', 'taxonomy' => 'area' ];
    }
    return $config;
}, 10, 3 );

// Stop a secondary query overwriting the captured pagination data.
add_filter( 'phox_facets_should_capture_query', function ( $should, $query ) {
    return $query->get( 'my_widget_query' ) ? false : $should;
}, 10, 2 );

Developer reference

Custom loop elements

To make your own loop element filterable:

1. Register it as a target with phox_facets_supported_elements. It then gets the Target ID control and the target classes automatically.
2. Point the handler at its SSR file with phox_facets_element_ssr_path, and allow that path with phox_facets_allowed_ssr_paths.
3. Build the query through the builder's query control so the facet filters actually run. If you build a raw WP_Query from control args instead, those filters never fire and you must apply $_POST['archiveContext'] yourself.
4. Leave the query in scope. The handler collects pagination from a $loop WP_Query variable left behind by the SSR file.

Writing a facet element

Follow Facet_Checkbox — it's the canonical implementation. The contract is: enqueue phox-facets, render a wrapper carrying data-phox-facet, data-phox-facet-name and a data-phox-facet-config JSON blob, read the current value from FacetRegistry, and register the facet with QueryModifier so full page loads filter correctly.

---

Help

Troubleshooting

The facet does nothing at all

Check window.PhoxFacetsConfig in the browser console. If targets is empty, no supported loop was detected — confirm the loop is one of the supported elements. If targets exist but the facet is inert, check its Facet Name is set and that its Target ID (if any) matches the loop's exactly.

Filtering shows results from outside the current category

The archive context isn't surviving the AJAX request. Inspect PhoxFacetsConfig.archiveContext — on a category page it should read type: "term" with the correct term_id. If it's empty, the page isn't resolving as an archive. If it's correct but results still escape, the loop element is building its query outside the builder's query control.

Sorting reloads the grid but the order never changes

WooCommerce's catalogue ordering applies its ordering at SQL level and overrides plain query arguments. The plugin bypasses that path when a sort facet is active — if you see this on a custom loop, that element needs the same treatment.

The results count or pagination is stuck on the wrong number

Both read the captured loop data, and a secondary query — a related-products block, a second loop — can overwrite it. Exclude that query with phox_facets_should_capture_query. If the count element sits above the loop it will have no data on first render; the JS corrects it immediately after load.

Counts look wrong on a numeric taxonomy

Term names that aren't plain integers are parsed for their numeric value, including European decimal formats. If counts still look wrong, check the term names for stray characters before suspecting the query.

Filtering lands on a 404, or the parameters are stripped

WordPress's canonical redirect is disabled when facet parameters are present, so this is nearly always a host or edge cache serving a redirect it cached earlier. Exclude URLs containing _pf_ from the cache.

The Filter Panel doesn't open

Confirm the trigger element actually carries the Open Class — check it in the page source, not just in the builder. If Hide Trigger Above Breakpoint is on, remember the button is deliberately hidden on desktop; test at a width below your breakpoint.

The panel opens but sits behind something, or in the wrong place

The panel is fixed-positioned, and a CSS transform, filter or backdrop-filter on any ancestor section creates a new containing block that traps it. Check the parent section for animation or blur effects.

Facets stopped working after enabling an optimisation plugin

Exclude the Phox Elements scripts from JavaScript concatenation and minification. A bundle that fails to build takes the facets runtime with it.

Help

FAQ

Do facets work with posts, or only products?

Any post type. WooCommerce is only needed for product-specific filters — price, sale status, featured and product attributes.

Can one page have two independently filtered loops?

Yes. Give each loop a unique Target ID and set the matching ID on each facet. Facets with an empty Target ID filter every loop on the page.

Do I need to build my filters twice for mobile?

No — that's exactly what the Filter Panel removes. One set of facets renders inline on desktop and as a drawer on mobile.

Can visitors share a filtered view?

Yes. The full filter state lives in the URL, so any filtered page can be copied, shared, bookmarked or used as a landing page.

Will filtered pages get cached and served to the wrong visitor?

No. Pages carrying facet parameters are marked uncacheable and sent with no-cache headers. See Caching.

Why do other options still show a count when I've already filtered?

By design. Counts within a facet are calculated against the other active filters but not that facet's own selection, so visitors can see what else is available rather than facing a column of zeros.

Can I filter on an ACF field?

Yes — set the facet's Data Source to Custom Field (Meta) and enter the field name as the Meta Key. For ACF date fields, match the Date Storage Format to how ACF saves the value.

Can I control the order of sizes rather than sorting them alphabetically?

Yes — set a sort value on each term and choose Order By → Menu Order on the facet.

Does it work on category and shop archive pages?

Yes, and the archive's own scope is preserved — filtering inside a category narrows within it rather than escaping to the whole catalogue.

Is the Oxygen version the same?

Yes. Same elements, same engine, same settings. Only the element panel and generated class names differ.

---