# Coveo DynamicHierarchicalFacet Component (CoveoDynamicHierarchicalFacet)

The `DynamicHierarchicalFacet` component is a facet that renders values in a hierarchical fashion. It determines the filter to apply depending on the selected path of values.

This facet requires a `field` with a special format to work correctly.

Not supported in

  Coveo for Salesforce Free

Available since

  January 2020 Release (v2.7968)

Additional documentation

  Using Hierarchical Facets

## Index

### Methods

- collapse
- debugInfo
- disable
- enable
- enableFreezeFacetOrderFlag
- expand
- getBindings
- getCaption
- reset
- selectPath
- showLessValues
- showMoreValues
- toggleCollapse
- get

### Properties

- bind
- componentOptionsModel
- componentStateModel
- disabled
- logger
- queryController
- queryStateModel
- root
- searchInterface
- ID

### Accessors

- usageAnalytics

### Component Options

- basePath
- clearLabel
- collapsedByDefault
- customSort
- customSortDelimitingCharacter
- delimitingCharacter
- dependsOn
- dependsOnCondition
- enableCollapse
- enableFacetSearch
- enableMoreLess
- enableScrollToTop
- field
- filterFacetCount
- headingLevel
- id
- includeInBreadcrumb
- injectionDepth
- numberOfValues
- sortCriteria
- title
- valueCaption

### Constructors

- constructor

## Methods

### collapse

- collapse(): void

- - Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :648

  Collapses the facet, hiding values.

  #### Returns void

### debugInfo

- debugInfo(): any

- Inherited from BaseComponent.debugInfo

  - Defined in ui/Base/BaseComponent.ts :41

  Return the debug info about this component.

  #### Returns any

### disable

- disable(): void

- Inherited from BaseComponent.disable

  - Defined in ui/Base/BaseComponent.ts :52

  Disable the component. Normally this means that the component will not execute handlers for the framework events (query events, for example). Components are enabled by default on creation.

  #### Returns void

### enable

- enable(): void

- Inherited from BaseComponent.enable

  - Defined in ui/Base/BaseComponent.ts :61

  Enable the component. Normally this means that the component will execute handlers for the framework events (query events, for example). Components are enabled by default on creation.

  #### Returns void

### enableFreezeFacetOrderFlag

- enableFreezeFacetOrderFlag(): void

- - Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :637

  For this method to work, the component has to be the child of a DynamicFacetManager component.

  Sets a flag indicating whether the facets should be returned in their current order.

  Setting the flag to `true` helps ensuring that the facets do not move around while the end-user is interacting with them.

  The flag is automatically set back to `false` after a query is built.

  #### Returns void

### expand

- expand(): void

- - Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :615

  Expands the facet, displaying all of its currently fetched values.

  #### Returns void

### getBindings

- getBindings(): IComponentBindings

- Inherited from Component.getBindings

  - Defined in ui/Base/Component.ts :328

  Return the bindings, or environment, for the current component.

  #### Returns IComponentBindings

### getCaption

- getCaption(value: string): string

- - Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :671

  #### Parameters

  - ##### value: string

    The string to find a caption for. Returns the caption for a value or the value itself if no caption is available.

  #### Returns string

### reset

- reset(): void

- - Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :592

  Deselects the path in the facet.

  Does not trigger a query automatically. Does not update the visual of the facet until a query is performed.

  #### Returns void

### selectPath

- selectPath(path: string[]): void

- - Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :571

  Select a path in the hierarchy.

  Does not trigger a query automatically. Does not update the visual of the facet until a query is performed.

  #### Parameters

  - ##### path: string[]

    The values representing the path.

  #### Returns void

### showLessValues

- showLessValues(): void

- - Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :556

  Reduces the number of displayed facet values down to numberOfValues.

  See the `enableMoreLess` option.

  Automatically triggers an isolated query.

  #### Returns void

### showMoreValues

- showMoreValues(additionalNumberOfValues?: number): void

- - Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :542

  Requests additional values.

  See the `enableMoreLess` option.

  Automatically triggers an isolated query.

  #### Parameters

  - ##### Default value additionalNumberOfValues: number = this.options.numberOfValues

    The number of additional values to request. Minimum value is 1. Defaults to the numberOfValues option value.

  #### Returns void

### toggleCollapse

- toggleCollapse(): void

- - Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :608

  Collapses or expands the facet depending on it's current state.

  #### Returns void

### Static get

- get(element: HTMLElement, componentClass?: any, noThrow?: boolean): BaseComponent

- Inherited from Component.get

  - Defined in ui/Base/Component.ts :410

  Get the bound component to the given HTMLElement. Throws an assert if the HTMLElement has no component bound, unless using the noThrow argument.
  If there is multiple component bound to the current HTMLElement, you must specify the component class.

  #### Parameters

  - ##### element: HTMLElement

    HTMLElement for which to get the bound component.

  - ##### Optional componentClass: any

    Optional component class. If the HTMLElement has multiple components bound, you must specify which one you are targeting.

  - ##### Optional noThrow: boolean

    Boolean option to tell the method to not throw on error.

  #### Returns BaseComponent

## Properties

### bind

bind: ComponentEvents

Inherited from Component.bind

- Defined in ui/Base/Component.ts :270

Allows the component to bind events and execute them only when it is enabled.

type

  {Coveo.ComponentEvents}

### componentOptionsModel

componentOptionsModel: ComponentOptionsModel

Inherited from Component.componentOptionsModel

- Defined in ui/Base/Component.ts :294

Contains the state of options for different components. Mainly used by ResultLink.

### componentStateModel

componentStateModel: ComponentStateModel

Inherited from Component.componentStateModel

- Defined in ui/Base/Component.ts :282

Contains the state of different components (enabled vs disabled). Allows to get/set values. Triggers component state event when modified. Each component can listen to those events.

### disabled

disabled: boolean

Inherited from BaseComponent.disabled

- Defined in ui/Base/BaseComponent.ts :23

A disabled component will not participate in the query, or listen to ComponentEvents.

type

  {boolean}

### logger

logger: Logger

Inherited from BaseComponent.logger

- Defined in ui/Base/BaseComponent.ts :18

Allows component to log in the dev console.

### queryController

queryController: QueryController

Inherited from Component.queryController

- Defined in ui/Base/Component.ts :286

Contains the singleton that allows to trigger queries.

### queryStateModel

queryStateModel: QueryStateModel

Inherited from Component.queryStateModel

- Defined in ui/Base/Component.ts :278

Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.

### root

root: HTMLElement

Inherited from Component.root

- Defined in ui/Base/Component.ts :274

A reference to the root HTMLElement (the SearchInterface).

### searchInterface

searchInterface: SearchInterface

Inherited from Component.searchInterface

- Defined in ui/Base/Component.ts :290

A reference to the root of every component, the SearchInterface.

### Static ID

ID: string

Inherited from BaseComponent.ID

- Defined in ui/Base/BaseComponent.ts :28

The static ID that each component needs in order to be identified.
For example, SearchButton -> static ID: SearchButton -> className: CoveoSearchButton

## Accessors

### usageAnalytics

- get (): IAnalyticsClient

- Inherited from Component.usageAnalytics

  - Defined in ui/Base/Component.ts :343

  A reference to the Analytics.client.

  #### Returns IAnalyticsClient

## Component Options

### basePath

basePath: string[]

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :314

The base path shared by all values to display in the hierarchical facet.

If you set this option, the specified base path will always be active on the facet.

This implies that:

- The end user will not have to manually select the specified base path values.
- Values that do not have the specified base path will not be displayed in the facet.

Default

  `[]`

Available since

  April 2020 Release (v2.8864)

Markup configuration example(s) :

    data-base-path='electronics'
    data-base-path='electronics,laptops'

### clearLabel

