Theme App Extension

FilterIQ uses Shopify's Theme App Extension system to add search and filter components to your storefront. This is the recommended integration method.

What is a Theme App Extension?

A Theme App Extension is Shopify's official way for apps to add functionality to your storefront without modifying your theme's code. Benefits:

No code injection — We don't edit your theme files
Theme-specific activation — Check the app embed and blocks again when changing or updating a theme
Easy enable/disable — Toggle the extension on/off in the theme editor
Automatic updates — When we release improvements, you get them automatically

Enabling the Extension

For a store accepted into the private preview, follow the supplied installation path first. Then:

Go to Online Store > Themes in your Shopify admin
Duplicate the theme, then open Edit theme for the copy
In the theme editor, click App embeds in the left sidebar
Find FilterIQ in the list
Toggle it on
Click Save

Preview the duplicate theme and test search, filters, sorting, empty results and mobile interactions before publishing. Keep the previous theme and settings as a rollback path. Confirm store-wide app-setting effects separately; theme duplication does not isolate all application configuration.

Components Included

The Theme App Extension adds these components to your storefront:

Search Widget

The search widget attaches to a supported input in your theme. Check the detected input and placement; enabling an embed does not guarantee that a missing header search input will be created. Features to validate:

Autocomplete dropdown with product suggestions
Keyboard navigation (arrow keys to navigate suggestions, Enter to select)
Mobile-responsive (full-screen search on mobile)

Filter Sidebar

A filter component for collection pages and search results. Features:

All configured filter types (swatches, sliders, checkboxes, etc.)
Real-time result count updates
Active filter chips
Clear individual or all filters
Mobile drawer mode on small screens

Search Results Grid

Product grid for displaying search results. Features:

Product cards with image, title, price, variant info
Pagination or infinite scroll (configurable)
Sort options (relevance, price, date, alphabetical)
Responsive grid (4 columns desktop, 2 columns mobile)

Placement

Automatic Placement

The extension uses configured placement and selector-based attachment. Check the intended search input, collection filter area and results grid in the duplicate theme. Custom templates or another app can change which elements are present.

Manual Placement (App Blocks)

For more control, you can manually place app blocks in the theme editor:

Open the theme editor (Online Store > Themes > Customize)
Navigate to the page where you want to add a component
Click Add block or Add section
Select the FilterIQ block you want
Position it where you'd like
Configure block settings (colors, sizing, etc.)

Customization

Visual Customization

The extension inherits your theme's fonts and base styles. You can customize:

Colors: Primary color, hover color, active filter color, text colors
Border radius: Match your theme's border radius style
Font size: Base font size for filter labels and search text
Spacing: Padding and margins

Configure in the theme editor when the app block is selected.

CSS Customization

For advanced customization, you can add custom CSS:

Go to the app dashboard → Settings > Appearance
Add CSS in the Custom CSS field
Click Save

CSS class reference:

/* Search bar */
.ssf-search-bar { }
.ssf-search-input { }
.ssf-search-autocomplete { }
.ssf-search-suggestion { }

/* Filter sidebar */
.ssf-filters { }
.ssf-filter-group { }
.ssf-filter-label { }
.ssf-filter-option { }
.ssf-filter-active { }
.ssf-filter-clear { }

/* Color swatches */
.ssf-swatch { }
.ssf-swatch--selected { }

/* Range slider */
.ssf-range-slider { }
.ssf-range-handle { }
.ssf-range-track { }

/* Results grid */
.ssf-results-grid { }
.ssf-product-card { }
.ssf-product-image { }
.ssf-product-title { }
.ssf-product-price { }

/* Mobile filter drawer */
.ssf-mobile-drawer { }
.ssf-mobile-trigger { }

Theme Compatibility

Online Store 2.0

The extension is built for the OS 2.0 theme integration model. Validate the actual version, templates, block placement, styling and other app interactions using the theme validation guide.

Vintage and Custom Storefronts

Confirm an integration path with the team before planning changes to a vintage theme or a headless storefront. A selector fallback does not establish a supported custom integration.

Interactions to Test

Overlays: Search dropdowns, navigation panels and consent controls should remain usable together
Templates: Confirm the search input and product grid selected by the extension
AJAX carts: Verify cart controls and available analytics after filtering or replacing results

Performance Impact

Measure the deployed theme and extension together:

Record transferred JavaScript/CSS sizes for the actual asset versions
Check script loading, image rendering and layout shift on cold and warm loads
Review configured input debounce separately from network and result-rendering time
Measure representative query response and interaction times, including p95/p99 behaviour
Verify that loading and error states remain usable when a request or asset is delayed

Disabling the Extension

To temporarily disable without uninstalling:

Open the theme editor
Go to App embeds
Toggle FilterIQ off
Click Save

This changes the embed state for the selected theme. Review any manual blocks and shared app configuration separately, then test the expected search behaviour before treating the change as a successful rollback.