THIS IS ARCHIVED DOCUMENTATION

Usage (Deprecated)

The Coveo Atomic library provides you with a customizable set of UI components that are already configured to communicate with the Coveo Platform. These web components, which are built on top of the Coveo Headless library, can be used with or without existing frameworks.

Notes

This article provides an overview of the core Atomic concepts.

Install Atomic

CDN

The simplest way to get the Atomic component library is through a content delivery network (CDN).

Include the following scripts in the target HTML page:

<script
    type="module"
    src="https://static.cloud.coveo.com/atomic/v1/atomic.esm.js">
</script> 1
<link
    rel="stylesheet"
    href="https://static.cloud.coveo.com/atomic/v1/themes/coveo.css"/> 2
1 The main framework script.
2 The default stylesheet for the framework. While this import is optional, if you don’t import it you’ll need to define its variables yourself.

CDN links are available for the following versions of Atomic releases:

Major: https://static.cloud.coveo.com/atomic/v1/atomic.esm.js

Recommended for development and QA environment purposes. It’s a rather safe way to always have recent features from minor version updates, while not having major breaking changes.

Minor: https://static.cloud.coveo.com/atomic/v1.0/atomic.esm.js

Recommended for production and any customer-facing app. Minor version updates are mostly bug fixes; pointing to a minor version is safe and retrieves patches instantly.

NPM

The library is also available as an npm package.

npm install @coveo/atomic

All of the resources will be available under /node_modules/@coveo/atomic/dist/atomic. You can include those in target pages with <script> tags.

If you’re using a module bundler (Browserify, Webpack, Rollup, etc.), you can use require('@coveo/atomic') or import '@coveo/atomic'.

Use Components to Create a Search Interface

Atomic builds search pages by attaching components to target HTML elements.

This means that you can build your search page by assembling the target HTML elements:

<body>
  <atomic-search-interface id="search">
    <atomic-search-box></atomic-search-box>
    <atomic-facet-manager>
      <atomic-facet field="author" label="Authors"></atomic-facet>
      <!-- ... -->
    </atomic-facet-manager>
    <!-- ... -->
  </atomic-search-interface>
</body>

To turn these HTML elements into real Atomic components, you use a script to initialize the overarching atomic-search-interface component:

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

      await searchInterface.initialize({
        accessToken:'<ACCESS_TOKEN>', 1
        organizationId: '<ORGANIZATION_ID>' 2
      });
​
      searchInterface.executeFirstSearch();
    })();
  </script>
  <!-- ... -->
</head>
1 <ACCESS_TOKEN> (string) is a search token or an API key that grants the Allowed access level on the Execute Queries domain and the Push access level on the Analytics Data domain in the target organization.
2 <ORGANIZATION_ID> (string) is the unique identifier of your Coveo organization (for example, mycoveoorganizationa1b23c).

Some components expose options. For example, the following atomic-search-box component will offer a maximum of two queries when the user interacts with it:

<atomic-search-box number-of-queries="2"></atomic-search-box>

Some components also expose methods. The following code sample includes two methods exposed by the atomic-search-interface component:

const searchInterface = document.querySelector("atomic-search-interface");

await searchInterface.initialize({
  accessToken: "xx564559b1-0045-48e1-953c-3addd1ee4457",
  organizationId: "searchuisamples"
}); 1

searchInterface.executeFirstSearch(); 2
1 The initialize method is used to initialize the search interface. In this case, the await operator is used to wait for the interface to finish its initialization before moving on.
2 The executeFirstSearch method is used to trigger a search after the search interface has been initialized.

Style Your Components

Atomic uses shadow DOM to instantiate components. This encapsulates a specific section of the DOM to allow for componentization, meaning that the component style is independent from the surrounding DOM styling. As such, you must style those components using their shadow DOM parts. For example:

<style>
  atomic-facet::part(label-button) {
    justify-content: center;
    padding-bottom: 1rem;
    border-bottom: 2px solid var(--atomic-neutral)
  }
</style>

For more detailed guide on how to customize your components, please refer to this article.

What’s Next?

Result templates determine the format of the individual query results in a search interface. When a query is successful, each result is rendered according to the first template whose condition is satisfied by that result.

Atomic currently provides one default template for all result types. More will be added in the future.

You can also create your own result templates with custom styles (see Defining a result template). To learn more, see Defining a Result Template.