clearLabel: string

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :296

The label to display to clear the facet when a value is selected.

Default value is the localized string for `AllCategories`.

Markup configuration example(s) :

    data-clear-label='Everything'

### collapsedByDefault

collapsedByDefault: boolean

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :126

Whether this facet should be collapsed by default.

Only effective when

  `enableCollapse` is truthy

Default

  `false`

Markup configuration example(s) :

    data-collapsed-by-default='true'
    data-collapsed-by-default='false'

### customSort

customSort: string

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :263

Specifies a custom order by which to sort the dynamic hierarchical facet values.

Custom-ordered values won't necessarily retrieve values from the index.

Example:

    <div
      class="CoveoDynamicHierarchicalFacet"
      data-field="@countries"
      data-title="Countries"
      data-tab="All"
      data-clear-label="All Countries"
      data-delimiting-character="|"
      data-custom-sort="America, Asia|Japan, America|Mexico, America|Canada, Europe|Germany, Europe|France, Oceania"
    ></div>

Markup configuration example(s) :

    data-custom-sort='foo'

### customSortDelimitingCharacter

customSortDelimitingCharacter: string

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :282

If a custom sort is defined, this specifies the delimiter that separates paths from each other.

*Example:**

    <div
      class="CoveoDynamicHierarchicalFacet"
      data-field="@countries"
      data-title="Countries"
      data-tab="All"
      data-clear-label="All Countries"
      data-delimiting-character="|"
      data-custom-sort="America...Asia|Japan...America|Mexico...America|Canada...Europe|Germany...Europe|France...Oceania"
      data-custom-sort-delimiting-character="..."
    ></div>

Only effective when

  `customSort` is truthy

Markup configuration example(s) :

    data-custom-sort-delimiting-character='foo'

### delimitingCharacter

delimitingCharacter: string

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :172

The character that specifies the hierarchical dependency.

Example:

If your field has the following values:

`electronics; electronics>laptops; electronics>laptops>gaming;`

The delimiting character is `>`.

Default

  `|`

Markup configuration example(s) :

    data-delimiting-character='>'

### dependsOn

dependsOn: string

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :190

The `id` option value of another facet in which at least one value must be selected in order for the dependent hierarchical facet to be visible.

Default: `undefined` and the hierarchical facet does not depend on any other facet to be displayed.

Additional documentation

  Defining Dependent Facets

Markup configuration example(s) :

    data-depends-on='department'

### dependsOnCondition

dependsOnCondition: IDependentFacetCondition

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :202

A function that verifies whether the current state of the `dependsOn` facet allows the dependent facet to be displayed.

If specified, the function receives a reference to the resolved `dependsOn` facet component instance as an argument, and must return a boolean. The function's argument should typically be treated as read-only.

By default, the dependent facet is displayed whenever one or more values are selected in its `dependsOn` facet.

Only effective when

  `dependsOn` is truthy

Additional documentation

  Defining Dependent Facets

### enableCollapse

enableCollapse: boolean

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :121

Whether to allow the end-user to expand and collapse this facet.

Default

  `true`

Markup configuration example(s) :

    data-enable-collapse='true'
    data-enable-collapse='false'

### enableFacetSearch

enableFacetSearch: boolean

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :157

Whether to allow the end-user to search the facet values.

Default

  `false`

Markup configuration example(s) :

    data-enable-facet-search='true'
    data-enable-facet-search='false'

### enableMoreLess

enableMoreLess: boolean

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :152

Whether to enable the More and Less buttons in the Facet.

See also the `numberOfValues` option.

Default

  `true`

Markup configuration example(s) :

    data-enable-more-less='true'
    data-enable-more-less='false'

### enableScrollToTop

enableScrollToTop: boolean

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :131

Whether to scroll back to the top of the page whenever the end-user interacts with a facet.

Default

  `true`

Markup configuration example(s) :

    data-enable-scroll-to-top='true'
    data-enable-scroll-to-top='false'

