Upgrade from v1 to v2

This is for:

Developer
In this article

Atomic v2 introduces changes that improve the library’s performance, make it easier to use, and let you scale projects by supporting additional use cases.

Important
The following are breaking changes from Atomic v1 to v2

Renamed Variables

This section lists variables that were renamed without changes to the underlying functionality.

atomic-result-list

The image attribute has been renamed to image-size.

Atomic Version 1

<atomic-result-list image="small"></atomic-result-list>

Atomic Version 2

<atomic-result-list image-size="small"></atomic-result-list>

atomic-result

The image attribute has been renamed to image-size.

Atomic Version 1

<atomic-result image="small"></atomic-result>

Atomic Version 2

<atomic-result image-size="small"></atomic-result>

atomic-rating-facet:

  • The atomic-rating-facet-icon-active-color CSS variable has been renamed to atomic-rating-icon-active-color.

  • The atomic-rating-facet-icon-inactive-color CSS variable has been renamed to atomic-rating-icon-inactive-color.

Atomic Version 1

:root {
    --atomic-rating-facet-icon-active-color: blue;
    --atomic-rating-facet-icon-inactive-color: black;
}

Atomic Version 2

:root {
    --atomic-rating-icon-active-color: blue;
    --atomic-rating-icon-inactive-color: black;
}

atomic-refine-modal:

  • The select-icon CSS part has been renamed to select-icon-wrapper.

  • The select-icon-size CSS part has been renamed to select-icon.

Atomic Version 1

<style>
    atomic-refine-modal::part(select-icon) {
        position: absolute;
    }
    atomic-refine-modal::part(select-icon-size) {
        width: 1.5rem;
    }
</style>

Atomic Version 2

 <style>
    atomic-refine-modal::part(select-icon-wrapper) {
        position: absolute;
    }
    atomic-refine-modal::part(select-icon) {
        width: 1.5rem;
    }
</style>

Changes

CDN

https://static.cloud.coveo.com/atomic/latest/* resources will no longer be updated (also, using this wasn’t recommended). To follow updates, rather specify a version, such as in https://static.cloud.coveo.com/atomic/v2/*.

Atomic Version 1

<script
    type="module"
    src="https://static.cloud.coveo.com/atomic/latest/atomic.esm.js"
></script>
<link
    rel="stylesheet"
    href="https://static.cloud.coveo.com/atomic/latest/themes/coveo.css"
/>

Or

<script
    type="module"
    src="https://static.cloud.coveo.com/atomic/v1/atomic.esm.js"
></script>
<link
    rel="stylesheet"
    href="https://static.cloud.coveo.com/atomic/v1/themes/coveo.css"
/>

Atomic Version 2

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

NPM

Headless is no longer included in the Atomic npm package, you must install it yourself if you refer to Headless, otherwise you’ll receive an error warning you of missing dependencies.

Atomic Version 1 Example

// package.json
"dependencies": {
    "@coveo/atomic": "^1.123.0",
},
// ...
// app.tsx
import {
  getSampleSearchEngineConfiguration,
  SearchEngine,
} from '@coveo/atomic/headless';
// ...

Atomic Version 2 Example

// package.json
"dependencies": {
    "@coveo/atomic": "^2.0.1",
    "@coveo/headless": "^2.0.1",
},
// ...
// app.tsx
import {
  getSampleSearchEngineConfiguration,
  SearchEngine,
} from '@coveo/headless';
// ...

Headless is still packaged as part of the Atomic CDN link, so there is no difference in that case.

atomic-result-list and atomic-folded-result-list

The fields-to-include were removed from atomic-result-list and atomic-folded-result-list. Use the fields-to-include in atomic-search-interface instead.

Also, the values must now be specified as JSON/JSX/Angular Template, as you can see in the next section.

Atomic Version 1 Example

<atomic-search-interface>
    <!-- ... -->
    <atomic-result-list fields-to-include="in progress,completed"></atomic-result-list>
    <!-- ... -->
</atomic-search-interface>

Atomic Version 2 Examples

Atomic:

<atomic-search-interface fields-to-include='["in progress", "completed"]'>
    <!-- ... -->
    <atomic-result-list></atomic-result-list>
    <!-- ... -->
</atomic-search-interface>

Atomic React wrapper:

<AtomicSearchInterface fieldsToInclude={["in progress", "completed"]}>
    {/* ... */}
    <AtomicResultList></AtomicResultList>
    {/* ... */}
</AtomicSearchInterface>

Atomic Angular wrapper:

<atomic-search-interface fields-to-include="['in progress', 'completed']">
    <!-- ... -->
    <atomic-result-list></atomic-result-list>
    <!-- ... -->
</atomic-search-interface>

Attributes: String to JSON/JSX/Angular Template

The following attributes were modified to support only JSON, JSX, or Angular templates as parameters rather than comma-separated strings.

Atomic Version 1 Example

<atomic-facet allowed-values="in progress,completed"></atomic-facet>

Atomic Version 2 Examples

Atomic:

<atomic-facet allowed-values='["in progress", "completed"]'></atomic-facet>

Atomic React wrapper:

<AtomicFacet allowedValues={["in progress", "completed"]}></AtomicFacet>

Atomic Angular wrapper:

<atomic-facet allowed-values="['in progress', 'completed']"></atomic-facet>

atomic-query-summary

The atomic-query-summary enable-duration attribute has been removed. Use the duration CSS part instead.

Atomic Version 1

<atomic-query-summary enable-duration="true"></atomic-query-summary>

Atomic Version 2

<!-- html -->
<atomic-query-summary></atomic-query-summary>
<!-- CSS -->
atomic-query-summary::part(duration) {
  display: inline;
}

atomic-result

The engine property, which was unused, has been removed.

The interactiveResult property is now required. It was and still is undocumented and for internal use only, but if you were using it you should know that it now takes an InteractiveResult controller as a value, which you can build using buildInteractiveResult.

atomic-category-facet Styling

To improve accessibility, the skeleton of category facets was completely revamped to be hierarchical. In Atomic v1, the list of parents was separate from the list of children.

ul[part="parents"]
    li > button[part="parent-button"]{All categories}
    li > button[part="parent-button"]{Computers & Tablets}
    li > button[part="parent-button"]{Computer Accessories & Peripherals}
    li > button[part="parent-button"]{Laptop Accessories}
    li > button[part="active-parent"]{Laptop Bags & Cases}
ul[part="values"]
    li > button[part="value-link"]{Laptop Backpacks}
    li > button[part="value-link"]{Laptop Sleeves}
    li > button[part="value-link"]{Laptop Briefcases}
    li > button[part="value-link"]{Laptop Hard-Shell Cases}
    li > button[part="value-link"]{Laptop Messenger Bags}

In Atomic v2, the values are organized hierarchically.

[part="parents"]
    button[part="all-categories-button"]{All categories}
    [part="sub-parents"]
        button[part="parent-button"]{Computers & Tablets}
        [part="sub-parents"]
            button[part="parent-button"]{Computer Accessories & Peripherals}
            [part="sub-parents"]
                button[part="parent-button"]{Laptop Accessories}
                [part="sub-parents"]
                    button[part="active-parent"]{Laptop Bags & Cases}
                    [part="values"]
                        button[part="value-link"]{Laptop Backpacks}
                        button[part="value-link"]{Laptop Sleeves}
                        button[part="value-link"]{Laptop Briefcases}
                        button[part="value-link"]{Laptop Hard-Shell Cases}
                        button[part="value-link"]{Laptop Messenger Bags}

You need to use the new hierarchy when styling your category facets.

Atomic Version 1

li:first-child::part(parent-button) {
    font-size: 1.5rem;
}

Atomic Version 2

atomic-category-facet::part(all-categories-button) {
    font-size: 1.5rem;
}

The target attribute has been removed from atomic-result-link and atomic-result-printable-uri. Instead, use the attributes slot.

Atomic Version 1

<atomic-result-link target="_blank">
</atomic-result-link>

Atomic Version 2

<atomic-result-link>
  <a slot="attributes" target="_blank"></a>
</atomic-result-link>

Result sections

We strongly recommend against combining result section and non-result section elements at the root of a template. If you declare the template using pure HTML (that is, no JavaScript, JSX nor Angular templating) and mix result sections with non-result sections, Atomic logs a console warning.

'Result templates should only contain section elements or non-section elements. Future updates could unpredictably affect this result template.'

atomic-insight-result

This component was and is undocumented and meant for internal purposes, but if you were using it, the following are the changes.

The atomic-insight-result engine: InsightEngine attribute has been removed.

The atomic-insight-result interactive-result: InsightInteractiveResult attribute is now required.

The search box now exposes a --atomic-layout-max-search-box-input-width CSS variable, which limits search box width by default.

The search suggestions can now expand horizontally beyond the search box. You can adjust the width using the following CSS variables:

  • --atomic-layout-max-search-box-double-suggestions-width

  • --atomic-layout-search-box-left-suggestions-width

Atomic Version 2 Example

:root {
    --atomic-layout-max-search-box-double-suggestions-width: 700px;
    --atomic-layout-search-box-left-suggestions-width: 300px;
}
Note

A case where you can see two suggestion panels is when implementing instant results.

URL Serializing

The hash in the URL representing the state of the search page now serializes facets with a dash instead of brackets.

For instance, f[my-facet]=valueA,valueB in v1 is serialized as f-my-facet=valueA,valueB in v2.

Atomic generally handles URL serialization by itself, so the changes should be transparent, unless you were leveraging the URL directly somehow, for example by linking to your search page with preselected facets.

Atomic Version 1 Example

<a href="https://mysite.com/search/#f[country]=canada"></a>

Atomic Version 2 Example

<a href="https://mysite.com/search/#f-country=canada"></a>

Atomic React Wrapper

The theme attribute of the AtomicSearchInterface component has been removed.

The theme attribute of the AtomicRecsInterface component has been removed.

Atomic Version 1

<!-- index.html -->
<!-- ... -->
<AtomicSearchInterface engine={this.engine} theme="coveo">
<!-- ... -->

Atomic Version 2

Instead, import the target prebuilt theme directly.

<!-- index.html -->
<!-- ... -->
<link
    rel="stylesheet"
    href="https://static.cloud.coveo.com/atomic/v2/themes/coveo.css"
/>
<!-- ... -->
<AtomicSearchInterface engine={this.engine}>
<!-- ... -->