The Autocomplete module provides methods to retrieve autocomplete suggestions as users type their search queries.
Getting Started The autocomplete module is available on your Constructor.io client instance:
const ConstructorioClient = require ( '@constructor-io/constructorio-client-javascript' ); const constructorio = new ConstructorioClient ({ apiKey: 'YOUR_API_KEY' , }); // Access the autocomplete module constructorio . autocomplete . getAutocompleteResults ( 't-sh' );
Methods getAutocompleteResults Retrieve autocomplete suggestions based on a partial query.
Basic Usage
With Parameters
Section-Specific Filters
constructorio . autocomplete . getAutocompleteResults ( 't-sh' ) . then (( response ) => { console . log ( response . sections ); });
Parameters The partial search term to get autocomplete suggestions for
Additional parameters to refine the result set The total number of results to return across all sections
Number of results to return per section. Keys are section names, values are numbers. Example: { Products : 5 , 'Search Suggestions' : 10 }
Key/value mapping of filters used to refine results across all sections
Filters used to refine results per section. Keys are section names, values are filter objects.
Format options used to format different aspects of the response
Faceting expression to scope autocomplete results
Hidden metadata fields to return
The variations map object to aggregate variations
Additional query parameters to be appended to requests for results
Parameters relevant to the network request Request timeout in milliseconds
Response Structure Autocomplete results are organized into sections:
{ "sections" : { "Search Suggestions" : [ { "value" : "t-shirts for men" , "data" : { "total_num_results" : 245 }, "result_id" : "abc123-xyz789" }, { "value" : "t-shirts women" , "data" : { "total_num_results" : 189 }, "result_id" : "abc123-xyz789" } ], "Products" : [ { "matched_terms" : [ "t-shirt" ], "data" : { "id" : "shirt-123" , "title" : "Blue T-Shirt" , "url" : "/products/shirt-123" }, "result_id" : "abc123-xyz789" } ] }, "result_id" : "abc123-xyz789" , "request" : { ... } }
Each item in every section includes a result_id field that should be used when tracking user interactions.
Common Use Cases
As-You-Type Suggestions
Call getAutocompleteResults on each keystroke with a debounce: let debounceTimer ; function handleSearchInput ( event ) { clearTimeout ( debounceTimer ); debounceTimer = setTimeout (() => { const query = event . target . value ; if ( query . length >= 2 ) { constructorio . autocomplete . getAutocompleteResults ( query ) . then ( displaySuggestions ); } }, 300 ); }
Display Suggestions by Section
Render different sections with appropriate styling: function displaySuggestions ( response ) { const { sections } = response ; // Display search suggestions if ( sections [ 'Search Suggestions' ]) { renderSearchSuggestions ( sections [ 'Search Suggestions' ]); } // Display product suggestions if ( sections . Products ) { renderProductSuggestions ( sections . Products ); } }
Track User Selections
Track when users select a suggestion: function handleSuggestionClick ( suggestion ) { // Navigate to the suggestion window . location . href = suggestion . data . url ; // Track the selection using the tracker module constructorio . tracker . trackAutocompleteSelect ( suggestion . value , { result_id: suggestion . result_id } ); }
Events The autocomplete module dispatches custom events on the browser window when requests complete:
window . addEventListener ( 'cio.client.autocomplete.getAutocompleteResults.completed' , ( event ) => { // event.detail contains the response data console . log ( event . detail ); }, false );
Query Handling Queries starting with / are automatically converted to | for backend API compatibility.
Implement debouncing (300ms recommended) to reduce API calls
Set a minimum query length (2-3 characters) before making requests
Use resultsPerSection to limit the number of results and improve response times
Cache responses for identical queries within a session
