HS Product Filters — user guide
For development preview 0.8.1-dev. Test on a staging copy before using this preview on a live store. The supported presentation is one Product Filters shortcode catalog on a WordPress page. It does not replace an existing WooCommerce archive or an Elementor product widget.
Create your first catalog
- Install the Product Filters ZIP on a site with WooCommerce active. The current package requires WordPress6.8 or later and PHP8.2 or later; the verified platform combinations and limits are listed below.
- Open HookSpark → Product Filters and create a set. Give it a name your customers will understand: the catalog uses it as a heading.
- Choose the product category that defines the collection, or use the whole catalog. Under Subcategories, choose Include subcategories (the default for new and existing sets) or Direct category assignments only. This choice applies both to the catalog boundary and to category filters. The boundary remains in place when a visitor resets their selections. A product explicitly assigned to both parent and child categories can match either direct assignment; it is counted only once.
- Select up to eight filter sources. Available sources are categories, tags, WooCommerce brands when registered, and global product attributes. Create missing global attributes in WooCommerce first; product-specific custom attributes are not filter sources in this preview.
- Use the preview to try combinations. It shows at most six matching product cards; its total counts all matches. Long value lists are shortened to30 values in the editor preview.
- Save the set and enable it when ready. Copy its generated shortcode into a Shortcode block on a WordPress page. Use one grid on that page. Publish through the normal WordPress page workflow.
- Open the page as a logged-out visitor, try filtering and sorting, then test on a phone.
A typical shortcode is [hs_product_filters set="YOUR_SET_ID"]. Copy the actual value from the editor; a set name is not its ID. For an explicitly bound SEO landing, follow the separate SEO guide.
How matching works
Several values in the same filter are alternatives: Plum or Lavender. Different filters are combined: Plum and Small. A variable product must have one eligible variation that satisfies all selected attributes, price and availability together. A Plum/Small variation and a Lavender/Medium variation do not make the parent match Plum/Medium.
A variation configured with Any value can match the values assigned to its parent for that attribute. Category ancestors are included when the set includes subcategories. The preview supports simple and variable products; it does not currently evaluate grouped, external or custom product types.
The catalog includes published, publicly visible, purchasable products with a price. Password-protected products are excluded. WooCommerce's hide-out-of-stock setting is respected. When that setting hides an item, selecting Out of stock does not reveal it.
Each parent product appears once. Its card uses the image, price and link of the cheapest matching variation. If that variation has no image, WooCommerce uses the parent product image; if neither has an image, it shows its standard placeholder. The same fallback applies to the admin preview. The admin preview also explains that all selected filters must match the same variation or simple product, identifies the cheapest matching variant, and lists its attribute values next to its ID. These diagnostic details are not added to the public product cards. A visitor follows that link to the normal WooCommerce product page to choose or purchase the item; filtering does not change cart quantities, stock or catalog prices.
Counts, price and sorting
The number beside a value counts distinct parent products. It considers the other filter groups while ignoring the current group, so shoppers can see alternative choices. Adding several values from one group will not count a parent repeatedly.
Minimum and maximum price are inclusive and use the displayed WooCommerce price with the configured currency precision, from zero to six decimal places. Use a decimal point or comma for fractional amounts, without thousands separators. An inverted range is rejected. Invalid prices keep their entered values and show a message beside the field, with a linked error summary. After applying, focus moves to the first invalid price; on mobile the filter panel opens for correction. Tax and currency integrations still need testing in their actual store context.
Availability choices are Any availability, In stock, On backorder and Out of stock. Sorting supports catalog order, price ascending, price descending and newest first. The public grid shows twelve products per page.
Change or clear selections
With JavaScript, controls update the product grid without a full page reload. The Apply filters button also works as ordinary page navigation. The URL records applied selections, and browser Back/Forward restores them. When updates overlap, an older response cannot replace a newer selection.
Selected values appear above the grid as removable chips. Remove one to keep the other selections; the catalog returns to page one. Reset restores the original catalog or the single filter assigned to an SEO landing. On screens up to650px wide, the Filter products button opens a modal panel. Selections remain a draft until Apply filters is pressed. Cancel changes, Escape or closing the backdrop restores the applied selections and returns focus to the opening button. Moving to desktop width also cancels the draft. Counts reflect the applied state and update after applying; there is no live draft result-count preview. Without JavaScript, the ordinary expandable filter form remains usable.
A combination with no matches shows recovery controls. Remove a chip, widen the price range or reset. An invalid or empty filtered landing returns404 and noindex; this does not mean that the original WordPress page was deleted. If an AJAX request fails, the previous result remains visible with an error message and a Retry update button. Retry repeats the failed operation, including removal of a filter chip. A newer request supersedes older responses and errors.
SEO and readable URLs
Create a normal WordPress page with a readable slug for a useful single-filter collection, then bind that page in SEO landing pages. You control its title, description and indexing switch. Saving the binding does not publish the page or override WordPress's site visibility.
Only an explicitly enabled, exact, nonempty landing can be eligible for indexing. Additional filters, price bounds, sorting and pagination remain noindex and do not inherit the editorial description. The plugin does not generate thousands of readable paths for arbitrary combinations. See the SEO setup and recovery guide before enabling indexing.
Manage sets safely
Search the set list by name. Copying a set creates an inactive copy so it can be adjusted before use. Moving a set to the trash requires its name; restoring it leaves it inactive. A disabled, missing or trashed set shows an unavailable message and a link to the normal shop instead of exposing its former catalog.
Unsaved changes trigger a navigation warning in the editor. Rejected saves retain the entered values and identify the first invalid field. If someone saves another revision first, reload and compare the latest configuration before retrying; do not assume that your stale form overwrote their work.
Recover a previous configuration
Open a saved set and find Previous configurations below the preview. The last ten changed configurations are kept for that set. Choose Load revision … as a draft to inspect the previous name, source selection and category. This does not change the saved catalog. The recovered draft is inactive; review it and save when ready, then enable it deliberately if needed.
Saving the recovered draft preserves the configuration it replaces, so you can recover that version too. Concurrent saves are rejected. If an old category or filter source no longer exists, the editor explains the problem and shows the current configuration instead. SEO landing settings and other filter sets are unchanged. Duplicate sets start with their own empty history; moving a set to Trash keeps its history. Versions before this feature was installed cannot be reconstructed.
The preview accepts at most100 sets including trashed sets and100 SEO bindings. These are implementation limits, not paid plan tiers. Keep unused test copies out of production configuration.
Demo and compatibility
The Product Filters demo uses synthetic studio products and original illustration/product images. A personal admin demo lasts one hour and has an isolated WordPress subsite and restricted account. It permits filter settings and the supplied SEO pages; it does not grant general page publication, uploads, plugin installation or network management. Demo pages remain noindex. Personal session URLs expire.
Verified combinations: WordPress 6.8 with WooCommerce 10.6.0, and WordPress 7.1.1 with WooCommerce 11.1.0, both on PHP 8.2.29. The minimum-platform checks use the installed distribution ZIP and cover filtering, SEO, lifecycle data retention and a frontend browser smoke test. This is evidence for those environments, not certification of every version above the package minimums. Native single-page shortcode filtering, SEO policy, variant matching and the supplied multisite demo have automated checks. Yoast SEO 28.5 and Rank Math 1.0.278 passed metadata, robots, canonical and actual XML sitemap HTTP checks on WordPress 7.1.1, WooCommerce 11.1.0 and PHP 8.2.29. Yoast 27.9 and Rank Math 1.0.278 also passed on the minimum platform. Yoast 28.5 requires WordPress 6.9 or later and was not forced onto 6.8. Other provider versions remain unverified. Multiple grids, archive/page-builder adapters, multilingual integrations and other multicurrency providers remain outside the verified preview.
Large catalogs still require further optimization. The current engine scans the eligible catalog on each evaluation; batching reduces database queries but does not eliminate that work. A50,000-simple-product local measurement took about10seconds. Do not use that measurement as a hosting guarantee or a claim of large-store readiness.
Troubleshooting
| Symptom | What to check |
|---|---|
| Catalog unavailable | Confirm the shortcode ID, saved set and enabled status; restore then enable a trashed set if appropriate. |
| An attribute is absent | Use a global WooCommerce attribute, assign its terms to products and select it in the set. |
| Expected variation is absent | Check that the same variation satisfies all dimensions, has a price and is available under store visibility settings. |
| An old URL is rejected | The referenced source or term may have been removed; update the binding and relevant links. |
| SEO title is generic | An additional filter, sort or page number may make the URL a browsing combination rather than the exact landing. |
| Noindex remains after enabling the landing | Check WordPress site visibility and existing SEO-plugin restrictions; the Product Filters switch cannot remove them. |
| Preview is slow | Measure the actual catalog and installed extensions; the large-catalog index is still in development. |
| Save reports a concurrent change | Reload the latest configuration, compare changes, then save deliberately. |
Disabling the plugin retains its configuration and does not delete WooCommerce products or native pages. Its shortcode output requires the active plugin; remove or replace the shortcode if retiring a catalog page. There is no automatic deletion of merchant products on plugin removal. Keep a normal site backup before upgrades or cleanup. Configuration retention across deactivate/reactivate, upgrade and uninstall/reinstall was verified on the minimum WordPress 6.8 / WooCommerce 10.6.0 pair for 0.6.1-dev. This does not certify every third-party combination.
Match your theme
The filter catalog inherits its surrounding font and text color. Controls and cards use WordPress base/contrast palette values when present. Styles target HookSpark classes; the shortcode owns its result grid and does not restyle the theme shop grid. Native archive and page-builder grid adapters remain unverified.
For a local color override, scope custom CSS to the catalog or its containing section. For example, .my-catalog { --hs-pf-accent: #006446; --hs-pf-on-accent: #ffffff; } changes the accent pair only within that container. Additional optional properties are --hs-pf-surface, --hs-pf-border and --hs-pf-soft. Choose readable foreground/background pairs and check both desktop and mobile after customization.
Review pages before removing a set
In the filter-set list, choose Review affected pages before Move to Trash. The read-only list combines explicit shortcodes in native pages with saved SEO landing bindings, removes duplicates and links to page editors when your account can edit them. Drafts are included; unreadable pages and trashed pages are not shown. Template files and page-builder storage must be reviewed separately. The review runs only when requested.
Moving a set to Trash requires its exact saved name. It does not delete the pages or their editorial content. Their unavailable catalog offers a link to the shop. Restore the set as inactive, review its settings, then enable it again when ready.
Tested currency switching
FOX Currency Switcher1.5.4 was checked on WordPress6.8/WooCommerce10.6.0/PHP8.2.29 with USD/EUR, fixed test rates, automatic rate updates disabled, default transient storage and an uncached shortcode page. Native prices, currency labels and min/max comparisons agree in this configuration. The provider selector reloads the page and clears selections made by AJAX; choose the currency first, then apply filters. No automatic conversion of an already-entered filter amount is promised.
Cookie storage showed a delayed update and is not supported by this acceptance result. GeoIP, product-specific fixed prices, cached storefronts, checkout/payment conversion and other providers have not been verified. FOX is optional and is not included in the Product Filters ZIP.