Query Filters – Interactive Filtering for WordPress Query Loop

WordPress’s Query Loop block displays posts, but it doesn’t give your visitors any way to narrow down what they see. If someone lands on a page with 200 posts, they scroll or they leave.

Groundworx Filters changes that. It adds interactive filter controls — taxonomy dropdowns, keyword search, sort options, active filter tags — directly to any Query Loop block. Visitors filter the results right on the page, without reloads, without custom code.

The plugin also includes Global Search — a site-wide search system with autocomplete suggestions, relevance ranking, and a tunable search engine that goes far beyond what WordPress offers out of the box.

How Filters Work

Filters are built entirely with blocks. There’s no shortcode, no widget, no settings page to wire things up. You add blocks to the page in the editor, and they work.

Every filter setup has two parts:

A Query Loop block — the block whose results get filtered.
A Filters container block — placed inside the Query Loop, this wraps all your filter controls and connects them to the query.

Here’s what the block structure looks like:

Query Loop
├── Filters (container)
│   ├── Filter Terms
│   ├── Filter Text
│   ├── Filter Order By
│   └── Filter Active
└── Post Template
    └── (your post layout)

When a visitor selects a category, types a keyword, or changes the sort order, the plugin updates the URL and re-renders the Query Loop with the filtered results. With the right settings, this happens instantly — no page reload, no flash of content.

Setting Up Your First Filter

Let’s walk through a complete setup. Say you have a blog with posts organized by category, and you want visitors to filter by category and search by keyword.

1. Add a Query Loop

Insert a Query Loop block on your page or template. Set it to display the post type you want (Posts, in this case). Design your Post Template however you like.

If you’re working in a template (like an archive), turn on Inherit query from template so the Query Loop uses the page’s natural query instead of a hardcoded one.

2. Add the Filters Block Container

Click inside the Query Loop and insert the Filters block (under the Groundworx category in the inserter). This is the wrapper that all your individual filter blocks live inside. It doesn’t display anything on its own — it’s the connection point between filters and the Query Loop.

3. Add Your Filter Blocks

Inside the Filters container, add:

A Filter Terms block — set the taxonomy to “Categories”
A Filter Text block — for keyword search

That’s a working filter interface. Save the page, visit the frontend, and you can filter posts by category and search by keyword.

4. Make It Instant

By default, selecting a filter reloads the entire page. That works, but it’s not a great experience. To make filters apply instantly without a page reload:

Select the Filters container and turn on Auto Submit in the sidebar.
Select the Query Loop block, open the Advanced panel, and turn off “Reload full page.”

Auto Submit tells the plugin to apply filters as soon as the user makes a selection (no submit button needed). Turning off “Reload full page” tells WordPress to use the Interactivity API to update just the Query Loop content instead of navigating to a new page. You need both.

Now when a visitor picks a category, the post list updates immediately.

The Filters Container

The Filters block is the required wrapper. Every filter block must be inside it.

It has one setting: Auto Submit. When enabled, filters apply the moment a user interacts with them. When disabled, the user sets all their filters and then clicks a Submit button to apply them all at once.

Auto Submit is better for simple interfaces (one or two filters) where immediate feedback feels natural. Manual submission is better for complex setups (five filters, a price range slider, a keyword search) where the user wants to dial everything in before waiting for results.

Laying Out Your Filters

The Filters block supports WordPress’s layout system — Flow, Flex, and Grid. This is how you control whether your filters appear in a row, a column, or a grid.

Horizontal filter bar — Switch to Flex layout with horizontal orientation. Each filter sits side by side. Turn on “Wrap” so they flow to the next line on smaller screens.
Stacked column — Keep the default Flow layout. Filters stack vertically. Works well in a sidebar.
Grid — Use Grid layout for equal-width columns. Good for symmetrical layouts like four filters in a 2×2 grid.

You also get the standard spacing controls (margin, padding, block gap) and alignment options (wide, full width).

Filter Blocks

Filter Terms

This is the most common filter. It lets visitors filter by taxonomy — categories, tags, or any custom taxonomy registered on the post type.

When you add a Filter Terms block, the sidebar shows a Taxonomy dropdown listing every public taxonomy available for the Query Loop’s post type. Pick the one you want.

Want to filter by both Category and Tag? Add two Filter Terms blocks — one for each taxonomy.

Single vs. Multiple Selection

Single selection means picking one term replaces the previous one. If a visitor selects “News,” then selects “Sports,” they see Sports posts — not News and Sports. This is the right choice when the categories are mutually exclusive or when you want a simple, focused experience.

Multiple selection lets visitors select several terms at once. Selecting “News” and “Sports” shows posts in either category. Use this when visitors might want to browse across categories.

Display Styles

You have four ways to present the terms:

Select — A native browser dropdown. It’s the most compact option and what users expect from form controls. Doesn’t support showing counts or hierarchy.

Custom Select — A styled dropdown built by the plugin. It looks more polished than a native select and supports features the native one can’t: term counts, hierarchical indentation, and a search field for finding terms in long lists. Use this when you need those features or want more visual control.

