Integrate a search page into your commerce solution

This is for:

Developer

In this article

Example code
Including the Atomic library resources
Initializing the Atomic search interface
Building your search interface
What’s next?

This article serves as an introduction and high-level guide to creating a search interface with the Coveo Atomic library.

Example code

You can quickly build a minimal search interface using just a few dozen lines of HTML code:

<!DOCTYPE html>
<html 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>
        (async () => {
        await customElements.whenDefined('atomic-search-interface');
        const searchInterface = document.querySelector('#search');

        await searchInterface.initialize({
            accessToken:'<ACCESS_TOKEN>',
            // Replace with an API key or search token that grants the privileges to execute queries and push usage analytics data.
            organizationId: '<ORGANIZATION_ID>',
            organizationEndpoints: await searchInterface.getOrganizationEndpoints('<ORGANIZATION_ID>')
            // Replace with your actual organization ID.
        });

        searchInterface.executeFirstSearch();
        })();
    </script>
    <!-- ... -->
    </head>
    <body>
        <atomic-search-interface search-hub="<SEARCH_HUB>">
            <atomic-search-layout mobile-breakpoint="800px">
                <atomic-layout-section section="search">
                    <atomic-search-box></atomic-search-box>
                </atomic-layout-section>

                <atomic-layout-section section="facets">
                    <atomic-facet-manager>
                        <atomic-facet field="cat_gender" label="Gender"></atomic-facet>
                        <atomic-facet field="store_name" label="Store"></atomic-facet>
                        <!-- ... -->
                    </atomic-facet-manager>
                </atomic-layout-section>

                <atomic-layout-section section="main">
                    <!-- ... -->
                    <atomic-layout-section section="results">
                        <atomic-result-list image-size="large" display="grid">
                            <atomic-result-template>
                                .
                                .
                                .
                            </atomic-result-template>
                        </atomic-result-list>
                    </atomic-layout-section>
                    <atomic-layout-section section="pagination" style="flex-direction: column">
                        <atomic-results-per-page choices-displayed="3,5,8,10"></atomic-results-per-page>
                        <atomic-load-more-results></atomic-load-more-results>
                    </atomic-layout-section>
                </atomic-layout-section>
            </atomic-search-layout>
        </atomic-search-interface>
    </body>
</html>

The rest of this article dissects and analyzes the various sections of the above code sample.

Including the Atomic library resources

To use the Atomic library, link the following two files in the <head> of the page (see install the Atomic library):

<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"/>

	The main Atomic script.
	The default Atomic stylesheet. While this import is optional, if you don’t import it you’ll need to define its variables yourself.

Initializing the Atomic search interface

Before you can begin searching content, you must connect your search page to your Coveo organization. Do so within the <head> tag of the search page.

<head>
  <!-- ... -->
  <script>
    (async () => {
      await customElements.whenDefined('atomic-search-interface');
      const searchInterface = document.querySelector('#search');

      await searchInterface.initialize({
        accessToken:'<ACCESS_TOKEN>', 
        organizationId: '<ORGANIZATION_ID>' 
        organizationEndpoints: await searchInterface.getOrganizationEndpoints('<ORGANIZATION_ID>'),
      });

      searchInterface.executeFirstSearch();
    })();
  </script>
  <!-- ... -->
</head>

<ACCESS_TOKEN> (string) is an API key or search token that grants the Allowed access level on the Execute Queries domain, as well as the Push access level on the Analytics Data domain in the target organization.

We strongly recommend that the access token enforces a searchHub value. See Defining the search hub in the authentication for more details.

<ORGANIZATION_ID> (string) is the unique identifier of your Coveo organization (e.g., mycoveoorganizationa1b23c).

Use organization specific endpoints to simplify deployments and increase resiliency.

API key for search

Requests to the Search API and to Coveo Usage Analytics (Coveo UA) must be authenticated with either a search token or an API key you created for your catalog. This lets you retrieve results for search pages, product listings, or recommendations.

Leading practice

While you can authenticate requests to the Search API using an API key, we recommend using a search token for enhanced security.

Search tokens automatically expire after 24 hours, limiting unauthorized use.

Additionally, search tokens offer precise control over access to specific products, prices, or content, ensuring only authorized users see relevant information.

While setting up tokens may involve more initial effort than generating API keys, it provides tailored access control and safeguards sensitive content. However, if your use case doesn’t require user-specific content or enhanced security through token expiration, API keys may suffice.

If you opt for the API key approach, ensure you’re aware of the leading practices regarding API keys.

To create an API key for search:

