One form, two ways of being used
The search field is an ordinary HTML form. Pressing Enter submits it and the shopper lands on a product search results page. That works before any script has loaded, with JavaScript turned off, and on a page served from a cache.
A small script (no jQuery, nothing loaded from another site) then adds the live suggestions on top. If the script fails, the form still works.

Free edition: the flow
- The shopper types. The script waits until they pause for 250 ms.
- If they have typed fewer than two characters, nothing happens.
- Otherwise the script calls
GET /wp-json/gatemi-ps-free/v1/suggest?q=…. - The route runs WordPress' own product search (
WP_Querywiths) over published products — the product title, excerpt and content — and returns at most eight. - Each suggestion carries the product's name, link, thumbnail and its price as the shop shows it, as plain text. A variable product is one line with its price range.
- Clicking anywhere outside the form closes the list.
Submitting the form goes to /?s=…&post_type=product, WordPress' own product search page, rendered by your theme.
Hidden products stay hidden
A product whose Catalog visibility is set to Shop only or Hidden carries WooCommerce's exclude-from-search term. The suggestion route excludes that term, the same rule WooCommerce's own search follows. The route is public — anybody can call it — so a product you hid from search must not appear there by name and price.
What the free edition does not search
WordPress' product search does not look at SKUs, attributes, brands or variation options. The free edition searches what WordPress searches, and there is no setting to change that. Searching those fields needs an index, which is what the full edition builds.
Full edition: the index
WooCommerce's built-in search asks the database to scan every product's text for a substring on every search. It gets slower as the catalog grows and cannot rank results.
The full edition breaks every product into words once, when it is indexed, and stores each word with a weight. A search is then a lookup on those words and a sum — its cost depends on how many products contain the words typed, not on how many products you have.
What a word is worth
A word in a product's name says far more about it than the same word deep in a description. The default weights are:
| Field | Weight |
|---|---|
| Title | 20 |
| SKU | 20 |
| Short description | 8 |
| Categories, tags, brands | 6 |
| Attributes | 4 |
| Variation SKUs and options | 4 |
| Description | 2 |
Words shorter than two characters and common stopwords are skipped.
Indexing never slows the shop down
- A product is saved, imported, or its stock changes.
- One row is written to a queue. Nothing is indexed in that request.
- A background worker runs every minute through WordPress cron. It takes a lock, indexes up to 50 products, and stops after about 20 seconds.
- Each product's indexed content is fingerprinted. Re-indexing an unchanged product writes nothing.
A bulk price import or a stock sync therefore adds queue rows, not seconds to the storefront. A full rebuild walks through product IDs in batches; searches keep working against the index as it stands.
Searching
- Every word must match. If nothing matches all of them, the plugin falls back to products that match some of them, so a search that was close never returns an empty page.
- Typo correction: a word of four or more lowercase letters that matches nothing is replaced by the closest word your products actually contain, and the page tells the shopper what it searched for instead. Candidates must share the first two letters (or have them swapped).
- The plugin takes over the product query your theme already runs, so your templates, pagination and layout stay as they are. WooCommerce's visibility rules still apply on the results page.
- The search term uses its own URL argument,
gmps. Ordinary?s=product searches are also answered from the index.
Instant suggestions
The suggestion route gatemi-ps/v1/suggest answers from the index, caches the answer, and returns six suggestions by default (each field can ask for up to 20, and the site-wide ceiling defaults to 10). It is an ordinary cacheable GET with nothing visitor-specific in it.
The candidates the index finds are run back through WP_Query with WooCommerce's exclude-from-search visibility term, the same rule as the free edition, and each one is then judged the way a search judges it: a product set to Shop only or Hidden is never suggested, and one set to Search results only is. (A REST request is never a search page as far as WooCommerce knows, so its ordinary visibility check reads those two the wrong way round; the route does not rely on it.)
Full edition: filters
The filters are category, tag, brand, attribute, price, rating, on sale, in stock, an active-filter summary with a reset, and a product grid.
- Every filter is a link. Choosing one goes to a real URL such as
?gmpsf=shoes&gmpss=1. With JavaScript, the script fetches that same URL and swaps the product grid and filters in place; without it, the page reloads. There is one rendering path, so the two cannot disagree, and a page cache or CDN can serve every filtered view. - Price, rating, sale and stock come from WooCommerce's own product lookup table through one join, not from meta queries.
- Counts beside each choice are cached and bounded. Above a ceiling the filters show without numbers rather than load the database.
Automatic placement
With both shop-page settings on, the search field and the filters appear on the shop page and on category, tag and brand archives through woocommerce_before_shop_loop. Attribute filters appear for attributes you enabled archives for. On a page that already contains one of the plugin's blocks or shortcodes — including the shop page's own content — the automatic panel steps aside, so your own layout wins.
Free edition: the same check reads the page being displayed — the shop page's content on the shop archive, the page itself on a single page or post. A product listed on an archive whose description happens to quote the shortcode does not count.
Full edition: search reports
Under WooCommerce → Search Reports (with Record what shoppers search for on):
- a summary: searches, distinct terms, and how many found nothing;
- Most popular searches — worth checking each lands on something good;
- Searches that found nothing — each is a shopper who wanted something you did not show them.
Both tables export to CSV. Log rows older than 180 days are pruned daily.
