Frequently Asked Questions

The questions we’re asked most often about Super Speedy Filters, drawn from five years of support. For error messages and things that have stopped working, see the Troubleshooting guide, or ask us on Discord.

How do I set up a filter? (the basics)

Filters are added as widgets. Install the free Classic Widgets plugin (the block widget screen is buggy for this), then go to Appearance > Widgets – not the Customizer. Add a Super Speedy Filter widget, choose the ‘product’ post type, and hit Save – the rest of the options only appear after you save and reload. Then choose the taxonomy (product category, pa_brand, pa_color, etc.), a container type (e.g. Popout) and a display type (e.g. List), and save again. Add one widget per attribute or taxonomy you want to filter on. The supporting tables must have finished building first (the Advanced tab shows the build status), or the widgets show nothing. It’s a complex plugin, so set it up on a staging site first.

How do I add filters in Elementor, Divi, Bricks or an FSE theme?

There’s no separate builder block. Add the widgets under Appearance > Widgets, then drop the [ssf_widgets] shortcode (or the matching shortcode block/area) into your archive template. The builder’s product loop must be set to “Current Query”, not “Latest Products”, or the filters can’t act on it. See the page-builder section of the Troubleshooting guide for the per-builder specifics. To place inline filters on a page where a product is in scope (like a product page), use [ssf_inline_filters].

Do I need Redis or an object cache?

Yes – Super Speedy Filters uses an object cache as its progressive cache, and without one every archive page recalculates all the counts from scratch and is slow. Install Redis Object Cache by Till Krüss, or Memcached, or the free Docket Cache plugin if you can’t run Redis. Keep the cache local to the server (not a remote/managed Redis), and give Redis a memory limit and eviction policy so it can’t fill your RAM (maxmemory + maxmemory-policy allkeys-lfu). The first load of an archive builds the counts and is slow; every load after is fast until the cache clears.

Is Scalability Pro required?

No. Super Speedy Filters lists Scalability Pro under WordPress’s “Required Plugins” panel, but the Type column says Recommended – it’s safe to dismiss the prompt. They complement each other (Scalability Pro speeds up the rest of your queries) but Super Speedy Filters works on its own.

Does it filter custom post types or non-WooCommerce content?

Not yet – currently it filters WooCommerce products only. Custom taxonomies on products (a “car selector”, a brand, etc.) do work; it’s non-product post types (blog posts, ACF-driven CPTs) that aren’t supported. A custom-post-type version is in development but not released. If you select the “post” post type today you’ll get an empty widget.

Why are attributes missing from the widgets when I’ve set them on my products?

Work through these:

• Only global attributes work. Per-product (custom) attributes are stored in a serialized blob that can’t be queried efficiently – convert them to global attributes (Products > Attributes).
• Are the products published? Draft products don’t count.
• Manual sorting enabled but not configured. If you turned on “allow manual sorting” but never set a manual order for the attribute’s terms, they won’t appear – either turn it off, or set a custom order under Products > Attributes > Configure Terms.
• “Check stock levels” on with no stock. If you enabled the stock-check option, products need stock to appear – add stock or turn the option off.
• Cache. If you imported terms straight into the database, flush the widget/object cache.

Why do the product counts in the sidebar look wrong?

Usually they’re right. If a widget is set to Respect Filters, its counts reflect whatever filters are active – so with colour set to “white”, only categories containing white products show, with counts to match. And a product placed in two sibling categories (say Dog Toys and Dog Training, both under Dogs) is legitimately counted in each. If the counts are genuinely stale after an import or migration, rebuild the tables (see the next question). See the Troubleshooting guide for the full rebuild steps.

When should I rebuild the Super Speedy Filters tables?

Super Speedy Filters maintains its supporting tables automatically, but you should rebuild them if you’ve renamed term slugs, renamed a taxonomy qualifier (e.g. the /brand/ in /brand/adidas/), run an import with do_action calls switched off, bulk-updated via SQL, or migrated the site. The quickest way is the WP-CLI command wp ssf rebuild; there’s also a Rebuild button on the Advanced tab. Full details, including automating it after WP All Import, are in the Troubleshooting guide.

How do I get pretty attribute URLs like /brand/adidas/ instead of ?pa_brand=adidas?

Edit the attribute under Products > Attributes > [attribute] > Edit and tick “Enable Archives”. Then go to Settings > Super Speedy Filters > URL Structure, check the URL order (you can optionally remove the term qualifier), Save, and then Settings > Permalinks > Save. Pretty archive URLs are indexable; the ?pa_x= query-string versions are deliberately non-indexable.

