{"id":10677,"library":"coveo-search-ui","title":"Coveo JavaScript Search Framework","description":"The Coveo JavaScript Search Framework, currently at version 2.10125.2, provides a comprehensive set of pre-built UI components for creating search interfaces powered by the Coveo Platform. Developed in TypeScript and shipping with integrated type definitions, it facilitates robust and type-safe development. The framework exhibits a very frequent release cadence, with minor versions often released daily, reflecting active maintenance. Its core differentiator lies in a declarative approach to building search UIs, primarily utilizing HTML data attributes for components and a global `Coveo` object for programmatic control and initialization. This abstracts much of the direct interaction with the underlying search API. While actively maintained, Coveo now advises developers to use its more modern, framework-agnostic Atomic or Headless libraries for new projects, as `coveo-search-ui` is explicitly in maintenance mode.","status":"maintenance","version":"2.10125.2","language":"javascript","source_language":"en","source_url":"https://github.com/coveo/search-ui","tags":["javascript","coveo","search","ui","framework","js","typescript","jssearch","jsui"],"install":[{"cmd":"npm install coveo-search-ui","lang":"bash","label":"npm"},{"cmd":"yarn add coveo-search-ui","lang":"bash","label":"yarn"},{"cmd":"pnpm add coveo-search-ui","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For module bundlers, `import * as Coveo` makes the global Coveo object available. Direct `require` might not expose all global members correctly without further assignment or specific configuration.","wrong":"const Coveo = require('coveo-search-ui');","symbol":"Coveo","correct":"import * as Coveo from 'coveo-search-ui';"},{"note":"Type definitions like ISearchInterfaceOptions are available for use in TypeScript for stricter component configuration.","symbol":"ISearchInterfaceOptions","correct":"import { ISearchInterfaceOptions } from 'coveo-search-ui';"},{"note":"Individual UI components in the classic framework are primarily declared via specific HTML class names and `data-` attributes, then initialized by `Coveo.init()`, rather than imported directly as classes or functions in JavaScript modules.","wrong":"import { Searchbox } from 'coveo-search-ui';","symbol":"Searchbox Component (via HTML)","correct":"<div class=\"CoveoSearchbox\" data-options='{}'></div>"}],"quickstart":{"code":"import * as Coveo from 'coveo-search-ui';\n\n// Ensure Coveo CSS is loaded (example for Webpack/bundlers)\n// import 'coveo-search-ui/bin/css/CoveoFullSearch.min.css';\n\n// Basic HTML structure for the search interface\n// This would typically be in an HTML file or injected into the DOM.\nconst appRoot = document.getElementById('search-root') || document.createElement('div');\nappRoot.id = 'search-root';\ndocument.body.appendChild(appRoot);\n\nappRoot.innerHTML = `\n  <div class=\"CoveoSearchInterface\" id=\"search\">\n    <div class=\"CoveoSearchbox\"></div>\n    <div class=\"CoveoResultList\"></div>\n    <div class=\"CoveoPager\"></div>\n  </div>\n`;\n\nconst organizationId = process.env.COVEO_ORGANIZATION_ID ?? 'YOUR_ORG_ID';\nconst accessToken = process.env.COVEO_ACCESS_TOKEN ?? 'YOUR_API_KEY'; // Ensure this key has 'Search - Execute queries' privilege\nconst searchHub = process.env.COVEO_SEARCH_HUB ?? 'default';\n\n(async () => {\n  // Configure the search endpoint\n  Coveo.SearchEndpoint.configureCloudEndpoint(\n    organizationId,\n    accessToken,\n    searchHub\n  );\n\n  // Initialize the framework on the root element of the search interface\n  // For token renewal, pass a function that returns a new token.\n  Coveo.init(document.getElementById('search') as HTMLElement, {\n    // Additional options can be passed here\n    // For example, to handle token renewal:\n    // accessToken: () => fetch('/api/renew-token').then(res => res.text())\n  });\n\n  console.log('Coveo Search Interface initialized.');\n})();","lang":"typescript","description":"This quickstart demonstrates the foundational setup of a Coveo search interface using `coveo-search-ui`. It includes configuring the cloud endpoint with an API key and organization ID, defining essential search components via HTML classes, and initializing the framework."},"warnings":[{"fix":"For new implementations, evaluate `@coveo/atomic` or `@coveo/headless`. For existing projects, be aware that new features are unlikely to be added, and focus will be on bug fixes and critical updates.","message":"The `coveo-search-ui` package is in maintenance mode. For new projects, Coveo strongly recommends using the modern, framework-agnostic Atomic or Headless libraries, which offer greater flexibility and performance.","severity":"deprecated","affected_versions":">=2.x"},{"fix":"Consult the official 'Version 1.x to 2.x breaking changes and upgrade guidelines' documentation. Thoroughly test existing custom components and integrations after upgrading.","message":"Upgrading from version 1.x to 2.x introduced several breaking changes, including the removal of internal jQuery dependencies and updates to component initialization. While generally straightforward, careful review of upgrade guidelines is essential.","severity":"breaking","affected_versions":">=2.x"},{"fix":"Configure the `accessToken` option in `Coveo.init()` to accept a function that asynchronously fetches and returns a fresh search token when needed. This allows the framework to automatically renew the token.","message":"Search tokens used for authentication can expire. If not handled, this leads to an error 'This DOM element has already been initialized as a search interface, skipping initialization' because the framework cannot re-initialize with a new token directly.","severity":"gotcha","affected_versions":">=1.x"},{"fix":"Review `DynamicFacet` and `DynamicHierarchicalFacet` implementations. If previous behavior (where `filterFacetCount` was `false` by default) is desired, explicitly set `data-filter-facet-count='false'` on the component's HTML element.","message":"The `DynamicFacet` and `DynamicHierarchicalFacet` components now have `filterFacetCount` parameter set to `true` by default since a 2021 release, which changes how facet search requests are sent.","severity":"breaking","affected_versions":">=2.10092.7"},{"fix":"Adjust any custom Usage Analytics reports or integrations that rely on the `notifications` trigger or `customData.executed` to reflect the new `executions` array format.","message":"Changes to Usage Analytics event logging occurred. Specifically, the `notifications` trigger changed from a string to a string array, and `customData.executed` was replaced by `customData.executions` (an array of objects). This affects how analytics reports are structured.","severity":"breaking","affected_versions":">=2.10103.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Pass a function to the `accessToken` option of `Coveo.init()` that returns a promise resolving to a new token. The framework will call this function automatically when the token needs renewal. Do not call `Coveo.init()` multiple times on the same root element.","cause":"Attempting to call `Coveo.init()` on a DOM element that has already been initialized, typically occurring when a search token expires and a re-initialization is attempted instead of renewal.","error":"This DOM element has already been initialized as a search interface, skipping initialization"},{"fix":"Ensure that `CoveoJsSearch.min.js` (or its lazy equivalent) is loaded via a `<script>` tag in your HTML *before* any inline scripts that use `Coveo`, or that your module bundler correctly includes `coveo-search-ui` and the `import * as Coveo from 'coveo-search-ui'` statement is at the top of your relevant module.","cause":"The main Coveo JavaScript Search Framework script (CoveoJsSearch.min.js) has not been loaded or executed before attempting to access the `Coveo` global object. This can happen if script tags are in the wrong order, or if module imports are not correctly bundled.","error":"Coveo is not defined"},{"fix":"Upgrade to Coveo for Salesforce package version 3.31 or later, which includes a fix. As a workaround, add a custom script to override `Coveo.SearchInterface.prototype.setupMobileFastclick` to an empty function.","cause":"Observed in Salesforce Lightning Communities on mobile, this error occurs when Salesforce's LockerService blocks an internal 'fastclicks' library used by `coveo-search-ui`.","error":"SearchUIController: Initialization error Error in $A.getCallback() [Cannot assign to read only property 'removeEventListener' of object '[object Object]']"},{"fix":"Review Sitecore logs for specific initialization failures or `NullReferenceException` details. Ensure all Coveo for Sitecore components are correctly installed, configured, and that indexes are initialized and accessible. Rebuilding indexes may resolve the issue.","cause":"These errors, often seen in Sitecore integrations with Coveo, usually indicate that the search indexes are not properly initialized or are unavailable, potentially due to Sitecore instance startup/shutdown or incorrect installation/configuration of Coveo for Sitecore.","error":"The provided index '{0}' was not found. OR Exception System.NullReferenceException: Object reference not set to an instance of an object."}],"ecosystem":"npm"}