SDK Reference

Complete reference for every configuration option you can pass to the SearchX widget.

Initialization

The widget is initialized by calling SearchXSDK.init() once on your page with a configuration object:

SearchXSDK.init({
  app_id: 'YOUR_APP_ID',
  api_key: 'YOUR_API_KEY',
  components: {
    SearchBar: { root: 'search-bar' },
    SearchPage: { root: 'search-page' },
  },
  settings: {
    /* feature toggles + UI options — see sections below */
  },
});

Every option except the credentials and components is optional. Leave a setting out to keep the SDK default.

Top-level parameters

Components object

The components object tells the widget where to render. Both keys are optional independently — render only the search bar, only the results page, or both.

components: {
  SearchBar: { root: 'search-bar' },
  SearchPage: { root: 'search-page' },
}

The target elements must exist in the DOM before init() runs and must be empty.

Settings — Layout & behaviour

High-level controls for where the widget routes searches, the platform integration mode it should use, and how pagination behaves.

Settings — Search bar popup

Controls the small popup that opens beneath the search bar while the shopper is typing — top searches, recent searches, featured products, and promotional links.

Settings — Product cards

What metadata each product card displays in the search results grid, and which shopper actions are surfaced on the card.

Settings — Filter sidebar

Which facet panels appear in the filter sidebar of the search results page. Each toggle is independent — turn on only the panels that match your catalogue.

Settings — AI Search

AI-assisted search is configured from the SearchX dashboard. The widget-side toggle below lets you opt the widget in or out at runtime.

Deprecated settings (still supported)

These settings continue to work for backward compatibility, but new integrations should use the explicit replacements below. The widget treats the new key as authoritative whenever both are set.

Full example

A complete init() call with every section represented. Trim to the settings your storefront actually needs — leaving the rest out keeps you on safe defaults.

SearchXSDK.init({
  app_id: 'YOUR_APP_ID',
  api_key: 'YOUR_API_KEY',
  apiPageURL: 'https://admin.searchxengine.ai/api/v1',
  components: {
    SearchBar: { root: 'search-bar' },
    SearchPage: { root: 'search-page' },
  },
  customCSSUrl: '/assets/theme.css',
  customLocaleUrl: '/assets/i18n/{{lng}}.json',
  defaultLanguage: 'en',
  settings: {
    // Layout & behaviour
    searchPageURL: '/search?q={query}',
    mobileViewPort: '900px',
    platform: 'custom',
    compactPagination: true,
    defaultProductsPerPage: 24,
    defaultPlaceholder: 'Search for products...',

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

    // Product cards
    showBrand: true,
    showSizes: true,
    showColor: true,
    showDescription: false,
    showSalePrice: false,
    showAddToCartButton: true,
    wishlistEnabled: true,
    cartButtonText: 'Buy Now',
    wishlistButtonText: 'Save for later',

    // Filter sidebar
    showBrandFacet: true,
    showCategoryFacet: true,
    showPriceRangeFilter: true,
    showOnSaleFacet: false, // opt-in; requires sale_price on indexed products
    showSizeFilter: true,
    showColorFilter: true,

    // AI search
    aiSearchEnabled: false,
  },
});

Related

• Quick Start — Smallest possible install.
• Widget Styling — Theme the widget with CSS variables and override component selectors.
• Suggested Links — How the dashboard-managed promotional chips work.
• URL Filters — Deep-link to filtered search results.
• Event Handling — Handle cart and wishlist clicks on custom platforms.