How do I show only the child categories of the current category?

Use the Children display option on a hierarchical taxonomy, and set the top-term id to the parent. A common pattern is to run two category widgets: a top-level one set to “ignore other filters” (to switch shop areas) and a children one set to “respect other filters”. A “Children” filter is intentionally blank until a parent category is selected.

How does the price / range filter work? Can it auto-detect min and max?

It doesn’t auto-calculate min and max from the current category – scanning the postmeta table for that on every load is too slow. Instead you configure it: for a slider, add one min and one max; for Amazon-style text-link ranges (which also work better on mobile) add several min/max pairs like €0-€10, €10-€25, €25-€50, €100+; or tick the option to show just two numeric entry boxes and add no ranges. A slider needs a numeric step value or you’ll get a noUiSlider: 'step' is not numeric error. For performance, set the widget’s advanced option to hide the price filter until a category is selected.

How do I create a WooCommerce rating filter?

Use a Custom Postmeta Range filter:

1. Create a Super Speedy Postmeta Range filter.
2. Use meta_key _wc_average_rating (include the leading underscore).
3. Use the Text Links display option.
4. Add 5 ranges: 4 to 5, then 3 to 4, and so on.
5. In each range’s text box, paste the star HTML from your site (5 stars, 4 stars, etc.), or choose an image per rating.

If HTML stars are fiddly, paste these as text instead: ★★★★★ / ★★★★ / ★★★ / ★★ / ★.

Can I filter by an ACF field or other custom postmeta?

Filtering works best on taxonomies and attributes, because those give fast, accurate counts. Postmeta doesn’t – so the best approach is to convert the value into a global attribute or taxonomy (you can keep the postmeta too, for the product page). If you must filter on raw meta, you can define the meta keys in wp-config.php and rebuild:

define('SSF_META_KEYS', array('author', 'second_key'));

Then run wp ssf rebuild; the keys appear at the bottom of the Taxonomy dropdown in the widget (only if data exists). Use the real meta_key – for ACF that’s the field name, not the field_xxxx key (verify with SELECT * from wp_postmeta where meta_key = 'x' LIMIT 10;). Serialized/array values aren’t supported; deserialize to a plain string or migrate to a taxonomy.

How do I set colour swatches, per-term images, or colours programmatically?

For a colour swatch, add the widget, choose the colour attribute, choose the Colour (or “Colour col2”) display type and Save – a colour selector then appears next to each option. For a custom image per term, set a Thumbnail under Products > Attributes > [attribute] > Edit Terms. If you have thousands of colours mapped in a file, set the hex programmatically with our filter (note we use the American spelling color):

add_filter('ssf_change_color_hex', 'override_ssf_color_hex', 10, 3);
function override_ssf_color_hex($colorhex, $term_id, $taxonomy) {
	// change your colours here based on term_id and taxonomy
	return $colourhex;
}

You get the hex you set in our interface (empty if unset), plus the $term_id and $taxonomy (e.g. pa_color). For a split “multicolour” swatch, give the term a unique hex and target it with a CSS gradient.

How do I make my filters look like my old plugin’s? (CSS classes)

Add a CSS class to the widget (there’s a CSS Class field in the widget settings). If you’re migrating from another filter plugin and want to keep the same look, the classes commonly used are:

woocommerce widget_layered_nav widget_product_categories

How do I change the look of the product counts?

Style them with CSS. To change the count colour and background:

.woocommerce .widget_awd_fast_category_widget ul li span.count, .woocommerce .widget_awd_fast_attribute_widget ul li span.count {
font-weight: normal;
font-size:12px;
color:#aaa;
background-color:white;
}

Counts are wrapped in (brackets) by default. To remove them:

.awdff span.count:before {
content:"";
}
.awdff span.count:after {
content:"";
}

To cap a widget’s height and add a scrollbar: .fww-widget-content { max-height:400px; overflow-y:auto; } (or max-height:none; to remove a cap).

Which multilingual plugin should I use?

Polylang or TranslatePress are recommended – enable “Polylang support” in the SSF Advanced/beta options. WPML works but is slow in general and isn’t our first choice (it uses nested subquery counts that don’t scale). Loco Translate is completely fine for translating interface text. GTranslate is not compatible (selecting a filter drops the /en/ language segment). Note: with Polylang, the on-sale/stock filter currently returns products of all languages on non-default languages.

Does it work with multi-vendor stores (WCFM, Dokan, MarketKing)?

Yes – add the multivendor filter, which filters on the product’s author id. It works out of the box with WCFM and Dokan, and with any plugin (such as MarketKing) that registers vendors as post authors.