Inline — Terms are displayed horizontally in a row as radio buttons (single selection) or checkboxes (multiple selection). Good when you have a small number of terms and want them all visible at a glance.

Stacked — Same as Inline but vertical. Terms stack in a column. Good for sidebar filter layouts or when you have many terms.

Labels

Every filter has a label. By default Filter Terms uses the taxonomy name (e.g., “Categories”), but you can change it to anything. The Label Position controls where it appears:

Hidden — The label is visually hidden but still available to screen readers.
Stacked (Left, Center, Right) — The label sits above the control, aligned as specified.
Inline Start — The label sits to the left of the control on the same line.

Showing Term Counts

Turn on Show Count and each term displays the number of posts it contains — “News (12)”, “Sports (8)”. This helps visitors understand how many results they’ll get before clicking.

The plugin maintains its own per-post-type count table, so counts are accurate even when a taxonomy is shared across multiple post types.

Hierarchy

If your taxonomy has parent and child terms (like Categories often do), two settings help:

Show Only Top Level — Hides child terms entirely. Only parent terms appear.
Show Hierarchy — Shows child terms indented under their parents. This only works with Custom Select, Inline, and Stacked display styles — native Select dropdowns can’t render indentation.

Contextual Filtering

This is one of the more powerful features. When Contextual Terms is enabled, the filter dynamically updates based on other active filters.

Example: You have a Filter Terms for Categories and another for Tags. A visitor selects the “Recipes” category. With Contextual Terms enabled on the Tags filter, it now only shows tags that appear on posts in the Recipes category — “vegetarian,” “quick meals,” “desserts” — instead of every tag on the site. Tags that would return zero results disappear.

This keeps the interface clean and prevents dead-end selections.

Contextual Search adds a search input inside the Custom Select dropdown panel. Type to filter the term list. Useful when a taxonomy has dozens or hundreds of terms and scrolling isn’t practical.

Responsive Collapse

Inline and Stacked layouts can take up a lot of space on small screens. Toggle Behavior lets you collapse them into a dropdown at a specific breakpoint:

Off — Always show the full list.
On — Always show as a collapsed dropdown.
Responsive — Full list on large screens, dropdown on mobile or tablet (you choose the breakpoint).

Filter Text

A keyword search input. Visitors type a word or phrase, and the Query Loop shows only posts that match.

What Gets Searched

By default, Filter Text searches three places: the post title, the post content, and the post excerpt. In the Search Query panel you can toggle each one independently.

Searching only titles is faster and often more relevant — a title match is usually what the visitor wants. Searching content casts a wider net but can surface less relevant results. Choose based on your content.

Autocomplete

Filter Text can show suggestions as the visitor types. There are two modes:

Suggested Searches — The dropdown shows short keyword phrases pulled from your content. If a visitor types “choc,” they might see “chocolate cake,” “chocolate chip,” “chocolate mousse.” Selecting a suggestion fills the search input with that phrase and applies the filter. This uses bigram-aware word completion, meaning it understands multi-word phrases, not just single-word prefixes.

Suggested Links — Instead of keyword phrases, the dropdown shows matching post titles as direct links. If a visitor types “choc,” they see the actual posts “Chocolate Cake Recipe” and “Chocolate Chip Cookies” as clickable links that navigate straight to those posts. This turns the search input into a quick-navigate tool.

Context Aware makes suggestions respect the currently active filters. If the visitor has already filtered to the “Desserts” category, autocomplete only suggests content from dessert posts — not from every post on the site.

Filter Order By

Gives visitors control over how results are sorted.

Out of the box, it offers four options:

Date (Newest first)
Date (Oldest first)
Title (A → Z)
Title (Z → A)

You can customize these in the sidebar — rename labels, reorder options, or remove ones you don’t need.

The Default Order syncs with whatever ordering the Query Loop block itself uses. If the Query Loop is set to show newest first, that’s the default sort visitors see before they change anything.

It supports the same display styles as Filter Terms: Select, Custom Select, Inline, and Stacked.

Adding Custom Sort Options

Developers can add sort options beyond what the editor provides. Use the PHP filter groundworx/filter_orderby_options-{post_type}:

add_filter( 'groundworx/filter_orderby_options-product', function ( $options ) {
    $options['price-low'] = array(
        'label'    => 'Price (Low to High)',
        'orderby'  => 'meta_value_num',
        'meta_key' => '_price',
        'order'    => 'ASC',
    );

    $options['price-high'] = array(
        'label'    => 'Price (High to Low)',
        'orderby'  => 'meta_value_num',
        'meta_key' => '_price',
        'order'    => 'DESC',
    );

    return $options;
} );

This adds two price-based sort options to the Order By filter on any Query Loop displaying the product post type. You can sort by any standard WordPress field (date, title, menu_order, rand, ID) or by meta fields (using meta_value for text, meta_value_num for numbers).

Filter Active

Shows visitors what’s currently filtering their results and lets them remove individual filters.