On the Catalogs (platform-ca | platform-eu | platform-au) page, click the catalog for which you want to create an API key, and then click Create API Key in the Action bar.
Select an API key for Search.
Click Create Key.

The created API key value is unique. It’s impossible to view the value more than once.

If you fail to get the value, delete the lost key and create a new one.
We strongly recommend that the API key enforces a searchHub value. See Defining the search hub in the authentication for more details.

Building your search interface

A Coveo Atomic search interface builds search pages by attaching components to target HTML elements. These components add functionality to your search interface. Some of the important components are highlighted in the example below.

<body>
    <atomic-search-interface search-hub="<SEARCH_HUB>"> 
      <atomic-search-layout mobile-breakpoint="800px">
        <atomic-layout-section section="search">
          <atomic-search-box></atomic-search-box> 
        </atomic-layout-section>

        <atomic-layout-section section="facets">
          <atomic-facet-manager> 
            <atomic-facet field="cat_gender" label="Gender"></atomic-facet>
            <atomic-facet field="store_name" label="Store"></atomic-facet>
            <!-- ... -->
          </atomic-facet-manager>
        </atomic-layout-section>

        <atomic-layout-section section="main">
          <!-- ... -->
          <atomic-layout-section section="results">
            <atomic-result-list image-size="large" display="grid">
                <atomic-result-template> 
                    .
                    .
                    .
                </atomic-result-template>
            </atomic-result-list>
          </atomic-layout-section>
          <atomic-layout-section section="pagination" style="flex-direction: column">
            <atomic-results-per-page choices-displayed="3,5,8,10"></atomic-results-per-page> 
            <atomic-load-more-results></atomic-load-more-results> 
          </atomic-layout-section>
        </atomic-layout-section>
      </atomic-search-layout>
    </atomic-search-interface>
</body>

Some essential components include:

Atomic component Description

Atomic component	Description
1. atomic-search-interface	The parent of all other atomic components in the search page. `<atomic-search-interface></atomic-search-interface>` Notice that this is where you would define a `<SEARCH-HUB>` to name your component (e.g., `my search hub`). This value is used as your interface’s identifier and will be sent along with each queries and usage analytics events originating from this component. See About the search hub for more information on search hubs.
2. atomic-search-layout	Helps organize elements on the search page. Has the `mobileBreakpoint` property which specifies when layout switches from mobile to desktop. `<atomic-search-layout></atomic-search-layout>`
3. atomic-layout-section	Allows the identification of various sections of an Atomic page. Acts as a container `<atomic-layout-section section="search"></atomic-layout-section>`
4. atomic-facet-manager	Helps reorder facets. Acts as a container for facet components. `<atomic-facet-manager></atomic-facet-manager>`
5. atomic-facet	Displays a list of values for a specific field occurring in the results `<atomic-facet field="author" label="Authors"></atomic-facet>`
6. atomic-result-list	Responsible for displaying query results. `<atomic-result-list></atomic-result-list>`

1. atomic-search-interface

The parent of all other atomic components in the search page.

<atomic-search-interface></atomic-search-interface>

Notice that this is where you would define a <SEARCH-HUB> to name your component (e.g., my search hub). This value is used as your interface’s identifier and will be sent along with each queries and usage analytics events originating from this component. See About the search hub for more information on search hubs.

2. atomic-search-layout

Helps organize elements on the search page. Has the mobileBreakpoint property which specifies when layout switches from mobile to desktop.

<atomic-search-layout></atomic-search-layout>

3. atomic-layout-section

Allows the identification of various sections of an Atomic page. Acts as a container

<atomic-layout-section section="search"></atomic-layout-section>

4. atomic-facet-manager

Helps reorder facets. Acts as a container for facet components.

<atomic-facet-manager></atomic-facet-manager>

5. atomic-facet

Displays a list of values for a specific field occurring in the results

<atomic-facet field="author" label="Authors"></atomic-facet>

6. atomic-result-list

Responsible for displaying query results.

<atomic-result-list></atomic-result-list>

There’s another essential functionality which isn’t visible in the search interface example provided above: Atomic Usage Analytics. Atomic records usage analytics events performed in the search interface to feed Coveo Machine Learning (Coveo ML) models and to create UA reports.

For more details, to customize or send your own UA events, see Atomic Usage Analytics.

What’s next?

You now have a general understanding of how to configure a Coveo-powered search interface using the Atomic library.

You may want to follow up by going through the Coveo Atomic Tutorial to better familiarize yourself with its concepts, components, functions, and methods.

You may also want to create a standalone search box to provide relevant search throughout your ecommerce solution or website.

For more examples, have a look at the interactive ones below: