Use a standalone search box

This is for:

Developer

In this article

Static search box behaviour
Dynamic search box behaviour

A standalone search box is a search box that’s independent of the display of results. This is controlled with the redirection-url property of the atomic-search-box component. You can use this pattern to set up your search on one page before you redirect your users to a page to display the full search results.

Important

Query pipeline redirects will overwrite the redirection-url if it’s set on the pipeline being queried.

In the following examples, it’s assumed that there’s no pipeline redirect set.

With the redirection-url parameter set, the search box automatically redirects to the target URL when a search is executed.

In the following example, there’s a standalone search box defined in the <header /> of a page:

<!doctype html>
<html lang="en">
  <head>
    <script type="module" src="https://static.cloud.coveo.com/atomic/v3/atomic.esm.js"></script> 
    <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v3/themes/coveo.css"/>
    <script type="module">
      import {
        getSampleSearchEngineConfiguration
      } from "https://static.cloud.coveo.com/headless/v3/headless.esm.js";

      (async () => {
        await customElements.whenDefined("atomic-search-interface");
        const searchInterface = document.querySelector("atomic-search-interface");
        const configuration = { 
          ...getSampleSearchEngineConfiguration(),
        };
        await searchInterface.initialize(configuration);
        window.coveoEngine = searchInterface.engine;
      })();
    </script>
  </head>

  <header>
    <atomic-search-interface>
      <atomic-search-box redirection-url="search-results.html"></atomic-search-box> 
    </atomic-search-interface>
  </header>
  <body>
    <h1>This is a page without any search results content.</h1>
  </body>
</html>

	Ensure that the Atomic library and styling is loaded.
	`configuration` needs to be replaced with a valid search engine configuration. Refer to `SearchEngineConfiguration` for details.
	Every time a user submits a search, the search box redirects them to `search-results.html`.

It’s often simpler to have a single search box used on multiple pages on your site.

You can change the behaviour of a single search box by programmatically modifying the redirection-url parameter of the atomic-search-box component.

Embedded in a normal page

Here’s a page which provides a search box. As in the previous example, there’s no interface to display search results. This examples lacks a redirection-url for atomic-search-box:

<!doctype html>
<html lang="en">
  <head>
    <script type="module" src="https://static.cloud.coveo.com/atomic/v3/atomic.esm.js"></script> 
    <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v3/themes/coveo.css"/>
    <script type="module" src="./atomic-bootstrap.js"></script> 
  </head>

  <header>
    <atomic-search-interface id="search-interface">
      <atomic-search-box id="search-box"></atomic-search-box>
    </atomic-search-interface>
  </header>
  <body>
    <h1>This is a page without any search results content.</h1>
  </body>
</html>

	Ensure that the Atomic Library and styling is loaded.
	Shared script to initialize the search box.

The atomic-bootstrap.js script included by this page controls redirection-url programmatically:

// atomic-bootstrap.js
import {getSampleSearchEngineConfiguration} from 'https://static.cloud.coveo.com/headless/v3/headless.esm.js';

(async () => {
  await customElements.whenDefined('atomic-search-interface'); 
  const searchBox = document.querySelector(
    'atomic-search-box#search-box' 
  );
  if (!searchBox) return; 

  const searchResults = document.querySelector(
    'atomic-search-interface#results' 
  );
  searchBox.setAttribute(
    'redirection-url', 
    searchResults ? undefined : 'search-results.html' 
  );
  const searchInterface = document.querySelector(
    'atomic-search-interface#search-interface' 
  );
  const configuration = {
    ...getSampleSearchEngineConfiguration(), 
  };
  await searchInterface.initialize(configuration); 
  window.coveoEngine = searchInterface.engine; 
})();

	Ensure that an `atomic-search-interface` component has been loaded before proceeding.
	Be as specific as you can with the search box you are targeting.
	Don’t proceed if no `atomic-seach-box` can be found on the page.
	Check to see if there is an `atomic-search-interface` to display search results on the page.
	Manage the redirection URL for the search box.
	If the `atomic-search-interface` used to results display is found, don’t redirect the user.
	Note the targeting by id here. The page contains multiple instances of `atomic-search-interface` and it’s important to target the correct one.
	`configuration` needs to be replaced with a valid search engine configuration. Refer to `SearchEngineConfiguration` for details.
	Initialize the search interface.
	Expose the master engine so other interfaces can attach to it.

Embedded in a search results page

In search-results.html, the same atomic-search-box is used, though in this case the page displays search results:

<!doctype html>
<html lang="en">
  <head>
    <script type="module" src="https://static.cloud.coveo.com/atomic/v3/atomic.esm.js"></script>
    <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v3/themes/coveo.css"/>
    <script type="module" src="./atomic-bootstrap.js"></script> 
    <script type="module" src="./search-results.js"></script> 

  </head>

  <header>
    <atomic-search-interface id="search-interface">
      <atomic-search-box id="search-box"></atomic-search-box>
    </atomic-search-interface>
  </header>

  <body>
    <h1>This is a page with search results content.</h1>
    <atomic-search-interface id="results"> 
      <atomic-result-list>
        <atomic-result-template>
          <template>
            <atomic-result-link></atomic-result-link>
          </template>
        </atomic-result-template>
      </atomic-result-list>
    </atomic-search-interface>
  </body>
</html>

	Use the same script from the other page to initialize the search box.
	Attach the search results to the master engine.
	This is a minimal example of showing search results. Refer to `atomic-result-list` for detailed instructions on how to customize your search results.

In search-results.js, the instance of the initialized search engine is connected to this search results interface:

// search-results.js
(async () => {
  await customElements.whenDefined('atomic-search-interface'); 

  const searchResults = document.querySelector(
    'atomic-search-interface#results' 
  );

  if (!searchResults) return;

  while (!window.coveoEngine) {
    await new Promise((r) => setTimeout(r, 50)); 
  }

  await searchResults.initializeWithSearchEngine(window.coveoEngine); 

  searchResults.executeFirstSearch(); 
})();

	Wait until the search results interface has loaded.
	Query for the search results container.
	Wait until the master engine exists, then reuse it.
	Initialize the search results with the Engine initialized in `atomic-bootstrap.js`.
	The results page should execute the first search.

This pattern allows the search box to dynamically change its behaviour—from a standalone search box to a regular search box—based on the content of the page.