Build search interfaces

This is for:

Developer

In this article

Prerequisite
Code Sample
Search page
Search box component

Atomic for Commerce components are in open beta and remain under active development.

Atomic for Commerce hasn’t yet gone through a formal accessibility review. If you have accessibility needs, contact your Account Manager and we’ll work with you to address them.

All commerce search interfaces in Atomic use the atomic-commerce-search-box component, which is the main building block that provides search box functionality. To work properly, it must be placed inside a atomic-commerce-interface with the type attribute set to search (the default value).

Prerequisite

Make sure that you understand how to build commerce search pages.

Code Sample

Following is a minimal example of a search interface built with Atomic for Commerce. This uses getSampleCommerceEngineConfiguration from @coveo/headless/commerce for its configuration. This won’t work in a production environment.

For a detailed breakdown of how to configure your search interface, refer to the Coveo Headless documentation for CommerceEngineConfiguration.

You can find a complete example of a search interface in Storybook.

<html>
  <head>
    <title>Example Search Page</title>
      <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">
      (async () => {
        const {
          getSampleCommerceEngineConfiguration
        } = await import('http://static.cloud.coveo.com/headless/v3/commerce/headless.esm.js'); 

        const siteRoot = 'https://www.example.com/';
        const siteConfig = {
          'Example Search Page': {
            href: 'index.html',
            label: 'Example Home',
            resourceUrl: `${siteRoot}/search` 
          },
        };

        const {context, ...restOfConfiguration} = getSampleCommerceEngineConfiguration(); 
        const configuration = {
            context: {
              ...context,
              view: {
                url: siteConfig[document.title]?.resourceUrl,
              },
            },
            ...restOfConfiguration,
        };

        await customElements.whenDefined('atomic-commerce-interface');
        const commerceInterface = document.querySelector('atomic-commerce-interface');
        await commerceInterface.initialize(configuration); 
        commerceInterface.executeFirstRequest();
      })();
    </script>
  </head>
  <body>
    <atomic-commerce-interface>
      <atomic-commerce-layout>
        <atomic-layout-section section="search">
          <atomic-commerce-search-box></atomic-commerce-search-box> 
        </atomic-layout-section>
        <atomic-layout-section section="main">
          <atomic-layout-section section="products">
            <atomic-commerce-product-list
              display="grid"
              density="compact"
              image-size="small"
            ></atomic-commerce-product-list>
            <atomic-commerce-query-error></atomic-commerce-query-error>
          </atomic-layout-section>
      </atomic-commerce-layout>
    </atomic-commerce-interface>
  </body>
</html>

	Import the Atomic library. This is responsible for handling the web components.
	Link the Coveo theme stylesheet. This provides the default styling for the web components.
	Import the Headless for Commerce library to get the sample configuration. When providing your own configuration you won’t need to import this function.
	The `resourceUrl` as shown defines the resources for the Coveo integration. These must exist and be configured in your Coveo organization's Coveo Merchandising Hub.
	Refer to the Coveo Headless documentation for `CommerceEngineConfiguration` for all configuration options.
	Initialize the `atomic-commerce-interface`.
	The search box for the interface. For additional options refer to Search box component.

Search page

A search page typically consists of a search box and a list of product results, as well as components to filter and navigate the results. Once you know how to build a search box, you can start building a search page. Here is a list of useful Atomic components that can be added to a commerce search page:

atomic-commerce-product-list: This component fetches and displays products.
atomic-commerce-facets: This component renders facets that let users filter results by category or by attributes such as product price or color.
atomic-commerce-sort-dropdown: This component renders a dropdown that lets users choose how to sort query results, such as by relevance, date, or product price.
atomic-commerce-pager: This component renders a pager that lets users navigate through paginated product results.
atomic-commerce-query-summary: This component displays information about the current set of products being shown, such as 'Products 1-10 of 123'.

The search box component is the core of your search interface. It lets users perform product searches by typing and submitting a query. It features built-in support for query suggestions and optional redirection to a search page. For the best user experience, the search box should be clearly visible, typically placed in the upper-center or upper-right section of a page.

You can add the following components as children of the atomic-commerce-search-box component:

atomic-commerce-search-box-query-suggestions: This component displays query suggestions as the user types.
atomic-commerce-search-box-instant-products: This component displays instant products as the user types.
atomic-commerce-search-box-recent-queries: This component displays recent queries as the user types.

When using the atomic-commerce-search-box component on non-search pages, you can add the redirection-url property to create a standalone search box. The search box will redirect users to a results page when they submit a query.

Before redirecting, the component writes the submitted query to the coveo-standalone-search-box-data local storage entry, which the destination page’s atomic-commerce-interface reads as its first query. If you replace the standalone search box with one of your own, it must pass the submitted query along in the same way, or in the URL fragment as the Headless standalone search box does. Otherwise, the destination page runs its first search with the default, empty query.