Performance Troubleshooting

If search or filters feel slow on your storefront, this guide helps you diagnose the root cause and fix it.

Diagnosing Slow Search

Step 1: Measure Actual Response Times

Open browser DevTools (F12) and go to the Network tab. Perform a search on your storefront and look for the request to /apps/search-filter/api/search/products.

Response Time	Assessment
Under 50ms	Normal -- this is expected performance
50-200ms	Slightly elevated -- check backend health
200-500ms	Slow -- likely a backend or network issue
Over 500ms	Very slow -- immediate investigation needed

Step 2: Identify the Bottleneck

The response time breaks down into these components:

Total time = DNS + TLS + Shopify App Proxy routing + Backend processing + Response transfer

DNS + TLS: Usually under 20ms for repeat requests. If consistently high, the issue is network-level
Shopify App Proxy: Adds 10-30ms of routing overhead. This is unavoidable but consistent
Backend processing: The search query itself. Check the X-Response-Time header if available
Response transfer: Depends on result count and payload size

Step 3: Check Backend Health

In the app dashboard, go to Analytics > Performance to see:

Average response time trend
P95 response time
Error rate
Request volume

If response times have recently increased, it may be due to:

A large catalog re-index in progress
Increased traffic on your store
Backend infrastructure issues

Diagnosing Slow Filters

Filters Take Long to Appear

If the filter sidebar takes more than 1-2 seconds to appear on collection pages:

Check CSS loading -- The filter CSS should load synchronously. In DevTools Network tab, verify that ssf-critical-layout.css loads within the initial page request waterfall
Check JS execution -- Look for search-filter.js in the Network tab. It should load with defer and execute after DOM ready
Check for JS errors -- Look in the Console tab for any [SSF] error messages

Filters Update Slowly After Selection

When a shopper selects a filter option, the product grid should update within 200ms:

Check the network request for the filtered search query
If the request itself is fast but the grid update is slow, the issue may be in your theme's product card rendering
Large product card images (unoptimized) can slow down grid re-rendering

Common Performance Issues

Issue: High CLS (Cumulative Layout Shift)

Symptoms: The page content shifts visibly when filters load.

Cause: The CLS guard CSS may not be loading early enough.

Fix:

Ensure the Theme App Extension embed is enabled (not a custom code integration)
Check that no custom CSS overrides the .ssf-loading class behavior
Verify that ssf-critical-layout.css is loading synchronously

Issue: Search Dropdown Appears Slowly

Symptoms: User types but the dropdown takes 500ms+ to appear.

Causes and fixes:

High debounce setting -- Check Search > Configuration and reduce debounce from 500ms to 150ms
Slow network -- The first request may be slow due to DNS resolution; subsequent requests are faster
Widget config fetch -- The first load fetches widget config asynchronously; if this is slow, default settings are used

Issue: Product Images Load Slowly in Search Results

Symptoms: Search results appear quickly but product thumbnails are slow to load.

Fix: This is not a FilterIQ issue -- it depends on your product image sizes. Shopify automatically serves images through their CDN with appropriate sizing, but very large source images may still be slow. Consider:

Using Shopify's image optimization features
Ensuring product images are under 4472 x 4472 pixels

Issue: Mobile Drawer is Laggy

Symptoms: The filter drawer animation stutters on mobile devices.

Causes and fixes:

Too many filter options -- Filters with 100+ options can cause rendering lag. Enable "Show search within filter" to paginate options
Heavy product cards -- Simplify product card markup if possible
Old devices -- On very old devices (iPhone 6, etc.), reduce the number of visible filters

Performance Monitoring

Built-in Monitoring

The app tracks these metrics automatically:

Search response times (average and P95)
Filter interaction latency
CLS measurements (via ssf-cls-telemetry.js)
Error rates

View these in Analytics > Performance.

External Monitoring

For comprehensive performance monitoring, use:

Google Lighthouse -- Run from DevTools or web.dev/measure
Google PageSpeed Insights -- For field data from real users
Shopify Theme Inspector -- For Liquid rendering performance

When to Contact Support

Contact support@filteriq.app if:

Search response times consistently exceed 200ms
CLS measurements are above 0.1 on collection pages
Filter interactions have a noticeable delay (500ms+)
You see [SSF] error messages in the browser console

Include the following in your support request:

Your store URL
Your theme name
A screenshot of the Network tab showing the slow request
The browser Console output filtered to [SSF] messages