📢 Use this project, contribute to it or open issues to help evolve it using Store Discussion.

The VTEX Search app handles the new Intelligent Search solution in IO stores by providing new UI components to enhance the search experience, such as the autocomplete feature.

The Search app requires the [email protected] and [email protected] apps to be installed in your store. For more information, read the Intelligent Search documentation.

To configure the Search app, see the sections below.

Add the search app to your theme dependencies in the manifest.json as shown below:

  "dependencies": {
    "vtex.search": "2.x"
  }

You can now use all blocks exported by the search app. See the full list below:

ℹ️ The search-banner, did-you-mean, and search-suggestions blocks require Search Result app version 3.x or higher installed in your theme.

First, declare the autocomplete-result-list.v2 block as a child block of the search-bar block, exported by the Store Components app. Example:

{
  "search-bar": {
    "blocks": ["autocomplete-result-list.v2"],
    "props": {
      "openAutocompleteOnFocus": true
    }
  }
}

The autocomplete-result-list.v2 block also allows you to add a list of child blocks to it. You can declare a theme block and have it rendered among the autocomplete features. Example:

{
  "autocomplete-result-list.v2": {
    "blocks": ["product-summary"]
  }
}

Now, you can add the last three search blocks: search-banner, did-you-mean, and search-suggestions.

These blocks, as opposed to autocomplete-result-list.v2, need to be added under the search-result-layout.desktop or the search-result-layout.mobile blocks, following the Search Results block hierarchy.

Once added, the blocks can be declared using their respective props for configuration. Example:

{
  "search-result-layout.desktop": {
    "children": [
      "flex-layout.row#did-you-mean",
      "flex-layout.row#suggestion",
      "flex-layout.row#banner-one",
      "flex-layout.row#result"
    ],
    "props": {
      "pagination": "show-more",
      "preventRouteChange": true,
      "mobileLayout": {
        "mode1": "small",
        "mode2": "normal"
      }
    }
  },

  "flex-layout.row#did-you-mean": {
    "children": ["did-you-mean"]
  },
  "flex-layout.row#suggestion": {
    "children": ["search-suggestions"]
  },
  "flex-layout.row#banner-one": {
    "children": ["search-banner#one"]
  },

  "search-banner#one": {
    "props": {
      "area": "one",
      "blockClass": "myBanner",
      "horizontalAlignment": "center"
    }
  }
}

To improve the user's search experience in stores where the Intelligent Search engine is supported, the app have the following options:

• Stores using Universal Analytics (UA):

  The Search app provides blocks that, when rendered as components, will improve the user's search experience in stores where the Intelligent Search engine is supported.

  These components use _q as the query-string for the search term, meaning that if you want to track user searches in these components, you will need to add the _q query-string to the store's Google Analytics. To activate this behavior, refer to Set up Site Search Google's documentation.

    >❗ Please note that although the Search app's blocks enhance the search experience in VTEX stores, this feature is only compatible with VTEX stores using UA. As UA will be discontinued on July 1st, 2023, **we highly recommend that you update your store to GA4**. For more information on the migration, see the [release notes](https://developers.vtex.com/updates/release-notes/2023-05-04-google-tag-manager-new-version) and follow the option below.
  

• Store using Google Analytics 4 (GA4):

  Install the VTEX Google Tag Manager app, which includes the search event within the app's data layer. This app is responsible for tracking the user's search activity. For instructions on setting up Google Tag Manager, consult the Setting up Google Tag Manager documentation.

In order to apply CSS customizations to this and other blocks, follow the instructions given in the recipe on Using CSS handles for store customizations.

Thanks goes out to these wonderful people:

This project follows the all-contributors specification. Contributions of any kind are welcome!