TURBO for Developers

Home > widget-integration > InstantSearchModule

InstantSearchModule class

Instant Search Widget Module

Provides a unified, framework-based instant search system for Shopify themes.

**Features**: - Search-as-you-type with debounced API requests - Multiple display styles (dropdown, full-width overlay) - 20+ theme auto-detection and integration - Full keyboard accessibility (WCAG compliant) - Recent searches management - Custom events for extensibility

**Migration from Legacy**:

| Legacy | New Module | |-------------------------------------|-------------------------------------| | handleInstantSearchWidget(context) | window.boostISWModule.initISWWithContext(settings) | | Global functions with context param | DI-based services | | Hard-coded selectors | Theme config map | | Inline event handling | Controller with state management |

**Technical Support Extension**:

window.boostWidgetIntegration.extend('InstantSearchModule', (InstantSearchModule) => {
  return class CustomISWModule extends InstantSearchModule {
    async onInitBlock(block) {
      // Add custom tracking
      await super.onInitBlock(block);
    }
  };
});

Signature:

export declare class InstantSearchModule

Constructors

Constructor	Modifiers	Description
(constructor)(moduleRef, appService)		Constructs a new instance of the `InstantSearchModule` class

Properties

Property	Modifiers	Type	Description
appService	`protected`	AppService
blockInitialized	`protected`	boolean	Whether the block has been fully initialized (including click listeners, bundles, etc.)
contextInitialized	`protected`	boolean	Whether the module has been initialized with context
currentBundles	`protected`	Array<Record<string, unknown>>	Current bundles from the latest search render (updated via boost-sd-isw-rendered event)
instantSearchAPI	`protected`	InstantSearchAPI	Instance of the InstantSearchAPI
instantSearchController	`protected`	InstantSearchController	Instance of the InstantSearchController
instantSearchSelectors	`protected`	InstantSearchSelectors	Instance of the InstantSearchSelectors
instantSearchService	`protected`	InstantSearchService	Instance of the InstantSearchService
moduleRef	`protected`	ModuleRefImpl
recentSearchService	`protected`	RecentSearchService	Instance of the RecentSearchService
servicesResolved	`protected`	boolean	Whether services have been resolved from DI

Methods

Method	Modifiers	Description
addRecentSearch(query)		Add a recent search.
bindSearchInputs()		Re-bind search inputs. Call this after dynamically adding new search inputs to the page. Legacy: Required manual event binding New: bindSearchInputs()
callAfterRenderHooks(block)	`protected`	Call afterRender customization hooks if configured. Supports both block-specific and global afterRender callbacks defined via `context.app.customization`.
clearRecentSearches()		Clear all recent searches.
closeSuggestion()		Close suggestion dropdown/overlay. Legacy: closeSuggestion(context, input?) / onCloseSuggestion(context, input?) New: closeSuggestion()
getRecentSearches(limit)		Get recent searches.
getSuggestionData()		Get current suggestion data. Legacy: context.useContextState('instant-search')[0]() New: getSuggestionData()
getThemeSearchConfig()		Get theme search configuration. Legacy: Hard-coded selectors New: getThemeSearchConfig()
handleInputChange(event, input)		Handle input change event. For legacy compatibility.
handleKeydown(event, input)		Handle keydown event. For legacy compatibility.
handleRecentSearchClick(event)	`protected`	Handle clicks on popular suggestions and no-result suggestions to save them as recent searches.
initBundleIntegrations(_block)	`protected`	Initialize dynamic bundle and volume bundle integrations for ISW. Bundle modules are loaded on demand so they can register their own TAE listeners only when the instant-search block is initialized.
initISWWithContext(searchSettings)		Initialize ISW with search settings. Legacy: handleInstantSearchWidget(context) New: initISWWithContext(searchSettings)
onInitBlock(block)	`protected`	Called when an instant search block is registered. Resolves services, exports the module to `window`, and defers or immediately initializes the controller depending on device type. On mobile/tablet (< 991 px) the ISW initializes immediately because users interact with the search input right away. On desktop, initialization is deferred until the first `mousemove` or `touchmove` event for performance.
openSuggestion(input)		Open suggestion dropdown/overlay. Legacy: openSuggestion(context, input) / onOpenSuggestion(context, input) New: openSuggestion(input?)
resolveServices()	`protected`	Resolve DI service instances (idempotent).
search(query)		Trigger a search. Legacy: requestSuggestionDebounce(context, query) New: search(query)
setupBlockClickListeners(block)	`protected`	Set up click delegation for the ISW block. Handles watermark clicks, recent search suggestion clicks, bundle product clicks, and locale-aware link navigation.
setupBlockListener()	`protected`	Sets up the TAE App block listener for instant search widget. Follows the same pattern as FilterModule.setupBlockListener(), RecommendationModule.setupBlockListener(), etc. Override this method to customize block detection or support additional block types.
toggleSuggestion()		Toggle suggestion visibility. Legacy: N/A New: toggleSuggestion()

← Back to Library Reference