Access Headless through Atomic

This is for:

Developer

The Atomic library uses Coveo Headless to interface with Coveo. For advanced customizations not possible in Atomic components, you can leverage the Headless library directly through Atomic.

The following example code shows how to use Headless to modify the advanced query expression in an Atomic search interface.

<!DOCTYPE html>
<html dir="ltr" lang="en">
  <head>
    <script type="module" src="https://static.cloud.coveo.com/atomic/v2/atomic.esm.js"></script>
    <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v2/themes/coveo.css" />
    <script type="module">
      import {
        buildRedirectionTrigger,
        loadAdvancedSearchQueryActions
      } from 'https://static.cloud.coveo.com/atomic/v2/headless/headless.esm.js'; 

      (async () => {
        await customElements.whenDefined('atomic-search-interface');
        const searchInterface = document.querySelector('atomic-search-interface');
        await searchInterface.initialize({
          accessToken: 'xx564559b1-0045-48e1-953c-3addd1ee4457',
          organizationId: 'searchuisamples',
          organizationEndpoints: await searchInterface.getOrganizationEndpoints('searchuisamples'),
        });
 
        const engine = searchInterface.engine; 

        const controller = buildRedirectionTrigger(engine); 
        controller.subscribe(() => { 
          const { redirectTo } = controller.state;
          if (redirectTo) {
            window.location.replace(redirectTo);
          }
        });

        const action = loadAdvancedSearchQueryActions(engine).updateAdvancedSearchQueries({ 
          aq: '@author="BBC News"',
        });
        engine.dispatch(action); 
 
        searchInterface.executeFirstSearch();
      })();
    </script>
  </head>
  <body>
    <atomic-search-interface id="search">
      <atomic-search-box></atomic-search-box>
      <atomic-query-summary></atomic-query-summary>
      <atomic-result-list>
        <!-- ... -->
      </atomic-result-list>
    </atomic-search-interface>
  </body>
</html>

	Import the target Headless controllers or methods via CDN.
	After initializing the search interface, access and store the engine in a variable. You’ll need it to use Headless.
	Use the engine and the Headless controller builder you imported above in order to create a controller that can subscribe to the engine and dispatch actions.
	Subscribe to the engine and handle the redirection triggers.
	Use the engine and the Headless action creator you imported above in order to create an action that modifies the advanced query.
	Dispatch the action.

In your browser developer tools, if you inspect the search request sent to the https://platform.cloud.coveo.com/rest/search/v2 endpoint, you’ll see that the request payload includes the following search request parameter, as desired.

{
  ...
  "aq": "@author=\"BBC News\"",
  ...
}

You can find a more complex example in the Atomic project repository.