Skip to content

Developers

[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.

[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.

Filter state lives in the URL so it is bookmarkable and back-button safe:

  • sf_<facet> - a facet’s selected values (comma-separated; min-max for a range).
  • sf_q - the search query.
  • sf_orderby - the sort order.
  • sf_paged - the current page.

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.

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.
} );

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;
} );

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 );

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.

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'] ) );
} );

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 );

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 );

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 );

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 );