# Coveo DynamicFacet Component (CoveoDynamicFacet)

The `DynamicFacet` component displays a facet of the results for the current query. A facet is a list of values for a certain field occurring in the results, ordered using a configurable criteria (e.g., number of occurrences).

The list of values is obtained using an array of `FacetRequest` operations performed at the same time as the main query.

The `DynamicFacet` component allows the end-user to drill down inside a result set by restricting the result to certain field values.

This facet is more easy to use than the original `Facet` component. It implements additional Coveo Machine Learning (Coveo ML) features such as dynamic navigation experience (DNE).

Not supported in

  Coveo for Salesforce Free

Available since

  May 2019 Release (v2.6063)

## Index

### Methods

- collapse
- debugInfo
- deselectMultipleValues
- deselectValue
- disable
- enable
- enableFreezeCurrentValuesFlag
- enableFreezeFacetOrderFlag
- expand
- focusValueAfterRerender
- getBindings
- getCaptionForStringValue
- hasSelectedValue
- reset
- selectMultipleValues
- selectValue
- showLessValues
- showMoreValues
- toggleCollapse
- toggleSelectValue
- get

### Properties

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

### Accessors

- usageAnalytics

### Component Options

- collapsedByDefault
- customSort
- dependsOn
- dependsOnCondition
- enableCollapse
- enableFacetSearch
- enableMoreLess
- enableScrollToTop
- field
- filterFacetCount
- id
- includeInBreadcrumb
- injectionDepth
- numberOfValues
- numberOfValuesInBreadcrumb
- sortCriteria
- title
- useLeadingWildcardInFacetSearch
- valueCaption

### Constructors

- constructor

## Methods

### collapse

- collapse(): void

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

  Collapses the facet, displaying only its currently selected 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

### deselectMultipleValues

- deselectMultipleValues(values: string[]): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :427

  Deselects multiple values in this facet.

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

  #### Parameters

  - ##### values: string[]

    The names of the facet values to deselect.

  #### Returns void

### deselectValue

- deselectValue(value: string): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :406

  Deselects a single value in this facet.

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

  #### Parameters

  - ##### value: string

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

### enableFreezeCurrentValuesFlag

- enableFreezeCurrentValuesFlag(): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :562

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

  Setting the flag to `true` helps ensuring that the values 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

### enableFreezeFacetOrderFlag

- enableFreezeFacetOrderFlag(): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :575

  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/DynamicFacet/DynamicFacet.ts :526

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

  #### Returns void

### focusValueAfterRerender

- focusValueAfterRerender(value: string): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :458

  Keyboard focuses a value once it has been re-rendered.

  #### Parameters

  - ##### value: string

    The name of the facet value to focus

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

### getCaptionForStringValue

- getCaptionForStringValue(value: string): string

- - Defined in ui/DynamicFacet/DynamicFacet.ts :468

  Returns the configured caption for a desired facet value.

  #### Parameters

  - ##### value: string

    The string facet value whose caption the method should return.

  #### Returns string

### hasSelectedValue

- hasSelectedValue(value: string): boolean

- - Defined in ui/DynamicFacet/DynamicFacet.ts :415

  Determines whether the specified value is selected in the facet.

  #### Parameters

  - ##### value: string

    The name of the facet value to verify.

  #### Returns boolean

### reset

- reset(): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :504

  Deselects all values in this facet.

  Does not trigger a query automatically. Updates the visual of the facet.

  #### Returns void

### selectMultipleValues

- selectMultipleValues(values: string[]): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :388

  Selects multiple values in this facet.

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

  #### Parameters

  - ##### values: string[]

    The names of the facet values to select.

  #### Returns void

### selectValue

- selectValue(value: string): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :375

  Selects a single value in this facet.

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

  #### Parameters

  - ##### value: string

    The name of the facet value to select.

  #### Returns void

### showLessValues

- showLessValues(): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :490

  Reduces the number of displayed facet values down to numberOfValues.

  Automatically triggers an isolated query.

  #### Returns void

### showMoreValues

- showMoreValues(additionalNumberOfValues?: number): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :478

  Requests additional values.

  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/DynamicFacet/DynamicFacet.ts :519

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

  #### Returns void

### toggleSelectValue

- toggleSelectValue(value: string): void

- - Defined in ui/DynamicFacet/DynamicFacet.ts :444

  Toggles the selection state of a single value in this facet.

  Does not trigger a query automatically.

  #### Parameters

  - ##### value: string

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

### collapsedByDefault

collapsedByDefault: boolean

- Defined in ui/DynamicFacet/DynamicFacet.ts :228

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/DynamicFacet/DynamicFacet.ts :175

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

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

Example:

You could use this option to specify a logical order for support tickets, such as:

    <div class="CoveoDynamicFacet" data-field="@ticketstatus" data-title="Ticket Status" data-tab="All" data-custom-sort="New,Opened,Feedback,Resolved"></div>

Note:

> The `DynamicFacetRange` component does not support this option.

### dependsOn

dependsOn: string

- Defined in ui/DynamicFacet/DynamicFacet.ts :266

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

By default, the facet does not depend on any other facet to be displayed.

Available since

  December 2019 Release (v2.7610)

Markup configuration example(s) :

    data-depends-on='document-type-facet'

### dependsOnCondition

dependsOnCondition: IDependentFacetCondition

- Defined in ui/DynamicFacet/DynamicFacet.ts :280

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

Available since

  April 2020 Release (v2.8864)

Additional documentation

  Defining Dependent Facets

### enableCollapse

enableCollapse: boolean

