OpenCart Integration

Install the official SearchX extension from your OpenCart admin panel.

Overview

The SearchX extension is the recommended way to integrate SearchX with OpenCart. Once installed and configured from the admin panel, it automatically:

• Replaces the native search bar and search results page with the SearchX widget.
• Injects the SDK and preload hints on every storefront page — no template files to edit.
• Handles Add to Cart and Add to Wishlist directly, using OpenCart's own cart API.
• Auto-detects your active theme (Journal 3, So-eMarket, and the default OpenCart theme are supported out of the box).

You can enable, disable, or update credentials at any time from the admin panel without touching any files.

If your theme isn't auto-detected yet, or you don't have access to the extension installer, see Manual Integration below.

Step 1: Download the extension

1. Open your application in the SearchX dashboard and go to the Details tab.
2. Scroll to Install JS Snippet and select the OpenCart tab.
3. Download the package that matches your store version:
   • OpenCart 4.x → searchx.ocmod.zip
   • OpenCart 3.x → searchx-oc3.ocmod.zip

You can also find SearchX by searching the OpenCart Marketplace and installing it from there.

Step 2: Upload and apply the package

1. In your OC admin, go to Extensions → Installer.
2. Click Upload and select the zip file you downloaded.
3. Wait for the success message — SearchX now appears in the Installer list.
4. Click the green Install (+) button next to SearchX to extract and register the files.

Step 3: Install the module

1. Go to Extensions → Extensions and filter the type dropdown to Modules.

2. Find SearchX in the list and click Install (+).

   The extension shows as Disabled at this stage — that's expected. You'll enable it in the next step.

3. Click the Edit (pencil) button next to SearchX to open its settings page.

Step 4: Configure credentials

Fill in the settings form and save.

Click Save (floppy disk icon, top-right) when you're done.

Step 5: Clear the cache and verify

OpenCart caches compiled templates, so clear the cache before checking the storefront:

1. Go to your admin Dashboard.
2. Click the blue circular Refresh button in the top-right of the statistics area.

Then do a hard refresh on your storefront (Cmd/Ctrl + Shift + R). You should see:

• The SearchX search bar in place of the native search input.
• Instant suggestions as you type.
• The full SearchX results page at your search route.
• Add to Cart / Add to Wishlist updating without a page reload.

If something looks wrong, confirm Status is Enabled and your credentials are saved correctly, then check the browser console for messages prefixed [SearchX].

Platform Setting

The Platform field controls how Add to Cart and Add to Wishlist resolve products, and depends on what your SearchX product feed uses as unique_id:

A platform mismatch breaks Add to Cart silently, so double-check which identifier your feed exports before going live.

For non-extension integrations, see Event Handling for the equivalent platform SDK setting.

Theme Support

The extension auto-detects your active theme — no configuration needed:

Theme detection is served from the SDK, so support for new themes ships as a CDN update — you don't need to reinstall or upgrade the extension.

Updating, Disabling, and Uninstalling

• Update credentials: Extensions → Extensions → Modules → SearchX → Edit, change the fields, and save. No cache clear needed for credential-only changes.
• Disable temporarily: Same settings page, set Status to Disabled, save, and clear the template cache. The native search bar returns immediately; all settings are preserved.
• Uninstall: Extensions → Extensions → Modules, click Uninstall next to SearchX. This removes the event hooks and saved settings; the extension files stay on the server until you delete the extension/searchx/ folder (OC4) or the files copied by the installer (OC3).

Manual Integration

If you can't use the extension — for example, your theme isn't auto-detected yet and you need custom mount points — you can integrate SearchX by editing three template files directly.

Step 1: Configure Footer & Initialization

Add the SDK scripts and initialization to your footer template.

File: catalog/view/template/common/footer.twig

<!-- SearchX SDK Dependencies (React 18) -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<!-- SearchX SDK Core -->
<script src="https://sdk.searchxengine.ai/searchx-sdk.umd.js"></script>
<script>
  (function () {
    var storedLang = localStorage.getItem('searchx_lang') || 'en';
    window.SEARCHX_LANG = storedLang;

    function initSearchX() {
      if (!window.SearchXSDK) {
        console.warn('SearchX SDK not loaded yet.');
        return;
      }
      window.SearchXSDK.init({
        app_id: 'YOUR_APP_ID',
        api_key: 'YOUR_API_KEY',
        components: {
          SearchBar: { root: 'search-bar' },
          SearchPage: { root: 'search-page' },
        },
        customCSSUrl: '/catalog/view/stylesheet/custom/client-theme.css',
        customLocaleUrl: '/catalog/view/stylesheet/custom/locales/' + storedLang + '.json',
        defaultLanguage: storedLang,
        settings: {
          // Layout & behaviour
          platform: 'opencart',
          compactPagination: true,
          defaultProductsPerPage: 24,

          // Search bar popup
          showPopupAddToCart: true,
          showPopupSearchIcon: true,

          // Product cards
          showBrand: true,
          showSizes: true,
          showColor: true,
          showAddToCartButton: true,
          wishlistEnabled: true,

          // Filter sidebar
          showBrandFacet: true,
          showCategoryFacet: true,
          showPriceRangeFilter: true,
          showSizeFilter: true,
          showColorFilter: true,
        },
      });

      window.dispatchEvent(new Event('searchx:ready'));
      window.searchxReady = Promise.resolve();
    }

    if (window.SearchXSDK) {
      initSearchX();
    } else {
      window.addEventListener('load', initSearchX);
    }
  })();
</script>

Step 2: Search Bar Integration

Replace your existing search input with the SearchX container.

File: catalog/view/template/common/search.twig

<div id="search-bar" class="searchx-bar-container"></div>
<script>
  (function () {
    function mountSearchBar() {
      if (window.SearchXSDK && window.SearchXSDK.mount) {
        if (document.getElementById('search-bar')) {
          SearchXSDK.mount('Searchbar', { root: 'search-bar' });
        }
      }
    }
    if (window.searchxReady) {
      mountSearchBar();
    } else {
      window.addEventListener('searchx:ready', mountSearchBar);
    }
  })();
</script>

Step 3: Search Results Page

Update your search results template to use SearchX.

File: catalog/view/template/product/search.twig

Add the SearchX container inside your content area. Use Twig's header and footer includes as usual, and place the SearchX container where the default product listing loop was:

<div id="content" class="container">
  <!-- Your existing breadcrumbs here -->

  <!-- SearchX Results Container -->
  <div id="search-page" class="searchx-page-container"></div>
</div>
<script>
  (function () {
    function mountSearchPage() {
      var rootId = 'search-page';
      if (!document.getElementById(rootId)) return;
      if (window.SearchXSDK && window.SearchXSDK.mount) {
        try {
          SearchXSDK.mount('SearchPage', { root: rootId });
        } catch (err) {
          console.error('SearchX: Failed to mount SearchPage', err);
        }
      }
    }
    document.addEventListener('DOMContentLoaded', function () {
      if (window.searchxReady) {
        mountSearchPage();
      } else {
        window.addEventListener('searchx:ready', mountSearchPage);
      }
    });
  })();
</script>

When integrating manually, set the platform setting to "opencart" to enable OpenCart-specific Add to Cart behavior via its native API routes. For more details, see Event Handling.

Next Steps

• Customize the widget appearance with Widget Styling.
• Set up custom translations with Localization.