# Coveo CategoryFacet Component (CoveoCategoryFacet)

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

The path is a sequence of values that leads to a specific value in the hierarchy. It is an array listing all the parents of a file (e.g., `['c', 'folder1']` for the `c:\folder1\text1.txt` file).

This facet requires a `field` with a special format to work correctly (see Using the Category Facet Component).

Not supported in

  Coveo for Salesforce Free

Available since

  January 2019 Release (v2.5395.12)

## Index

### Methods

- changeActivePath
- debugInfo
- debugValue
- deselectCurrentValue
- disable
- enable
- getAvailableValues
- getBindings
- getCaption
- getVisibleParentValues
- hide
- reload
- reset
- selectValue
- show
- showLess
- showMore
- get

### Properties

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

### Accessors

- usageAnalytics

### Component Options

- basePath
- debug
- delimitingCharacter
- dependsOn
- dependsOnCondition
- displaySearchButton
- displaySearchOnTop
- enableFacetSearch
- enableMoreLess
- facetSearchDelay
- field
- id
- injectionDepth
- maximumDepth
- numberOfResultsInFacetSearch
- numberOfValues
- pageSize
- title
- valueCaption

### Constructors

- constructor

## Methods

### changeActivePath

- changeActivePath(path: string[]): void

- - Defined in ui/CategoryFacet/CategoryFacet.ts :515

  Changes the active path.

  #### Parameters

  - ##### path: string[]

  #### 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

### debugValue

- debugValue(value: string): Promise<void>

- - Defined in ui/CategoryFacet/CategoryFacet.ts :678

  Goes through any value that contains the value parameter, and verifies whether there are missing parents. Issues are then logged in the console. If you do not want to specify a value, you can simply enable CategoryFacet.options.debug and do an empty query.

  #### Parameters

  - ##### value: string

  #### Returns Promise<void>

### deselectCurrentValue

- deselectCurrentValue(): void

- - Defined in ui/CategoryFacet/CategoryFacet.ts :624

  Deselects the last value in the hierarchy that is applied to the query. When at the top of the hierarchy, this method does nothing.

  #### Returns void

### 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

### getAvailableValues

- getAvailableValues(): object[]

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

  Returns the values at the bottom of the hierarchy. These are the values that are not yet applied to the query.

  #### Returns object[]

  simple object with three fields: `value`, `count` and `path`.

### 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/CategoryFacet/CategoryFacet.ts :690

  #### 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

### getVisibleParentValues

- getVisibleParentValues(): CategoryValueDescriptor[]

- - Defined in ui/CategoryFacet/CategoryFacet.ts :541

  Returns all the visible parent values.

  #### Returns CategoryValueDescriptor[]

  simple object with three fields: `value`, `count` and `path`.

### hide

- hide(): void

- - Defined in ui/CategoryFacet/CategoryFacet.ts :652

  Hides the component.

  #### Returns void

### reload

- reload(): void

- - Defined in ui/CategoryFacet/CategoryFacet.ts :531

  Reloads the facet with the same path.

  #### Returns void

### reset

- reset(): void

- - Defined in ui/CategoryFacet/CategoryFacet.ts :643

  Resets the facet to its initial state.

  #### Returns void

### selectValue

- selectValue(value: string): void

- - Defined in ui/CategoryFacet/CategoryFacet.ts :609

  Selects a value from the currently available values. If the given value to select is not in the available values, it will throw an error.

  #### Parameters

  - ##### value: string

  #### Returns void

### show

- show(): void

- - Defined in ui/CategoryFacet/CategoryFacet.ts :659

  Shows the component.

  #### Returns void

### showLess

- showLess(): void

- - Defined in ui/CategoryFacet/CategoryFacet.ts :579

  Shows less values, up to the original number of values.

  See the `enableMoreLess`, and `numberOfValues` options.

  #### Returns void

### showMore

- showMore(): void

- - Defined in ui/CategoryFacet/CategoryFacet.ts :564

  Shows more values according to CategoryFacet.options.pageSize.

  See the `enableMoreLess`, and `numberOfValues` options.

  #### 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/CategoryFacet/CategoryFacet.ts :233

The path to use as the path prefix for every query.

Example:

You have the following files indexed on a file system:

    c:\
       folder1\
         text1.txt
       folder2\
         folder3\
           text2.txt

Setting the `basePath` to `c` would display `folder1` and `folder2` in the `CategoryFacet`, but omit `c`.

This options accepts an array of values. To specify a "deeper" starting path in your tree, you need to use comma-separated values.

For example, setting `data-base-path="c,folder1"` on the component markup would display `folder3` in the `CategoryFacet`, but omit `c` and `folder1`.

Default

  `[]`

### debug

debug: boolean

- Defined in ui/CategoryFacet/CategoryFacet.ts :246

Whether to activate field format debugging. This options logs messages in the console for any potential encountered issues. This option can have negative effects on performance, and should only be activated when debugging.

Default

  `false`

Markup configuration example(s) :

    data-debug='true'
    data-debug='false'

### delimitingCharacter

delimitingCharacter: string

- Defined in ui/CategoryFacet/CategoryFacet.ts :211

The character that specifies the hierarchical dependency.

Example:

If your field has the following values:

`@field: c; c>folder2; c>folder2>folder3;`

The delimiting character is `>`.

Default value is `|`.

Default

  `|`

Markup configuration example(s) :

    data-delimiting-character='foo'

### dependsOn

dependsOn: string

- Defined in ui/CategoryFacet/CategoryFacet.ts :295

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

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

