bricks_add_query_filter

Phase 4IntermediateComplexity: 6/10
Add a filter UI element (checkbox, range, select) to a page

Overview

Add a query filter element to a page that lets users filter query loop results interactively. Supports 8 filter types: checkbox, datepicker, radio, range slider, search, select dropdown, submit button, and active filters display.

Each filter element connects to a specific query loop via the target_query_id parameter, and filters results based on taxonomy terms, custom fields, post meta, or WordPress fields. Filters update the query results via AJAX or page reload.

Key Features

8 Filter Types
Checkbox, radio, select, range slider, search, datepicker, submit button, and active filters — covering all common filtering patterns.
Multiple Data Sources
Filter by taxonomy terms, custom fields (post_meta), or WordPress fields (post_date, post_author). Each source generates appropriate filter options.
AJAX or Submit
Configure filters to apply immediately on change (AJAX) or require a submit button click. AJAX provides instant feedback while submit reduces server load.
Post Count Display
Optionally show the number of matching posts next to each filter option, and hide options with zero results.

When to Use

Adding category/tag filters to a blog or portfolio grid
Creating price range sliders for product listings
Adding search input fields that filter query loop results
Building faceted navigation with multiple filter types (checkbox + range + search)
Displaying active filter pills that users can click to remove
Prerequisites
A page with an existing query loop element (configured via bricks_set_query_loop)
enableQueryFilters must be enabled in Bricks global settings (via bricks_update_site_settings)
For taxonomy filters: the taxonomy must exist with terms assigned to posts
For custom field filters: posts must have the meta key populated

When NOT to Use

Filtering data that does not come from a Bricks query loop — filters only work with query loops
You need complex multi-step filtering logic — use a custom PHP query handler instead
The page has no query loops to filter

Parameters

11 Total Parameters3 Required8 Optional
page_idnumberREQUIRED
Page (post) ID to add the filter to.
parent_idstringoptional
Parent element ID to nest the filter inside.
filter_typestringREQUIRED
Type of filter element to create.
Values: filter-checkbox, filter-datepicker, filter-radio, filter-range, filter-search, filter-select, filter-submit, filter-active-filters
target_query_idstringREQUIRED
Element ID of the query loop this filter targets. The filter will modify this query's results.
settings.filterSourcestringoptional
Data source for generating filter options.
Values: taxonomy, custom_field, post_meta, wp_field
settings.filterTaxonomystringoptional
[taxonomy source] Taxonomy slug to filter by (e.g., "category", "product_cat").
settings.filterMetaKeystringoptional
[custom_field/post_meta source] Meta key to filter by.
settings.filterApplyOnstringoptional
When to apply the filter: immediately on change (AJAX) or on submit button click.
Default: change Values: change, submit
settings.filterShowCountbooleanoptional
Show the post count next to each filter option.
settings.filterHideEmptybooleanoptional
Hide filter options that have no matching results.
content_areastringoptional
Content area for the filter element.
Default: content Values: content, header, footer

Code Examples


Warning: Undefined array key "example_output" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 12

Add category filter checkboxes to a blog grid

Create checkbox filters that let users filter blog posts by category, with post counts and AJAX updates.

JSON
bricks_add_query_filter({
  page_id: 45,
  parent_id: "filters-container",
  filter_type: "filter-checkbox",
  target_query_id: "blog-loop-item",
  settings: {
    filterSource: "taxonomy",
    filterTaxonomy: "category",
    filterLabel: "Categories",
    filterShowCount: true,
    filterHideEmpty: true,
    filterApplyOn: "change"
  }
});

Common Mistakes


Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49
Bricks query filters require enableQueryFilters to be enabled in global settings. Without this, filter elements will not function. Use bricks_update_site_settings to enable it.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49
The target_query_id must be the element ID of the element with hasLoop (the loop item), not the grid parent or the section. This is the same element you configured with bricks_set_query_loop.

Tips & Warnings

Tips & Warnings

Enable query filters first via bricks_update_site_settings({ enableQueryFilters: true }) before adding any filter elements.

Run bricks_reindex_filters after bulk content changes to ensure filter counts are accurate.

Combine multiple filter types for faceted navigation — e.g., checkbox for categories, range for price, search for text. All targeting the same query loop.

Return Values

FieldTypeDescription
successbooleanWhether the filter element was successfully created.
element_idstringThe Bricks element ID of the created filter.
filter_typestringThe type of filter that was created.

Related Tools

Technical Details

Tool ID
bricks_add_query_filter
API Endpoint
/bricks-mcp/v1/pages/{page_id}/elements/{parent_id}/children
HTTP Method
POST
Namespace
content-queries
Source File
content/filters.ts
Version
1.0
Min Bricks Version
2.0
Requires Auth
Yes

Changelog

v1.0
Initial release with 8 filter types
20250101