Atomic for commerce

This is for:

Developer
Important

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.

What’s Coveo Atomic for commerce?

Coveo Atomic is a web component library for assembling responsive, accessible, and future-proof Coveo-powered product discovery interfaces. Atomic components are self-encapsulated, composable, and lightweight. Under the hood, Atomic relies on the Coveo Headless library to interface with the Coveo Platform and handle application state.

In the context of Coveo for Commerce, Atomic is used in conjunction with the Coveo Merchandising Hub (CMH) to power your product discovery interfaces. As Atomic is built upon Headless, it relies on the Commerce API to query products from Coveo and the Event Protocol to send analytics events to Coveo.

Notes

When should I use Atomic?

Atomic is an ideal option to assemble a feature-rich Coveo-powered product discovery interface without having to implement all its UI components. It’s the recommended starting point for a new commerce implementation, as it covers search, product listings, facets, and recommendations out of the box.

To build every component of your product discovery interface yourself, or to integrate with an existing design system, use Coveo Headless for commerce instead. If only part of your interface needs that level of control, you can use both libraries together rather than choosing one.

If you’re using either React or Angular, consider using Atomic React or Atomic Angular. They’re wrappers around Atomic that make it easier to use Atomic for commerce components.

Use Atomic and Headless together

Atomic for commerce and Headless for commerce aren’t mutually exclusive. Atomic components are built on Headless, so both libraries read and write the state of the same commerce engine. A single implementation can use Atomic components for most of a storefront and Headless controllers for the pieces Atomic doesn’t cover, such as a cart or a product detail page. The commerce-hybrid sample demonstrates this approach with a Headless search box, cart, and product page in an Atomic storefront.

Choosing Atomic is therefore a two-way door. If a component falls short of what you need, you can build just that piece with Headless and keep every other Atomic component, rather than rewriting your whole interface.

Customize, compose, extend, or replace

Work down the following list and stop at the first approach that solves your problem. Each approach costs more to build and maintain than the one before it.

Need Approach

A different look, wording, behavior, or layout for an Atomic component

Customize the component through its attributes, ::part() selectors, CSS custom properties, slots, and product templates.

Custom UI around an Atomic component, such as a modal, a drawer, or a custom trigger

Compose around the component by wrapping it in your own markup, leaving the component itself untouched.

A capability that Atomic has no component for, such as a cart, a product detail page, or badges

Extend with Headless by building that piece with Headless controllers on the same commerce engine, keeping every Atomic component.

An Atomic component that can’t express a behavior you need, most often the search box

Replace that one component with your own, built with Headless controllers, keeping the rest of Atomic.

Full control of the entire experience, or an existing design system to integrate with

Use Headless for everything.

Before you replace a component, confirm that customizing it isn’t enough. The atomic-commerce-search-box component, for example, accepts custom suggestion providers through the public dispatchSearchBoxSuggestionsEvent, so adding a suggestion source on its own doesn’t require a replacement.

Integration points

The commerce engine is the entire integration surface. Initialize every commerce interface on the page with the same engine that your Headless controllers are built from, and both sides read and write the same state without knowing about each other.

Whether you replace an Atomic component or add one of your own, keep the following in mind:

  • Initialization order: atomic-commerce-interface installs its URL manager as the last step of initializeWithEngine. A query submitted before that promise resolves runs, but never reaches the address bar. Bind your own components only once initializeWithEngine resolves, and keep their inputs disabled until then.

  • Analytics: initializeWithEngine records @coveo/atomic as the analytics source on the engine, and events emitted by Headless controllers built from that engine carry the same source. The searches, cart updates, and product views coming from your own components are therefore attributed exactly like Atomic's own. Emit them only after the interfaces are initialized.

  • Styling: the ::part() hooks of the component you replaced no longer apply to your own markup. Style your components yourself, and use Atomic's theme CSS custom properties to keep them consistent with the components around them.

  • Components inside a product template: Atomic renders each product inside the shadow root of atomic-product, so your page stylesheets don’t reach a component placed in a product template. Such a component must carry its own styles, and inherits Atomic's theme through CSS custom properties. Use the fetchProductContext and initializeBindings helpers exported by @coveo/atomic to give it both its product and the interface’s engine.

  • Standalone search box: a search box of your own on a non-search page must pass the submitted query to the search page, which otherwise runs its first search with the default, empty query. Either write the coveo-standalone-search-box-data local storage entry, as the atomic-commerce-search-box standalone search box does, or redirect with the query in the URL fragment, as the Headless standalone search box does. The interface restores the fragment only while reflect-state-in-url is enabled.

  • Accessibility: the components you build are your responsibility, unlike the Atomic components around them. Route their screen reader announcements through the atomic-aria-live element that the interface already injects, so they queue with Atomic's own announcements instead of competing with them.

Where to start?

To learn about event tracking with Atomic for commerce, refer to Event tracking with Atomic.

To learn how to build a product discovery interface with Atomic, refer to the following articles:

The commerce-hybrid sample runs against a public sample organization, so you can clone and start it without any configuration.

You can review the Atomic commerce Storybook to see how the different components are implemented. Storybook is a front-end tool for showcasing UI components in isolation. Each story displays a different interactive component and contains documentation on how to use it.