### field

field: IFieldOption

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :94

The index field whose values the facet should use. The field values should have the form: `the; the|path; the|path|to; the|path|to|given; the|path|to|given|item;` where the delimiting character is `|`. This default delimiting character can be changed using the delimitingCharacter option.

To help you verify whether your fields are setup correctly, use the `debugInfo` method.

Required

  Specifying a value for this option is required for the component to work

Additional documentation

  Using the Hierarchical Facet Component.

Markup configuration example(s) :

    data-field='@category'

### filterFacetCount

filterFacetCount: boolean

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :218

Whether to exclude folded result parents when estimating result counts for facet values.

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

See also the `Folding` and `FoldingForThread` components.

Default: `true`.

Markup configuration example(s) :

    data-filter-facet-count='true'
    data-filter-facet-count='false'

### headingLevel

headingLevel: number

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :323

The heading level to use for the heading above the facet.

A value of 0 will render a `div` element instead.

Default: `2`.

Minimum

  `0`

Maximum

  `6`

Default

  `2`

Markup configuration example(s) :

    data-heading-level='10'

### id

id: string

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :79

A unique identifier for the facet. Among other things, this identifier serves the purpose of saving the facet state in the URL hash.

If you have two facets with the same field on the same page, you should specify an `id` value for at least one of those two facets. This `id` must be unique among the facets.

Default value is the `field` option value.

Markup configuration example(s) :

    data-id='productcategory'

### includeInBreadcrumb

includeInBreadcrumb: boolean

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :136

Whether to notify the `Breadcrumb` component when toggling values in the facet.

Default

  `true`

Markup configuration example(s) :

    data-include-in-breadcrumb='true'
    data-include-in-breadcrumb='false'

### injectionDepth

injectionDepth: number

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :145

The number of items to scan for facet values.

Setting this option to a higher value may enhance the accuracy of facet value counts at the cost of slower query performance.

Minimum

  `1000`

Default

  `1000`

Markup configuration example(s) :

    data-injection-depth='1500'

### numberOfValues

numberOfValues: number

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :116

The maximum number of field values to display by default in the facet before the user clicks the arrow to show more.

See also the `enableMoreLess` option.

Minimum

  `0`

Default

  `5`

Markup configuration example(s) :

    data-number-of-values='8'

### sortCriteria

sortCriteria: "occurrences" | "alphanumeric"

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :229

The sort criterion to use for this facet.

Default (Search API): `occurrences`.

Available since

  March 2020 Release (v2.8521)

Markup configuration example(s) :

    data-sort-criteria='alphanumeric'

### title

title: string

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :103

The title to display at the top of the facet.

Default value is the localized string for `NoTitle`.

Markup configuration example(s) :

    data-title='Product category'

### valueCaption

valueCaption: IStringMap<string>

- Defined in ui/DynamicHierarchicalFacet/DynamicHierarchicalFacet.ts :179

A mapping of facet values to their desired captions.

Additional documentation

  Normalizing Facet Value Captions

## Constructors

### constructor

- new DynamicHierarchicalFacet(element: HTMLElement, type: string, bindings?: IComponentBindings): DynamicHierarchicalFacet

- Inherited from Component.constructor

  - Defined in ui/Base/Component.ts :296

  Create a new Component. Resolve all IComponentBindings if not provided.
  Create a new Logger for this component. Attach the component to the SearchInterface.

  #### Parameters

  - ##### element: HTMLElement

    The HTMLElement on which to create the component. Used to bind data on the element.

  - ##### type: string

    The unique identifier for this component. See: IComponentDefinition.ID. Used to generate the unique Coveo CSS class associated with every component.

  - ##### Default value bindings: IComponentBindings = {}

    The environment for every component. Optional, but omitting to provide one will impact performance.

  #### Returns DynamicHierarchicalFacet

### Implements

- IDynamicHierarchicalFacet
- IFieldValueCompatibleFacet