---
title: Use hierarchical facets
slug: '2667'
canonical_url: https://docs.coveo.com/en/2667/
collection: javascript-search-framework
source_format: adoc
---
# Use hierarchical facets

[jsui-new Coveo JavaScript Search Framework v2.5395.12]


If some [items](https://docs.coveo.com/en/210/) in your [index](https://docs.coveo.com/en/204/) follow a logical hierarchical structure, you may want to display a [facet](https://docs.coveo.com/en/198/) that allows end users to navigate your item hierarchy accordingly.
This article explains how to use the [`DynamicHierarchicalFacet`](https://coveo.github.io/search-ui/components/dynamichierarchicalfacet.html) (or the [`CategoryFacet`](https://coveo.github.io/search-ui/components/categoryfacet.html)) component to do so.

> **Note**
>
> The `DynamicHierarchicalFacet` component is available since the [January 2020 release (v2.7968)](https://docs.coveo.com/en/m54e5269#january-2020-release-v27968).
> 
> This component works in a similar fashion to the older `CategoryFacet` component.
> However, the `DynamicHierarchicalFacet` is preferred as it supports the [Coveo Machine Learning](https://docs.coveo.com/en/188/) [Dynamic Navigation Experience (DNE)](https://docs.coveo.com/en/2907/) feature.

To use the `DynamicHierarchicalFacet` (or `CategoryFacet`) component in a search interface

. Ensure that your index contains [field](https://docs.coveo.com/en/200/) with the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) enabled and representing the item hierarchy.
The field values must have the following form `the;the|path;the|path|to;the|path|to|given;the|path|to|given|item;`, where the delimiting character is `|`.
. Include the component in your HTML page.


**Example**

You have indexed the following file system:

```text
c:\
user1\
   folder1\
      text1.txt
   folder2\
      text2.txt
      folder3\
      text3.txt
```

The `@parentfolders` contains values representing the path to each of those items in the file system hierarchy.
|===
| Item | `@parentfolders` field value

| text1.txt
| `c;c\|user1;c\|user1\|folder1;`

| text2.txt
| `c;c\|user1;c\|user1\|folder2;`

| text3.txt
| `c;c\|user1;c\|user1\|folder2;c\|user1\|folder2\|folder3;`
|===

In your search page, you include the `CoveoDynamicHierarchicalFacet` component.

```html
<div class="CoveoDynamicHierarchicalFacet" data-title="Folder"
     data-field="@parentfolders"></div>
```

## Navigating and filtering

You can only select one value at a time in a hierarchical facet.
This is because those facets are meant to ease navigation through hierarchically organized content (for example, exploring product categories), as opposed to applying multiple hierarchical filters.

**Example**

You have a search page for your store, where you sell electronics and office supplies.
You use a hierarchical facet titled **Product Category** on the `@productcategory` multi-value field.
This allows your end users to navigate the product hierarchy.

To refine result filtering, create [dependent facets on the target hierarchical facet values](https://docs.coveo.com/en/3210#example-3-display-a-facet-only-when-a-specific-hierarchical-value-is-selected-in-its-parent).

**Example**

You want the **Brand** facet to show when users select **paper** in your hierarchical facet, and you want the **Pen Type** facet to show when users select **pen** in your hierarchical facet.

```html
<div id="search" class="CoveoSearchInterface">
  <!-- ... -->
  <div class="coveo-facet-column">
      <div class="CoveoDynamicHierarchicalFacet"
         data-title="Product Category"
         data-field="@productcategory"></div>
      <div id="brand_facet"
         class="CoveoDynamicFacet"
         data-title="Brand"
         data-field="@brand"></div>
      <div id="pentype_facet"
         class="CoveoDynamicFacet"
         data-title="Pen Type"
         data-field="@pentype"></div>
  </div>
  <!-- ... -->
</div>
```

```html
<script>
   // ...
   document.addEventListener('DOMContentLoaded', function () {
      // ...
      const root = document.getElementById("search");
      function isSelectedInParent(value) {
         return (parentFacet) => {
            const id = parentFacet.options.id;
            const selected = parentFacet.queryStateModel.get(`f:${id}`);
            return selected.includes(value);
         }
      }
      Coveo.init(root, {
         brand_facet: {
            dependsOn: "@productcategory",
            dependsOnCondition: isSelectedInParent("paper")
         },
         pentype_facet: {
            dependsOn: "@productcategory",
            dependsOnCondition: isSelectedInParent("pen")
         }
      });
   });
</script>
```

## Setting the base path

> **Note**
>
> The `DynamicHierarchicalFacet` supports the [`basePath`](https://coveo.github.io/search-ui/components/dynamichierarchicalfacet.html#options.basepath) option since the [April 2020 release (v2.8864)](https://docs.coveo.com/en/m54e5269#2-8864).

When all items in a hierarchical relationship resolve to a unique common ancestor, you may want to use the [`basePath`](https://coveo.github.io/search-ui/components/categoryfacet.html#options.basepath) option of the `CategoryFacet` component to eliminate this redundancy.

```html
<div class="CoveoCategoryFacet" data-title="Folder"
     data-field="@parentfolders" data-base-path="c,user1"></div>
```



> **Note**
>
> pass:a[<span class="tag c4sf-edition" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Applicable Coveo for Salesforce Edition(s)"><a href="https://docs.coveo.com/en/l2590456/#salesforce-service-solutions">Pro and Enterprise editions only</a></span>]
> 
> When using [Data Categories](https://help.salesforce.com/articleView?id=category_whatis.htm&type=5) in Coveo for Salesforce, you can add the [`basePath`](https://coveo.github.io/search-ui/components/categoryfacet.html#options.basepath) option in the `CoveoCategoryFacet` element to start counting your fields at the second level, which is the `folder` field.