Available since

  September 2019 Release (v2.7023)

Markup configuration example(s) :

    data-depends-on='foo'

### dependsOnCondition

dependsOnCondition: IDependentFacetCondition

- Defined in ui/CategoryFacet/CategoryFacet.ts :307

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

### displaySearchButton

displaySearchButton: boolean

- Defined in ui/CategoryFacet/CategoryFacet.ts :324

Whether to display the facet search widget as a button instead of a search bar.

Default

  `true`

Available since

  July 2020 Release (v2.9373)

Markup configuration example(s) :

    data-display-search-button='true'
    data-display-search-button='false'

### displaySearchOnTop

displaySearchOnTop: boolean

- Defined in ui/CategoryFacet/CategoryFacet.ts :318

Whether to display the facet search widget above the facet values instead of below them.

Default

  `false`

Available since

  July 2020 Release (v2.9373)

Markup configuration example(s) :

    data-display-search-on-top='true'
    data-display-search-on-top='false'

### enableFacetSearch

enableFacetSearch: boolean

- Defined in ui/CategoryFacet/CategoryFacet.ts :141

Whether to display a search box at the bottom of the facet for searching among the available facet `field` values.

See also the `facetSearchDelay`, and `numberOfResultsInFacetSearch` options.

Default value is `true`.

Default

  `true`

Markup configuration example(s) :

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

### enableMoreLess

enableMoreLess: boolean

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

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

See also the `pageSize` option.

Default value is `true`.

Default

  `true`

Markup configuration example(s) :

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

### facetSearchDelay

facetSearchDelay: number

- Defined in ui/CategoryFacet/CategoryFacet.ts :182

If the `enableFacetSearch` option is `true`, specifies the delay (in milliseconds) before sending a search request to the server when the user starts typing in the category facet search box.

Specifying a smaller value makes results appear faster. However, chances of having to cancel many requests sent to the server increase as the user keeps on typing new characters.

Default value is `100`. Minimum value is `0`.

Minimum

  `0`

Default

  `100`

Markup configuration example(s) :

    data-facet-search-delay='10'

### field

field: IFieldOption

- Defined in ui/CategoryFacet/CategoryFacet.ts :115

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, see the CategoryFacet.options.debug option and the CategoryFacet.debugValue method.

See Using the Category Facet Component.

Required

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

Markup configuration example(s) :

    data-field='@foo'

### id

id: string

- Defined in ui/CategoryFacet/CategoryFacet.ts :151

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='foo'

### injectionDepth

injectionDepth: number

- Defined in ui/CategoryFacet/CategoryFacet.ts :165

The injection depth to use.

The injection depth determines how many results to scan in the index to ensure that the category facet lists all potential facet values. Increasing this value enhances the accuracy of the listed values at the cost of performance.

Default value is `1000`. Minimum value is `1000`.

Not supported in

  salesforcefree

Minimum

  `1000`

Default

  `1000`

Markup configuration example(s) :

    data-injection-depth='1500'

### maximumDepth

maximumDepth: number

- Defined in ui/CategoryFacet/CategoryFacet.ts :240

The maximum number of levels to traverse in the hierarchy. This option does not count the length of the base path. The depth depends on what is shown in the interface.

Default value is `Number.MAX_VALUE`.

Minimum

  `1`

Markup configuration example(s) :

    data-maximum-depth='10'

### numberOfResultsInFacetSearch

numberOfResultsInFacetSearch: number

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

If the `enableFacetSearch` option is `true`, specifies the number of values to display in the facet search results popup.

Default value is `15`. Minimum value is `1`.

Minimum

  `1`

Default

  `15`

Markup configuration example(s) :

    data-number-of-results-in-facet-search='10'

### numberOfValues

numberOfValues: number

- Defined in ui/CategoryFacet/CategoryFacet.ts :130

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='10'

### pageSize

pageSize: number

- Defined in ui/CategoryFacet/CategoryFacet.ts :197

If the `enableMoreLess` option is `true`, specifies the number of additional results to fetch when clicking the More button.

Default value is `10`. Minimum value is `1`.

Only effective when

  `enableMoreLess` is truthy

Minimum

  `1`

Default

  `10`

Markup configuration example(s) :

    data-page-size='10'

### title

title: string

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

The title to display at the top of the facet.

Default value is the localized string for `NoTitle`.

Markup configuration example(s) :

    data-title='foo'

### valueCaption

valueCaption: IStringMap<string>

- Defined in ui/CategoryFacet/CategoryFacet.ts :286

Specifies a JSON object describing a mapping of facet values to their desired captions. See Normalizing Facet Value Captions.

Note: If this option is specified, the facet search box will be unavailable.

Examples:

You can set the option in the 'init' call:

    var myValueCaptions = {
      "txt" : "Text files",
      "html" : "Web page",
      [ ... ]
    };

    Coveo.init(document.querySelector("#search"), {
      Facet : {
        valueCaption : myValueCaptions
      }
    });

Or before the `init` call, using the 'options' top-level function:

    Coveo.options(document.querySelector("#search"), {
      Facet : {
        valueCaption : myValueCaptions
      }
    });

Or directly in the markup:

    <!-- Ensure that the double quotes are properly handled in data-value-caption. -->
    <div class='CoveoCategoryFacet' data-field='@myotherfield' data-value-caption='{"txt":"Text files","html":"Web page"}'></div>

## Constructors

### constructor

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

- 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 CategoryFacet

### Implements

- IAutoLayoutAdjustableInsideFacetColumn