Start your content search
4 min read

Inject Interface X Components individually into your website's DOM

This tutorial outlines how to integrate Interface X Components individually into your commerce store. This approach provides full flexibility by injecting specific components—like the search box or results grid—into any part of your site’s DOM.

Interface X can render the search experience either embedded in your page layout or as a full-screen overlay. The viewMode configuration determines which mode is used for your integration. Depending on how Interface X Components are to be rendered on your website, there are two values available:

  • embedded: Components are injected directly into the specified containers within your website's DOM. Examples in this guide follow the embedded view mode configuration.
  • fullScreen: The search experience is displayed as an overlay panel on top of your existing website content. This is the default mode.

To inject specific Interface X Components into your DOM, perform the following steps:

  1. Load the Interface X JavaScript
  2. Initialize the SnippetConfig object
  3. Choose target containers for each component
  4. Customize the container selectors in the configuration object

Once you complete these steps, Empathy's Interface X  enablement team will handle the injection and component behavior to complete the integration process.

note

If you require any help during the process, contact Empathy Support or your Key Account Manager.

Loading the script

Add the app.js script hosted by Empathy through the following environment URLs:

  • Production: https://x.empathy.co/{INSTANCE}/app.js
  • Staging: https://x.staging.empathy.co/{INSTANCE}/app.js

Where {INSTANCE} is the name of your commerce store.

For example, to load the production version for the instance my-store, you need to add the following script to your HTML:

<script src="https://x.empathy.co/my-store/app.js" type="module"></script>

If you want to load the script for the staging environment, modify the script attribute src so that it points to the staging environment as follows:

<script src="https://x.staging.empathy.co/my-store/app.js" type="module"></script>

The app.js file contains the application logic and must be loaded before any injection occurs.

Initializing Interface X

Since no initialization configuration is defined when loading the script, you need to invoke the initialization function created automatically in the X API (opens new window) object to provide the initialization options:

<script src="https://x.empathy.co/my-store/app.js" type="module"></script>
<script>
  window.InterfaceX.init({
    instance: 'my-store',
    scope: 'desktop',
    lang: 'en',
    currency: 'EUR',
    consent: false,
    viewMode: 'embedded'
  });
</script>

For this example, the initialization function is called immediately after loading the script, but it can be called at any time. Note that you need to call this function only once.

interact

Check out the X API section from the Integrate Interface X Archetype into an existing website guide to learn more about the functions and parameters supported.

Choosing target containers

For each component you want to inject, select a parent container in the DOM (for example, a <div> or section) where you want the component to appear. Assign the default data attribute for the search box (data-teleport="empathy-search-box-container") and the results grid (data-teleport="empathy-results-container") to those containers so that they can be targeted reliably and the injection can be managed successfully.

This container can wrap existing content that will be replaced or hidden when the desired X Components are injected inside that container:

<div data-teleport="empathy-search-box-container">
   /**
    * Legacy elements to be replaced
    */
</div>

Customize CSS selectors

In the initialization configuration (initX), you can indicate custom selectors for each parent container in which the X Components are inserted. Note that you can use simple selectors (.search-container) or compound selectors for those cases where selectors may change depending on the individual pages within the website structure.

coding tip

Use a selector that's stable and works across different page types (home, category, etc.). It's strongly recommended that you use data attributes to avoid issues such as CSS class name changes.

In the following example, the searchBoxSelector and resultsSelector parameters define the containers used to inject the search box and results grid components in an embedded view mode configuration:

<script>
window.initX = {
  ...[rest of the params]...
  viewMode: 'embedded',
  searchBoxSelector: ".search-container"
  resultsSelector: ".home-body-container, .categories-body-container"
}
</script>

Depending on the view mode used, the following configuration parameters are available:

  • searchBoxSelector: Selector for the container where the search box element is injected in embedded mode. Default: [data-teleport="empathy-search-box-container"].

  • resultsSelector: Selector for the container where the results element is injected in embedded mode. Default: [data-teleport="empathy-results-container"].

  • layerSelector: Selector of the element that the search layer is positioned directly below in full-screen mode. Default: undefined.

The example below shows a full-screen view mode configuration, where layerSelector is used to position the search layer:

<script>
  window.initX = {
    ...[rest of the params]...,
    viewMode: 'fullScreen', // Or do not set it since it's the default value
    layerSelector: '.header' // Or do not set it to completely cover the page
  };
</script>

Next steps

Once you've loaded the script and completed the configuration, your website is ready for the Interface X Components to be injected.

Contact your Key Account Manager to complete the setup:

  • Inject the desired Interface X Component (for example, search box, results grid) into the specified containers.
  • Position the components:
    • At the start or end of the container.
    • Before or after a specific child element.
  • Control visibility by hiding or preserving sibling elements.
  • Enable dynamic monitoring of the DOM to:
    • Detect when containers are added or removed dynamically.
    • React to changes without requiring page reloads.

For more information on loading and initializing the Interface X project, refer to the Integrate Interface X Archetype into an existing website guide.

Cookie-Less