Skip to main content
Get Oxygen
Documentation/Integrations/Facets/FacetWP
Integrations

FacetWP

FacetWP is a paid plugin that adds faceted filtering — checkboxes,
sliders, dropdowns, search boxes, sorting — to a list of posts. Oxygen has built-in support
for it: with both plugins active you place FacetWP's facets as Oxygen elements and turn on a
single toggle on the loop they filter.

Build the facets themselves in FacetWP first. Oxygen reads the facets you've defined
there; it doesn't create them.

Filter a loop with FacetWP

  1. Build your listing as usual with a loop element, and check that it outputs the posts you
    want before adding any filtering.
  2. Select the loop element and open its Content tab.
  3. Scroll to the FacetWP section at the bottom of the tab and turn Enable FacetWP on.
  4. Add a FacetWP Facet element to the page for each facet you want to show.
  5. With the Facet element selected, pick the facet from the Facet dropdown. The list is
    populated live from your FacetWP settings.
  6. Save and view the page on the front end.

Your facets now filter the loop. Ticking a checkbox re-queries the posts and swaps the
loop's markup without a page reload.

Note: facets only render on the front end. In the builder canvas the Facet element
shows a placeholder reading "FacetWP's your facet facet will appear here on the
frontend" — that's expected, not a broken element.

What the toggle actually does

Turning Enable FacetWP on does two things to that loop: it adds the facetwp-template
class to the loop's wrapper, which is the marker FacetWP looks for when it decides which
markup to refresh, and it tags the loop's query so FacetWP applies the current facet
selections to it.

Both of those are per-element and apply to the loop you enabled it on, which is why only
one loop per page can be filtered. If you enable the toggle on two loops on the same page,
the facets drive one of them.

Pagination

Enabling FacetWP switches off Oxygen's own pagination for that loop, and hides the loop's
Pagination controls while it's on. FacetWP has to own paging, because it is the thing
re-running the query.

Use FacetWP's own Pager facet for paging instead, and place it directly below the loop.

Troubleshooting

The facet renders but nothing filters

Check Enable FacetWP is actually on for the loop, on the Content tab of the loop
element rather than the facet. Also check there is only one FacetWP-enabled loop on the
page.

The Facet element says it requires a plugin

The element prints "The "FacetWP Facet" element requires the plugins "FacetWP"" when
FacetWP isn't installed and active. Activate FacetWP and reload the builder.

The Facet dropdown is empty

Oxygen lists the facets defined in FacetWP's own settings. An empty dropdown means no facets
have been created yet — build one in FacetWP first.

The loop shows a warning about the Slider layout

FacetWP can't drive a loop laid out as a slider. The builder prints a warning above the loop
when the layout is set to Slider and FacetWP is enabled. Switch the loop to a grid or list
layout, or drop the FacetWP filtering on that loop.

Pagination controls disappeared from the loop

Expected — see Pagination above. Add a Pager facet instead.