- Defined in ui/DynamicFacet/DynamicFacet.ts :188

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/DynamicFacet/DynamicFacet.ts :212

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

Note: The `DynamicFacetRange` component does not support this option.

By default, the following behavior applies:

- Enabled when more facet values are available.
- Disabled when all available facet values are already displayed.

Markup configuration example(s) :

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

### enableMoreLess

enableMoreLess: boolean

- Defined in ui/DynamicFacet/DynamicFacet.ts :200

Whether to enable the Show more and Show less buttons in the facet.

Note: The `DynamicFacetRange` component does not support this option.

Default

  `true`

Markup configuration example(s) :

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

### enableScrollToTop

enableScrollToTop: boolean

- Defined in ui/DynamicFacet/DynamicFacet.ts :193

Whether to scroll back to the top of the page whenever the end-user interacts with the 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/DynamicFacet/DynamicFacet.ts :123

The name of the field on which to base this facet.

The field must of the `string` type.

Must be prefixed by `@`, and must reference an existing field whose Facet option is enabled.

Required

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

Additional documentation

  Add or Edit Fields

Markup configuration example(s) :

    data-field='@author'

### filterFacetCount

filterFacetCount: boolean

- Defined in ui/DynamicFacet/DynamicFacet.ts :309

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`.

Available since

  March 2020 Release (v2.8521)

Markup configuration example(s) :

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

### id

id: string

- Defined in ui/DynamicFacet/DynamicFacet.ts :86

The unique identifier for this facet.

Among other things, this is used to record and read the facet state in the URL fragment identifier (see the `enableHistory` `SearchInterface` option).

Tip: When several facets in a given search interface are based on the same field, ensure that each of those facets has a distinct `id`.

If specified, must contain between 1 and 60 characters. Only alphanumeric (A-Za-z0-9), underscore (_), and hyphen (-) characters are kept; other characters are automatically removed.

Defaults to the `field` option value.

Markup configuration example(s) :

    data-id='author-facet'

### includeInBreadcrumb

includeInBreadcrumb: boolean

- Defined in ui/DynamicFacet/DynamicFacet.ts :235

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

See also the `numberOfValuesInBreadcrumb` option.

Default

  `true`

Markup configuration example(s) :

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

### injectionDepth

injectionDepth: number

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

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`

Available since

  January 2020 Release (v2.7968)

Markup configuration example(s) :

    data-injection-depth='1500'

### numberOfValues

numberOfValues: number

- Defined in ui/DynamicFacet/DynamicFacet.ts :183

The number of values to request for this facet.

Also determines the default maximum number of additional values to request each time this facet is expanded, and the maximum number of values to display when this facet is collapsed (see the `enableCollapse` option).

Minimum

  `0`

Default

  `8`

Markup configuration example(s) :

    data-number-of-values='10'

### numberOfValuesInBreadcrumb

numberOfValuesInBreadcrumb: number

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

The maximum number of selected values the `Breadcrumb` component can display before outputting a N more... link for the facet.

Only effective when

  `includeInBreadcrumb` is truthy

Minimum

  `0`

Markup configuration example(s) :

    data-number-of-values-in-breadcrumb='10'

### sortCriteria

sortCriteria: FacetSortCriteria

- Defined in ui/DynamicFacet/DynamicFacet.ts :144

The sort criterion to use for this facet.

See `FacetSortCriteria` for the list and description of allowed values.

By default, the following behavior applies:

- If the requested `numberOfValues` is greater than or equal to the currently displayed number of values, the `alphanumeric` criterion is used.
- If the requested `numberOfValues` is less than the currently displayed number of values and the facet is not currently expanded, the `score` criterion is used.
- Otherwise, the `alphanumeric` criterion is used.

Markup configuration example(s) :

    data-sort-criteria='score'

### title

title: string

- Defined in ui/DynamicFacet/DynamicFacet.ts :106

The title to display for this facet.

Defaults to the localized string for `NoTitle`.

Markup configuration example(s) :

    data-title='Author'

### useLeadingWildcardInFacetSearch

useLeadingWildcardInFacetSearch: boolean

- Defined in ui/DynamicFacet/DynamicFacet.ts :219

Whether to prepend facet search queries with a wildcard.

Note: The `DynamicFacetRange` component does not support this option.

Only effective when

  `enableFacetSearch` is truthy

Default

  `true`

Markup configuration example(s) :

    data-use-leading-wildcard-in-facet-search='true'
    data-use-leading-wildcard-in-facet-search='false'

### valueCaption

valueCaption: IStringMap<string>

- Defined in ui/DynamicFacet/DynamicFacet.ts :255

A mapping of facet values to their desired captions.

Note: The `DynamicFacetRange` component does not support this option.

Additional documentation

  Normalizing Facet Value Captions.

Markup configuration example(s) :

    data-value-caption='{ "smith_alice": "Alice Smith", "jones_bob_r": "Bob R. Jones" }'

## Constructors

### constructor

- new DynamicFacet(element: HTMLElement, options?: IDynamicFacetOptions, bindings?: IComponentBindings, classId?: string): DynamicFacet

- Overwrites Component.constructor

  - Defined in ui/DynamicFacet/DynamicFacet.ts :328

  Creates a new `DynamicFacet` instance.

  #### Parameters

  - ##### element: HTMLElement

    The element from which to instantiate the component.

  - ##### Optional options: IDynamicFacetOptions

    The component options.

  - ##### Optional bindings: IComponentBindings

    The component bindings. Automatically resolved by default.

  - ##### Default value classId: string = DynamicFacet.ID

  #### Returns DynamicFacet

### Implements

- IDynamicFacet