Search Suggestions Setup for Bitrix CMS
Search suggestions — a dropdown list with options when typing in the search field. In Bitrix, suggestions are implemented through the bitrix:search.suggest component and work via AJAX request to the search controller. Without proper setup, suggestions either don't appear or show irrelevant results.
How Suggestions Work
With each character input (with debounce), the browser sends a GET request to /bitrix/components/bitrix/search.suggest/ajax.php with parameters q (query) and lang (language). Response is JSON with a list of suggestions.
The source of data for suggestions is the search index b_search_content — the same data as for main search. Therefore, suggestions only work with a built index.
Including the Suggestions Component
In the search form template:
$APPLICATION->IncludeComponent('bitrix:search.suggest', '', [
'SITE_ID' => SITE_ID,
'START_SEARCH_FORM_ID' => 'searchForm', // search form ID
'SUGGEST_MAX_COUNT' => 10, // maximum suggestions
'MIN_QUERY_LENGTH' => 3, // minimum characters for query
'SUGGEST_CACHE_TIME' => 3600, // response cache
'FILTER_NAME' => 'arrFILTER',
'arrFILTER' => [
['MODULE_ID' => 'iblock', 'PARAM1' => 'catalog', 'PARAM2' => 5],
],
]);
The search form must have a field named q and ID specified in START_SEARCH_FORM_ID.
Customizing Suggestions Appearance
The component template is located at /bitrix/components/bitrix/search.suggest/templates/.default/. For customization — copy to /local/components/bitrix/search.suggest/templates/custom/ and edit.
The standard template outputs only title text. Often required to add product images and prices — implemented via custom template with additional query to catalog by found element IDs.
Search by Trade Offers (SKU)
By default, search and suggestions work on main products, not SKUs. To search by SKU codes, enable indexing of trade offers:
Settings → Search → Additional settings — enable indexing of trade offer properties, specify offers infoblock.
AJAX Request Performance
With high traffic, suggestion AJAX requests can load the server. Solutions:
- Increase
SUGGEST_CACHE_TIME— suggestions are cached in Bitrix file cache - Enable managed cache for the component
- For high-load sites — deliver suggestions via separate cached endpoint with TTL
Implementation Timeline
Basic suggestions setup with component connection — 1–2 hours. Custom template with images and prices — 3–5 hours.