How should I configure the SEO and indexing settings?

On the SEO & Indexing tab, start conservative and relax over time: set the max indexable terms and taxonomies low (e.g. 1 each to begin), and set a minimum products-for-indexing (e.g. 10) so thin single-product pages aren’t indexed. The URL Structure tab holds per-taxonomy maximums. There’s a live indexable-pages count – aim low. We deliberately make filter links non-crawlable for bots; forcing crawlability just invites bot overload (the “100” PageSpeed score for crawlable links is meaningless here). For custom landing pages (“Corsair Power Supplies” with their own title, H1 and meta description), use the SEO Overrides tab – just enable the matching On-Page SEO features on the SEO & Indexing tab and the Overrides tab’s own enable checkbox.

How do I keep filters correct when I import or bulk-update products?

For WP All Import, leave “Increase speed by disabling do_action calls” disabled so the tables self-maintain (no rebuild needed), and set “Disable WooCommerce widget code” to the remove option to skip WooCommerce’s slow attribute-lookup build. If you do disable do_action calls, run wp ssf rebuild afterwards (or call ssf_update_object_ancestors_post($post_id); per row). If you update products directly via SQL, after writing the data run:

wp taxonomy list --field=name | xargs wp term recount
wp wc tool run regenerate_product_attributes_lookup_table --user=$user
wp wc tool run regenerate_product_lookup_tables --user=$user
wp ssf rebuild

(Our Super Speedy Imports plugin gives a SQL-first import interface that handles all of this – around 30,000 attribute updates in about 5 minutes.)

Which WooCommerce lookup tables can I empty once SSF is running?

Super Speedy Filters replaces WooCommerce’s lookup tables with its own object-ancestors table. Once you’ve disabled the Woo attribute-lookup tables (in WooCommerce and in SSF), you can truncate them – back up and test on a clone first, as other plugins might read them:

truncate table wp_wc_category_lookup;
truncate table wp_wc_product_attributes_lookup;
truncate table wp_wc_product_meta_lookup;

Can I group attribute values (e.g. dark-blue and light-blue into “blue”)?

Yes – create a second attribute (e.g. “colour group”) and build the filter on that. One caveat: on variable products the grouped attribute lives on the parent, so filtering by the group won’t swap to the matching variation image.

Is there a PHP API for reading the active filters?

Yes, via the FWWLink class – but it must run inside a hook that fires after the URL is parsed (e.g. woocommerce_before_main_content, init or plugins_loaded), never at the top level of functions.php, or it returns blank or white-screens. To read the active filters:

$pm = new FWWLink('', '');
print_r($pm->getfilters());   // e.g. [product_cat] => 2064 [pa_gender] => 2126
if ($pm->getOnSale()) { /* on the on-sale archive */ }

There are also ssf_archive_title and ssf_archive_html filters, and a ssf_widget_query_filter hook to add a SQL condition to the widget counts, e.g. add_filter('ssf_widget_query_filter', function(){ return ' AND p.ID in (1,2,3) '; });. To hide a filter on specific categories, use the free Widget Context plugin, or the widget_display_callback filter (widget id_base ssf_tax_widget).

Which wp-config.php constants does Super Speedy Filters support?

These optional constants (all defined in the plugin’s defines.php) tune behaviour – add them to wp-config.php above the “stop editing” line. The most useful:

• define('SSF_OPTIMISE_TAX_QUERIES', true); – replaces slow term-relationship joins with the fast object-ancestors table.
• define('SSF_SHOW_SINGLE_VARIATIONS', array('pa_color')); – show individual variations (e.g. per colour) as their own products in the archive. List only attributes actually used for variations. When choosing the widget post type, always pick ‘product’, never ‘product_variation’.
• define('SSF_META_KEYS', array('mykey')); – expose raw postmeta keys as filters (then run wp ssf rebuild).
• define('SSF_DISPLAY_FILTERED_CATS_ON_NON_CAT_PAGES', true); – allow category filtering on the shop page and roll subcategory products up to the parent.
• define('SSF_REMOVE_DEFAULT_SORT_ORDER', true); – drop the ORDER BY on archives when no ?orderby is set.
• define('SSF_MAKE_FILTERS_BE_FILTERED_BY_SEARCH', true); – make filter lists/counts respect the search term (beta; can be slow on broad searches).
• define('SSF_REMOVE_SHOP_FROM_BREADCRUMBS', true); – drop the Shop link from breadcrumbs.

Got an error rather than a question? See the Troubleshooting guide, or ask on Discord.