When a visitor selects a category, types a search keyword, or changes the sort order, Filter Active displays each active filter as a tag — “Category: News,” “Search: chocolate,” — with a remove button (×) next to each one. Clicking the × removes that single filter. When no filters are active, the block hides itself.

This is important for usability. Without it, visitors can lose track of what they’ve filtered, especially on pages with many filter options.

Clear All

Filter Active can include a Clear All button that removes every active filter at once. You control the label (default: “Clear All”) and its position — End places it after the last filter tag in the same row, Under places it on its own line below the tags.

Layout

Filter tags can flow Inline (horizontally, wrapping to the next line) or Stacked (vertically, one per line). Inline is the most common choice — it’s compact and familiar.

Filter Submit

A button that applies all filters at once. You only need this when Auto Submit is off on the Filters container.

When Auto Submit is on, the Submit block hides itself automatically — you don’t need to remove it from the editor. This means you can keep it in your layout and toggle Auto Submit without restructuring blocks.

The button supports full styling: typography, colors, borders, and you can set its width as a percentage for consistent sizing.

Filter Clear

A standalone “Clear All” button that removes every active filter. This is separate from the Clear All button inside Filter Active — it’s its own block that you can place anywhere in your layout.

Like Filter Active’s Clear All, it hides when no filters are active.

Use this when you want a prominent, always-accessible reset button — maybe at the top of a sidebar filter column or at the end of a filter bar.

WooCommerce Filters

When WooCommerce is active, four additional filter blocks appear, designed specifically for product filtering. They work exactly like the standard filter blocks — they go inside a Filters container, inside a Query Loop set to display Products.

Filter Woo Price

Lets visitors narrow products by price. Two display modes:

Slider — A dual-handle range slider. Visitors drag the min and max handles to set a price range, or type exact values into the number inputs beside the slider. You configure the overall range (min, max) and the step increment in the sidebar.

Set the range to match your actual product prices. If your cheapest product is $10 and your most expensive is $200, set the slider to 10–200 with a step of 5 or 10. A 0–1,000,000 slider with a step of 1 is technically functional but practically useless.

Tiers — Predefined price ranges that visitors choose from, like “Under $25,” “$25–$50,” “$50–$100.” These display using the same styles as Filter Terms (Select, Custom Select, Inline, Stacked). You define the tier labels and ranges in the sidebar — add, remove, or adjust them to match your product catalog.

Currency formatting (symbol, position, decimals) comes from your WooCommerce settings automatically.

Filter Woo Stock Status

Filters products by availability: In Stock, Out of Stock, or On Backorder. Supports single or multiple selection and all four display styles.

Straightforward and useful on any shop. Most stores will want at least a way for customers to hide out-of-stock products.

Filter Woo Rating

Filters products by average star rating. Visitors select a rating threshold — “4 stars and up,” “3 stars and up” — and only products meeting that rating appear.

The Show Stars toggle controls whether star icons display alongside the numbers. It’s on by default and helps visitors scan the options quickly.

Filter Woo On Sale

A simple on/off toggle that shows only products currently on sale. Choose between a Checkbox or a Toggle switch for the UI.

No configuration needed beyond the label — it reads WooCommerce’s sale metadata automatically.

Global Search

Everything above — Filter Terms, Filter Text, Order By — works inside a Query Loop. Global Search is different. It searches your entire site and presents results in a suggestion panel, independent of any Query Loop.

Think of it as a replacement for WordPress’s default search. Instead of a basic text input that dumps you on a search results page, Global Search shows instant suggestions as you type: keyword phrases, direct links to matching content, and even curated quick links — all before you hit Enter.

Where to Use It

There are two variants:

Global Search (Expanded) — The suggestions panel is always visible below the input. Good for dedicated search pages, prominent search sections, or anywhere you have room to display results inline.

Global Search Dropdown — A compact input that opens a dropdown panel when the user starts typing. The panel disappears when they click away. This is what you want in a header, navigation bar, or sidebar where space is limited.

Both variants have the same capabilities — they just differ in how the panel appears.

Building a Global Search

Global Search uses nested blocks. You compose the search interface by arranging child blocks inside it:

Global Search (or Global Search Dropdown)
├── Search Input
└── Autocomplete Dropdown
    ├── Suggested Searches
    │   ├── Search: Post Types
    │   └── Search: Taxonomies
    ├── Suggested Links
    │   ├── Search: Post Types
    │   ├── Search: Taxonomies
    │   └── Search: Profiles
    └── Quick Links
        ├── Link
        ├── Link
        └── Link

This structure gives you full control over what appears in the suggestion panel.

Search Input

The text field. Set the label, label position (or hide it), and placeholder text. Standard input controls.

Quick Links

A curated set of links that appear before the visitor types anything. This turns the search panel into a navigation tool — when someone opens the search, they immediately see useful destinations: your homepage, popular categories, current promotions, contact page, whatever makes sense.

Add individual Link blocks inside Quick Links, each with a URL and label.

Tutorial