Autocomplete

FilterIQ provides an instant search dropdown that appears as shoppers type in your store's search bar. This page covers how it works and how to configure it.

How It Works

The instant search widget (instant-search.js) looks for configured or recognized search-input selectors, including input[name="q"]. Validate the selected input and other theme overlays in a duplicate theme preview; selector matching does not guarantee compatibility with every template.

When a shopper starts typing:

1. The widget waits for the configured trigger length (default: 1 character)
2. Input is debounced (default: 150ms) to avoid excessive API calls
3. A request is sent through the Shopify App Proxy to the backend
4. Results are returned and displayed in a dropdown overlay

The dropdown is appended directly to document.body with fixed positioning. It never wraps or reparents your theme's search input, preserving your theme's DOM structure.

Configuration Options

You can configure autocomplete behavior in the app dashboard under Search > Configuration.

Layout Modes

Rich (default)

The rich layout displays product results with thumbnails, titles, prices, and variant information. Collection and page suggestions appear in a secondary column.

Minimal

A compact text-only layout suitable for stores that prefer a simpler search experience. Shows product titles and prices without images.

Fullwidth

A wide dropdown that spans the full width of the page header. Best for stores with large catalogs where showing more results at a glance is beneficial.

Result Sections

The autocomplete dropdown can show up to four sections:

• Products -- Matching products with thumbnail, title, price, and variant info
• Collections -- Matching collections by name
• Pages -- Matching pages (about, FAQ, etc.)
• Suggestions -- Common query completions based on the partial input

Each section can be independently enabled or disabled in the dashboard.

Keyboard Navigation

The autocomplete dropdown implements keyboard controls. Validate the following interactions in your theme, including focus and screen-reader announcements; this list is not an accessibility certification:

The widget uses proper ARIA attributes including role="combobox", aria-activedescendant, and live regions for screen reader announcements.

Mobile Behavior

On screens narrower than 768px, the autocomplete dropdown switches to a full-screen overlay mode. This provides:

• Larger touch targets (minimum 44x44px)
• Full-width search results
• A prominent close button
• Scroll lock on the background page

Performance

• Measure autocomplete from input to usable results, including debounce, network and rendering; timing varies by catalogue and conditions
• The widget loads configuration during search interaction and retains the available settings for the page session
• If the configuration fetch fails, the widget falls back to default settings from the Liquid template
• Confirm available analytics events and privacy requirements before relying on a custom integration; internal widget events are not a published API contract

Troubleshooting

Dropdown does not appear

• Verify the Theme App Extension embed is enabled in Online Store > Themes > Customize > App embeds
• Check that your theme's search input uses a standard name="q" attribute
• Open browser DevTools and check the Console for [SSF] messages

Dropdown appears in the wrong position

• The dropdown uses position: fixed and calculates its position relative to the search input
• Custom theme CSS that sets transform or will-change on parent elements can affect fixed positioning
• Contact support@filteriq.app with your theme name for help