Developers
Shortcode
Section titled “Shortcode”[sieve]Renders a complete, self-contained filter: facets, results grid, sorting, active-filter chips and pagination. It reads the current filter state from the URL (sf_* query vars), so the initial render is server-side and shareable.
Search shortcode
Section titled “Search shortcode”[sieve_search]Renders the predictive search box on its own (see Predictive search). It is a normal search form that submits to the WooCommerce product search when JavaScript is off. Attributes:
| Attribute | Default | Notes |
|---|---|---|
placeholder |
Search products |
Placeholder of the input. |
label |
Search products |
Accessible name of the input (aria-label). |
results_label |
Product search results |
Accessible name of the suggestion list. |
button |
true |
Show the submit button. Accepts 1, true, yes, on; anything else hides it. |
button_text |
Search |
Submit button label. |
limit |
6 |
Suggestions in the dropdown, clamped to 1-20. |
min_chars |
2 |
Characters typed before suggestions load, clamped to 1-10. |
in_stock_only |
true |
Suggest only in-stock products. Same boolean parsing as button. |
The dropdown reads GET /wp-json/sieve/v1/suggest (public; parameters q, limit 1-20, in_stock_only, and scope, the other active sf_* facets, so suggestions match the grid).
The Sieve Filter block (sieve/filter) is a dynamic block that renders the same widget as the shortcode. Add it from the block inserter.
URL state
Section titled “URL state”Filter state lives in the URL so it is bookmarkable and back-button safe:
sf_<facet>- a facet’s selected values (comma-separated;min-maxfor a range).sf_q- the search query.sf_orderby- the sort order.sf_paged- the current page.
REST API
Section titled “REST API”POST /wp-json/sieve/v1/filter
Public, read-only endpoint that powers AJAX filtering. Body: { "query": { "sf_product_cat": "hoodies", "sf_orderby": "price" } }. Returns the rendered fragments (facets_html, toolbar_html, results_html, pagination_html), the result count and found. The frontend swaps these in place.
Admin endpoints (capability manage_woocommerce):
GET/POST /wp-json/sieve/v1/settings- read or save the facet configuration.GET /wp-json/sieve/v1/catalog- the auto-discovered facet sources.POST /wp-json/sieve/v1/reindex- rebuild the index.
Extension hooks
Section titled “Extension hooks”Action: sieve/booted
Section titled “Action: sieve/booted”Sieve fires an action after it boots, so an extension can register additional services in the shared container:
add_action( 'sieve/booted', function ( \Sieve\Plugin $plugin ) { // Extend the container or register your own hooks.} );Filter: sieve_settings
Section titled “Filter: sieve_settings”Filters the whole settings array every time it is read: facets, per_page, columns, appearance, layout and zero_counts. It also runs on the built-in defaults, before anything is saved, so it is the place to change the starter preset.
add_filter( 'sieve_settings', function ( array $settings ) { $settings['per_page'] = 24; return $settings;} );Filter: sieve_facets
Section titled “Filter: sieve_facets”Filters the facet list before it is rendered and resolved. Arguments: $facets (array of \Sieve\Model\Facet) and $context, an array with is_shop (bool), category_id (int, the current product category or 0) and user_roles (array of role slugs, empty for guests). Return an array of facets; anything else is ignored and the configured list is used.
// Hide the price facet from wholesale customers.add_filter( 'sieve_facets', function ( array $facets, array $context ) { if ( ! in_array( 'wholesale_customer', $context['user_roles'], true ) ) { return $facets; } return array_filter( $facets, fn ( $facet ) => ! $facet->isPrice() );}, 10, 2 );Filter: sieve_facet_catalog
Section titled “Filter: sieve_facet_catalog”Filters the sources the admin facet builder offers. Each entry is an array with source (for example tax:pa_color, price, stock), label, suggested_type and group (taxonomy, attribute or field).
// Offer a custom product taxonomy in the builder.add_filter( 'sieve_facet_catalog', function ( array $sources ) { $sources[] = [ 'source' => 'tax:product_brand', 'label' => 'Brand', 'suggested_type' => 'checkbox', 'group' => 'taxonomy', ]; return $sources;} );The indexer only stores values for product categories, tags, global pa_* attributes, price, stock, on sale and rating, so a new source shows options only if your code also indexes it.
Filter: sieve_facet_types
Section titled “Filter: sieve_facet_types”Filters the presentation types listed in the builder. Each entry is value, label and help. A type added here is only drawn if you also render it with sieve_facet_body.
add_filter( 'sieve_facet_types', function ( array $types ) { return array_values( array_filter( $types, fn ( $type ) => 'az_index' !== $type['value'] ) );} );Filter: sieve_facet_body
Section titled “Filter: sieve_facet_body”Replaces the HTML body of one facet. Arguments: $html (null), $facet (\Sieve\Model\Facet), $counts (value => dependent count), $selected (selected values) and $bounds (min/max for price sliders, otherwise null). Return a non-empty string to use your markup; return null to keep the built-in widget. Sieve still wraps your body in its collapsible facet header.
add_filter( 'sieve_facet_body', function ( $html, $facet, array $counts, array $selected ) { if ( 'stock' !== $facet->slug ) { return $html; } $out = ''; foreach ( $counts as $value => $count ) { $out .= sprintf( '<p>%s (%d)</p>', esc_html( $value ), (int) $count ); } return $out;}, 10, 4 );Filter: sieve_search_product_ids
Section titled “Filter: sieve_search_product_ids”Runs before the built-in search resolver. Arguments: $product_ids (null), $term (raw search term) and $tokens (normalised query tokens). Return an array of product IDs to replace Sieve’s own prefix and fuzzy matching, for example with an external search service; return null to keep the built-in search. The IDs are de-duplicated and cut to the resolve cap below. An empty array means “no matches”, not “no search”.
add_filter( 'sieve_search_product_ids', function ( $ids, string $term ) { return my_search_service_lookup( $term ); // array of product IDs.}, 10, 2 );Filter: sieve_search_resolve_cap
Section titled “Filter: sieve_search_resolve_cap”The maximum number of product IDs a search term can resolve to. Default 2000. Values below 1 fall back to the default. Lower it on very large catalogs if search queries get slow.
add_filter( 'sieve_search_resolve_cap', fn () => 1000 );Filter: sieve_index_batch_size
Section titled “Filter: sieve_index_batch_size”Products read and held in memory per indexing batch. Default 200. Values below 1 fall back to the default. The background backfill indexes one batch per cron run, and Rebuild index walks all batches in one request. Lower the value on a memory-tight host.
add_filter( 'sieve_index_batch_size', fn () => 50 );