Coveo Atomic's "Atomic-Category-Facet"

Breaking Down Coveo Atomic's "atomic-category-facet"

The speed at which Coveo Atomic is being developed is, so awesome. Crazy to think I'm one of those that remember how it was to wake up, get the newspaper on the front porch and open it up to see what crazy news is happening in the world. It honestly feels the same way. What new feature or change will be in the next version of Atomic.

In a previous article, we talked about the atomic-facet. Today, we're going to breakdown the atomic-category-facet. It might not seem that different from atomic-facet as a lot of the attributes are similar, but there are some key differences.

Think of atomic-category-facet as the new CoveoHierarchialFacet.


While this is very similar to the CoveoFacet of years past, it has some "upgrades" you could say in terms of how information can be presented. It's very powerful and very flexible out-of-the-box.

Attribute Description Values
field (required) The field in your source you want to use for the facet. string
label The facet heading. string
delimiting-character The character that separates values of a multi-value field. default ';'
facet-id Specifies a unique identifier for the facet. string | undefined
filter-by-base-path Whether to use basePath as a filter for the results. true (default) | false
filter-facet-count Whether to exclude the parents of folded results when estimating the result count for each facet value. true (default) | false
injection-depth The maximum number of results to scan in the index to ensure that the facet lists all potential facet values. Note: A high injectionDepth may negatively impact the facet request performance. Minimum: 0 1000 (default)
is-collapsed Specifies if the facet is collapsed. false (default) | true
number-of-values The number of values to request for this facet. Also determines the number of additional values to request each time more values are shown. 8 (default)
sort-criteria The sort criterion to apply to the returned facet values. Possible values are 'alphanumeric' and 'occurrences'. "alphanumeric" | "occurrences" (default)
with-search Whether this facet should contain a search box. When "true", the search is only enabled when more facet values are available. false (default) | true

Aside from the attributes of the component, Coveo has greatly expanded it's use of Shadow Parts for all the facets as of version 1.15.0. As such, you're able to style with greater detail.

You can find the full list of Shadow Parts here.

Let's check out an example of how we this component for a recent blog, Feel The Power Of Coveo's Generic Rest API.

The Example

How It Looks

Out of the box, the atomic-category-facet looks very similar to the atomic-facet. It behaves much like it when it's set to the "link" display type and as it's essentially a hierarchial facet, when you select the top level, it will open up to display all the children.

Due to acting like a "link" facet, you're only able to select a single facet value at a time. This prevents the issue in past hierarchial facets where by selecting one value, navigating up the tree and down another branch the user may forget what is selected.

Screenshot of Coveo Atomic search category facets

Upon clicking "TV", we can see that the entire view has been reduced just the parent, the child you selected along with the ability to select "All Categories".

Screenshot of Coveo Atomic search category facets

Selecting a sub facet value, other options are removed. To select another option, merely navigate to "All Categories" or up the tree.

Screenshot of Coveo Atomic search category facets and genres

How It's Configured

To get this to work, couldn't be easier. Have a look at the HTML used in creating this.


One thing you'll notice is we updated the delimiting-character value to be "|". This is purely because this is how we had it configured from the good'ole days.


Getting your facet information in the proper format is important. Like the Coveo Hierarchial Facet you will want to always start the structure with the parent. In our case, that was Movie.


As mentioned, when it comes to styling, you can use the Shadow Parts to select what you want to style. As Atomic is utilizing Tailwind CSS it will have various "group" capabilities for things like hover and focus. This way if you want to say, change the styling of the facet label and facet value, on mouse over, you can utilize the value-link part and it should group the descendants accordingly.

    --atomic-neutral-dark: red;  

Hey, Developers!

We're on the look out for talented developers to join our team.

Think you have what it takes?

Meet David Austin

Development Team Lead


David is a decorated Development Team Lead with Sitecore Technology MVP and Coveo MVP awards, as well as Sitecore CDP & Personalize Certified. He's worked in IT for 25 years; everything ranging from Developer to Business Analyst to Group Lead helping manage everything from Intranet and Internet sites to facility management and application support. David is a dedicated family man who loves to spend time with his girls. He's also an avid photographer and loves to explore new places.

Connect with David