This page is about version 2.4.0 of the app, which is not the most recent version. The latest stable version is 2.16.10.
The VTEX Search app is responsible for handling the new VTEX Intelligent Search solution in IO stores by providing new UI components that enhance the search experience, such as the autocomplete feature.
Configuration
:warning: The proper functioning of the Search app components relies on having already installed apps vtex.admin-search@1.x
and vtex.search-resolver@1.x
in your store. For more on this, access our Help Center track on VTEX Intelligent Search.
Step 1 - Adding the Search app to your theme's dependencies
Add the search
app to your theme's dependencies in the manifest.json
as showed below:
_10 "dependencies": {_10+ "vtex.search": "2.x"_10 }
You are now able to use all of the blocks exported by the search
app. Check the full list below:
Block name | Description |
---|---|
autocomplete-result-list.v2 | Provides customized autocomplete features in the search bar component, such as top searches, search history, product suggestions or term suggestions. You can read more about the Intelligent Search autocomplete feature on VTEX Help Center. |
search-banner | Renders a customized banner according to the search query performed. |
did-you-mean | Helps users with possible misspelling corrections for the current search query. |
search-suggestions | Renders a list of similar search terms for the current search query. |
:warning: The blocks search-banner
, did-you-mean
and search-suggestions
require you to have Search Results app version 3.x or higher installed in your theme.
Step 2 - Adding the Search's blocks into the theme
First, declare the autocomplete-result-list.v2
block as a child block of the search-bar
block, exported by the Store Components app. For example:
_10{_10 "search-bar": {_10 "blocks": ["autocomplete-result-list.v2"],_10 "props": {_10 "openAutocompleteOnFocus": true_10 }_10 }_10}
autocomplete-result-list.v2
props
Prop name | Type | Description | Default value |
---|---|---|---|
maxTopSearches | number | Maximum number of items in the top searches list. | 10 |
maxHistory | number | Maximum number of items in the search history list. | 5 |
maxSuggestedProducts | number | Maximum number of items in the suggested products list. | 3 |
maxSuggestedTerms | number | Maximum number of items in the suggested terms list. | 3 |
autocompleteWidth | number | Autocomplete list width (in percent). The value must be between 0 and 100 | undefined |
productLayout | enum | Defines the suggested products list layout when rendered. Possible values are HORIZONTAL and VERTICAL . | undefined |
hideTitles | boolean | Defines whether all component titles are hidden when rendered (true ) or not (false ). | false |
hideUnavailableItems | boolean | Defines whether the autocomplete should hide unavailable items (true ) or not (false ). | false |
historyFirst | boolean | Defines whether the search history list should be prioritized over the other lists (true ) or not (false ). | false |
customBreakpoints | object | Defines a maximum number of suggested products by breakpoints. Possible values are md , lg or xlg . | - |
__unstableProductOriginVtex | boolean | When set as true , the prop enables the Intelligent Search to fetch catalog data in scenarios where product information is missing. This prop is extremely useful if you have sellers White Labels or if you just want to avoid rendering errors related to product data. But note the following: it may lead to a search performance loss. | false |
simulationBehavior | "skip" or "default" | If you want faster searches and do not care about most up to date prices and promotions, use "skip" value. | default |
customBreakpoints
object:
Prop name | Type | Description | Default value |
---|---|---|---|
md | object | Defines the maximum number of suggested products for the md breakpoint. | undefined |
lg | object | Defines the the maximum number of suggested products for the lg breakpoint. | undefined |
xlg | object | Defines the the maximum number of suggested products for the xlg breakpoint. | undefined |
md
,lg
andxlg
objects:
Prop name | Type | Description | Default value |
---|---|---|---|
width | number | Breakpoint minimum width. | undefined |
maxSuggestedProducts | number | Maximum number of suggested products. | undefined |
The autocomplete-result-list.v2
block also allows you to add a list of child blocks onto it.
This means that you can declare a theme block of your choosing and have it rendered among the autocomplete features. For example:
_10{_10 "autocomplete-result-list.v2": {_10 "blocks": ["product-summary"]_10 }_10}
Now, the time has come to add the last 3 search blocks: search-banner
, did-you-mean
and search-suggestions
.
Those blocks, differently from autocomplete-result-list.v2
, need to be added under the search-result-layout.desktop
or the search-result-layout.mobile
blocks, according to the Search Results block hierarchy.
Once added, these can be declared using their respective props for their configuration. For example:
_36{_36 "search-result-layout.desktop": {_36 "children": [_36 "flex-layout.row#did-you-mean",_36 "flex-layout.row#suggestion",_36 "flex-layout.row#banner-one",_36 "flex-layout.row#result"_36 ],_36 "props": {_36 "pagination": "show-more",_36 "preventRouteChange": true,_36 "mobileLayout": {_36 "mode1": "small",_36 "mode2": "normal"_36 }_36 }_36 },_36_36 "flex-layout.row#did-you-mean": {_36 "children": ["did-you-mean"]_36 },_36 "flex-layout.row#suggestion": {_36 "children": ["search-suggestions"]_36 },_36 "flex-layout.row#banner-one": {_36 "children": ["search-banner#one"]_36 },_36_36 "search-banner#one": {_36 "props": {_36 "area": "one",_36 "blockClass": "myBanner",_36 "horizontalAlignment": "center"_36 }_36 }_36}
search-banner
props
Prop name | Type | Description | Default value |
---|---|---|---|
area | string | Area of the store where the banner will be displayed. It needs to match the predefined area value in the banner setup. | undefined |
blockClass | string | Unique block ID to be used in CSS customization | undefined |
horizontalAlignment | string | Defines the banner horizontal alignment. Possible values are left , center or right . | center |
Modus Operandi
The Search app is merely responsible for offering blocks that when rendered as components will improve the user's search experience in stores where the VTEX Intelligent Search engine is already supported.
These components use _q
as the query-string for the search term, meaning that if you wish to track the searches of your users in these components you'll need to add the _q
query-string to the store's Google Analytics.
Find out how to do this by accessing our Google Analytics search tracking documentation.
Customization
In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.
CSS Handles |
---|
searchBanner |
didYouMeanPrefix |
didYouMeanTerm |
suggestionsList |
suggestionsListItem |
suggestionsListLink |
itemListSubItemLink |
itemListLink |
itemListLinkTitle |
Tests
We use Cypress to run end to end tests. If you want to run our tests, use the VTEX test command:
_10$ vtex test e2e
To provide your local user token, pass the --token
command line argument to the test command:
_10$ vtex test e2e --token
If you want to run Cypress locally, you can use the commands yarn e2e:open
or yarn e2e:run
.