Filters – Interactive Filtering for WordPress Query Loop

The Filters system extends the WordPress Query Loop block with interactive filtering. Users can filter posts by taxonomy, search by keyword, sort results, and see active filters—all without page reloads. Version 1.2.0 adds intelligent autocomplete search, full ADA compliance, and WooCommerce product filtering.

How Filters Work

Groundworx Filters are designed specifically to work with the WordPress Query Loop block. The Filters container and all Filter blocks (Filter Terms, Filter Text, Filter Order By, Filter Active, Filter Submit) must be placed inside a Query Loop block.

When users interact with filters, the Query Loop automatically updates to show matching results.

Key Points:

• Filters only work inside a Query Loop block
• All filter blocks belong inside a Filters container
• For instant filtering, disable “Reload full page” in the Query Loop’s Advanced panel
• Multiple independent filter groups can run on the same page

Adding Filters to Query Loop

1. Add a Query Loop block to your page
2. Inside the Query Loop, add a Filters block
3. Add filter blocks inside the Filters container
4. Configure each filter block’s settings

Filters Container Settings

The Filters block wraps all your filter controls and manages submission behavior.

Building a Filter Interface

Here’s a typical filter setup:

1. Query Loop with Enhanced Pagination enabled
2. Filters container with Auto Submit enabled
3. Inside Filters:
   • Filter Terms for category selection
   • Filter Text for keyword search
   • Filter Order By for sorting
   • Filter Active to show selected filters

Wrap filter blocks in Groups or Columns for custom layouts.

Enabling Instant Filtering

Auto Submit – When enabled, filters apply immediately when users make selections. When disabled, users must click a submit button to apply filters. For Auto Submit to work instantly (without page reloads), you must disable “Reload full page” in the Query Loop settings:

1. Select the Query Loop block
2. Open the Advanced panel in the sidebar
3. Disable “Reload full page” toggle

The “Reload full page” setting is found in the Query Loop block’s Advanced panel, below the HTML Element dropdown. When the toggle is off (disabled), the Query Loop updates dynamically without refreshing the page.

When “Reload full page” is disabled:

• Query Loop uses the Interactivity Router for seamless updates
• Auto Submit works instantly without page reload
• Smooth transitions between filter states
• Better performance and user experience

When “Reload full page” is enabled:

• Each filter change triggers a full page reload
• Auto Submit is then disabled, and a submit button will be used to submit
• Traditional form submission behavior

Filter Blocks

Add these blocks inside the Filters container:

Filters

Groups your filter controls. Auto-submit applies filters instantly—no button needed. Manual mode waits for the user to click submit. Each wrapper works independently, so you can have multiple filter groups on the same page without conflicts. Full layout controls for arranging child blocks.

Filter Terms Block

Filter by taxonomy terms (categories, tags, or custom taxonomies).

Taxonomy – Select which taxonomy to filter by

Selection Type:

• Single – Users can select one term at a time
• Multiple – Users can select multiple terms

Input UI:

• Select – Native browser dropdown
• Custom Select – Styled dropdown with better mobile experience
• Inline – Horizontal buttons/chips
  • Responsive – Custom select on smaller screens, switches to stacked layout on larger screens
• Stacked – Vertical list of options
  • Responsive – Custom select on smaller screens, switches to stacked layout on larger screens

Label Position – Hidden, Stacked (left/center/right), or Inline

Label – Custom label text

All Option Label – Text for the “All” option (default: “All”)

Show Count – Display post count next to each term

Show Only Top Level – For hierarchical taxonomies, show only parent terms

Show Hierarchy – Display terms in hierarchical tree structure

Hide Empty – Hide terms with no matching posts

Contextual Terms – Only show terms that exist in the current query results. When enabled, users never click a filter and get zero results.

Filter Text

Keyword search input with intelligent autocomplete.

Label Position – Hidden, Stacked (left/center/right), or Inline

Label – Custom label text (default: “Search”)

Placeholder – Placeholder text (default: “Search…”)

Search Content – When enabled, searches post content in addition to titles

Exact Phrase – When enabled, matches the exact phrase instead of individual words

Autocomplete – Intelligent suggestions as the user types. Two modes available:

• Words Mode – Suggests phrases that exist in your content. Every suggestion is guaranteed to return results. No dead ends.
• Posts Mode – Shows matching post titles as the user types. Click a suggestion to navigate directly to that post. Context-aware—only suggests posts that match currently active filters.

Autocomplete is fully ADA compliant with keyboard navigation and screen reader support built in.

Filter Order By

Sort control for query results.

Label Position – Hidden, Stacked (left/center/right), or Inline

Label – Custom label text (default: “Order by”)

Input UI:

• Select – Native browser dropdown
• Custom Select – Styled dropdown
• Inline – Horizontal buttons
• Stacked – Vertical list

Options – Customize available sort options:

• Newest to oldest
• Oldest to newest
• A → Z
• Z → A
• Add custom options for meta fields

You can add, remove, and reorder options visually in the editor. Set a default sort option.

Filter Active

Displays currently active filter selections with remove buttons.

Label Position – Hidden, Stacked (left/center/right), or Inline

Label – Custom label text (default: “Active Filters:”)

Show Clear All – Display a “Clear All” button

Clear All Label – Custom text for clear button (default: “Clear All”)

Filter Submit

Submit button for applying filters. Only needed when Auto Submit is disabled. When Auto Submit is enabled at the Filters block level, any Filter Submit block inside will be hidden automatically.

Label – Button text (default: “Apply Filters”)

Width – Set button width percentage

Supports button color, border, and typography customization.

Filter Clear

Dedicated clear-all-filters button. Works with both manual and auto-submit modes. Use this when you want a standalone clear button separate from the Filter Active block.

Label – Button text

Supports full styling controls—colors, borders, typography, width.

WooCommerce Filter Blocks

These blocks are designed specifically for filtering WooCommerce products within a Query Loop. They appear when WooCommerce is active on your site.

Filter Woo Price

Filter WooCommerce products by price. Two display modes:

• Range Slider – Dual-handle slider for setting a custom min/max price range
• Price Tiers – Predefined price brackets (e.g., Under $25, $25–$50, $50–$100, $100+)

Customizable min/max range – Set the price boundaries for the slider

Add, remove, and reorder tier labels – Define your own price brackets when using tiers mode

Responsive layout switching – Different display modes at different breakpoints

Filter Woo Rating

Filter WooCommerce products by star rating.

Display Options:

• Amazon-style star icons
• Text labels

Input UI:

• Stacked list
• Inline
• Custom dropdown
• Native select

Responsive layout switching between display modes at different breakpoints.

Filter Stock Status

Filter WooCommerce products by availability: In Stock, Out of Stock, or On Backorder.

• Single or multi-select
• Enable, disable, reorder, and relabel each status option
• Four layout options (select, custom select, inline, stacked) with responsive switching

Filter On Sale

Filter WooCommerce products currently on sale. Simple toggle control.

Display Options:

• Checkbox
• Toggle switch

Customizable label text for the toggle.

Custom Orderby Options

Register custom sort options for the Filter Orderby block using PHP filters. Options are post-type specific and appear automatically in the block editor.

Limitation: Custom sort options can be set as the default only when using inherited queries. Custom queries are limited to WordPress’s built-in orderBy values for defaults, though custom options remain available in the filter dropdown.

Basic Usage Sample

add_filter( 'groundworx/filter_orderby_options-{post_type}', function( $options ) {
    $options['random'] = array(
        'orderby' => 'rand',
    );
    return $options;
} );

Sorting by Custom Fields Sample

add_filter( 'groundworx/filter_orderby_options-product', function( $options ) {
    // Sort by price (numeric meta field)
    $options['by-price'] = array(
        'orderby'  => 'meta_value_num',
        'meta_key' => 'price',
        'order'    => 'ASC',
    );
    return $options;
} );

Multiple Sort Fields Sample

add_filter( 'groundworx/filter_orderby_options-product', function( $options ) {
    // Sort by featured status, then price, then title
    $options['featured-first'] = array(
        'meta_query' => array(
            'featured_clause' => array(
                'key'  => 'is_featured',
                'type' => 'NUMERIC',
            ),
            'price_clause' => array(
                'key'  => 'price',
                'type' => 'NUMERIC',
            ),
        ),
        'orderby' => array(
            'featured_clause' => 'DESC',
            'price_clause'    => 'ASC',
            'title'           => 'ASC',
        ),
    );
    return $options;
} );

Using Callbacks Sample

For complex sorting logic, use a callback function:

add_filter( 'groundworx/filter_orderby_options-post', function( $options ) {
    $options['trending'] = array(
        'callback' => function( $query ) {
            $query->set( 'meta_key', 'view_count' );
            $query->set( 'orderby', 'meta_value_num' );
            $query->set( 'order', 'DESC' );
            $query->set( 'date_query', array(
                array( 'after' => '1 week ago' ),
            ) );
        },
    );
    return $options;
} );

Multiple Filter Groups

You can use multiple independent filter groups on the same page. Each Filters container targets its own Query Loop. Posts in one section, tutorials in another—no conflicts.

This is useful for pages that display multiple content types, like a resources page with blog posts and documentation side by side.

Example Use Cases

Blog Archive: Filter posts by category with a text search and date sorting. Enable autocomplete so readers find articles without guessing keywords.

WooCommerce Product Catalog: Filter products by category, price range, star rating, stock status, and sale items. Combine multiple WooCommerce filter blocks for a full shop filtering experience.

Portfolio: Filter projects by type, client, or technology with alphabetical sorting.

Resource Library: Filter documents by topic, format, and date with keyword search. Use contextual terms so users only see relevant options.

Team Directory: Filter team members by department and location with alphabetical sorting.

Job Board: Filter positions by department, location, and type.

Accessibility

All filter blocks are built with full WCAG compliance. No extra configuration needed.

• Keyboard navigation throughout all interactive elements
• Screen reader support with proper ARIA patterns
• Focus management during filter updates
• Meets accessibility requirements for government, healthcare, education, and enterprise clients

This is built-in from the ground up, not retrofitted.

Styling Filters

Filter blocks inherit your theme’s form styles. Use the block toolbar and sidebar to customize:

• Typography (font size, weight, family)
• Colors (text, background)
• Spacing (padding, margin)
• Border (for submit button)

For global form styling, use theme.json:

{
  "styles": {
    "elements": {
      "button": {
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "var(--wp--preset--color--white)"
        }
      }
    }
  }
}

Next Steps

• Combine Filters with Featured Posts or Dynamic Flow for filtered carousels
• Add WooCommerce filter blocks to your product archive templates
• Experiment with different Input UI styles for Filter Terms
• Try autocomplete in Filter Text—Words mode for guaranteed results, Posts mode for direct navigation
• Use multiple filter groups on a single page for complex layouts