# Coveo Facet Component (CoveoFacet)

The `Facet` 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 a `GroupByRequest` operation performed at the same time as the main query.

The `Facet` component allows the end user to drill down inside a result set by restricting the result to certain field values. It also allows filtering out values from the facet itself, and can provide a search box to look for specific values inside larger sets.

This is probably the most complex component in the Coveo JavaScript Search Framework and as such, it allows for many configuration options.

See also the `FacetRange` and `TimespanFacet` components (which extend this component), and the `FacetSlider` and `CategoryFacet` components (which do not extend this component, but are very similar).

## Index

### Methods

- collapse
- debugInfo
- deselectMultipleValues
- deselectValue
- disable
- enable
- excludeMultipleValues
- excludeValue
- expand
- getBindings
- getCaptionForStringValue
- getDisplayedFacetValues
- getDisplayedValues
- getEndpoint
- getExcludedValues
- getSelectedValues
- getValueCaption
- hasSelectedValue
- hideWaitingAnimation
- reset
- selectMultipleValues
- selectValue
- showLess
- showMore
- showWaitingAnimation
- switchToAnd
- switchToOr
- toggleExcludeValue
- toggleSelectValue
- unexcludeMultipleValues
- unexcludeValue
- updateSort
- get

### Properties

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

### Accessors

- usageAnalytics

### Component Options

- additionalFilter
- allowedValues
- availableSorts
- computedField
- computedFieldCaption
- computedFieldFormat
- computedFieldOperation
- customSort
- dependsOn
- dependsOnCondition
- enableCollapse
- enableFacetSearch
- enableMoreLess
- enableSettings
- enableSettingsFacetState
- enableTogglingOperator
- facetSearchDelay
- facetSearchIgnoreAccents
- field
- id
- includeInBreadcrumb
- includeInOmnibox
- injectionDepth
- isMultiValueField
- lookupField
- numberOfValues
- numberOfValuesInBreadcrumb
- numberOfValuesInFacetSearch
- numberOfValuesInOmnibox
- paddingContainer
- pageSize
- preservePosition
- scrollContainer
- sortCriteria
- title
- useAnd
- useWildcardsInFacetSearch
- valueCaption

### Constructors

- constructor

## Methods

### collapse

- collapse(): void

- - Defined in ui/Facet/Facet.ts :1253

  Collapses the facet.

  #### 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: FacetValue[] | string[]): void

- - Defined in ui/Facet/Facet.ts :906

  Deselects multiple values.

  Does not trigger a query automatically.

  #### Parameters

  - ##### values: FacetValue[] | string[]

    Can be an array of `FacetValue` or an array of strings.

  #### Returns void

### deselectValue

- deselectValue(value: FacetValue | string): void

- - Defined in ui/Facet/Facet.ts :892

  Deselects a single value.

  Does not trigger a query automatically.

  #### Parameters

  - ##### value: FacetValue | string

    Can be a `FacetValue` or a string (e.g., `deselectValue('foobar')` or `deselectValue(new FacetValue('foobar'))`).

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

### excludeMultipleValues

- excludeMultipleValues(values: FacetValue[] | string[]): void

- - Defined in ui/Facet/Facet.ts :937

  Excludes multiple values.

  Does not trigger a query automatically.

  #### Parameters

  - ##### values: FacetValue[] | string[]

    Can be an array of `FacetValue` or an array of strings.

  #### Returns void

### excludeValue

- excludeValue(value: FacetValue | string): void

- - Defined in ui/Facet/Facet.ts :923

  Excludes a single value.

  Does not trigger a query automatically.

  #### Parameters

  - ##### value: FacetValue | string

    Can be a `FacetValue` or a string (e.g., `excludeValue('foobar')` or `excludeValue(new FacetValue('foobar'))`).

  #### Returns void

### expand

- expand(): void

- - Defined in ui/Facet/Facet.ts :1263

  Expands the facet.

  #### 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/Facet/Facet.ts :1211

  Returns the configured caption for a desired facet value.

  #### Parameters

  - ##### value: string

    The string facet value whose caption the method should return.

  #### Returns string

### getDisplayedFacetValues

- getDisplayedFacetValues(): FacetValue[]

- - Defined in ui/Facet/Facet.ts :1019

  Returns the currently displayed values as an array of `FacetValue`.

  #### Returns FacetValue[]

  The currently displayed values.

### getDisplayedValues

- getDisplayedValues(): string[]

- - Defined in ui/Facet/Facet.ts :1010

  Returns the currently displayed values as an array of strings.

  #### Returns string[]

  The currently displayed values.

### getEndpoint

- getEndpoint(): ISearchEndpoint

- - Defined in ui/Facet/Facet.ts :1093

  Returns the endpoint for the facet.

  #### Returns ISearchEndpoint

  The endpoint for the facet.

### getExcludedValues

- getExcludedValues(): string[]

- - Defined in ui/Facet/Facet.ts :1049

  Returns the currently excluded values as an array of strings.

  #### Returns string[]

  The currently excluded values.

### getSelectedValues

- getSelectedValues(): string[]

- - Defined in ui/Facet/Facet.ts :1031

  Returns the currently selected values as an array of strings.

  #### Returns string[]

  The currently selected values.

### getValueCaption

- getValueCaption(facetValue: IIndexFieldValue | FacetValue | string): string

- - Defined in ui/Facet/Facet.ts :1188

  Returns the configured caption for the given `FacetValue`.

  #### Parameters

  - ##### facetValue: IIndexFieldValue | FacetValue | string

    The `FacetValue` whose caption the method should return.

  #### Returns string

### hasSelectedValue

- hasSelectedValue(value: string): boolean

- - Defined in ui/Facet/Facet.ts :1040

  Determines whether the specified value is selected in the facet.

  #### Parameters

  - ##### value: string

    The name of the facet value to verify.

  #### Returns boolean

### hideWaitingAnimation

- hideWaitingAnimation(): void

- - Defined in ui/Facet/Facet.ts :1146

  Hides the waiting animation in the facet header.

  #### Returns void

### reset

- reset(): void

- - Defined in ui/Facet/Facet.ts :1057

  Resets the facet by un-selecting all values, un-excluding all values, and redrawing the facet.

  #### Returns void

### selectMultipleValues

- selectMultipleValues(values: FacetValue[] | string[]): void

- - Defined in ui/Facet/Facet.ts :875

  Selects multiple values.

  Does not trigger a query automatically.

  #### Parameters

  - ##### values: FacetValue[] | string[]

    Can be an array of `FacetValue` or an array of strings.

  #### Returns void

### selectValue

- selectValue(value: FacetValue | string): void

- - Defined in ui/Facet/Facet.ts :861

  Selects a single value.

  Does not trigger a query automatically.

  #### Parameters

  - ##### value: FacetValue | string

    Can be a `FacetValue` or a string (e.g., `selectValue('foobar')` or `selectValue(new FacetValue('foobar'))`).

  #### Returns void

### showLess

- showLess(): void

- - Defined in ui/Facet/Facet.ts :1240

  Shows less elements in the Facet (up to the original number of values).

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

  #### Returns void

### showMore

- showMore(): void

- - Defined in ui/Facet/Facet.ts :1224

  Shows the next page of results in the facet.

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

  Triggers a query if needed, or displays the already available values.

  #### Returns void

### showWaitingAnimation

- showWaitingAnimation(): void

- - Defined in ui/Facet/Facet.ts :1135

  Shows a waiting animation in the facet header (a spinner).

  #### Returns void

### switchToAnd

- switchToAnd(): void

- - Defined in ui/Facet/Facet.ts :1071

  Switches the facet to `AND` mode.

  See the `useAnd`, and `enableTogglingOperator` options.

  #### Returns void

### switchToOr

- switchToOr(): void

- - Defined in ui/Facet/Facet.ts :1083

  Switches the facet to `OR` mode.

  See the `useAnd`, and `enableTogglingOperator` options.

  #### Returns void

### toggleExcludeValue

- toggleExcludeValue(value: FacetValue | string): void

- - Defined in ui/Facet/Facet.ts :998

  Toggles the exclusion state of a single value (excludes the value if it is not already excluded; un-excludes the value if it is already excluded).

  Does not trigger a query automatically.

  #### Parameters

  - ##### value: FacetValue | string

    Can be a `FacetValue` or a string.

  #### Returns void

### toggleSelectValue

- toggleSelectValue(value: FacetValue | string): void

- - Defined in ui/Facet/Facet.ts :983

  Toggles the selection state of a single value (selects the value if it is not already selected; un-selects the value if it is already selected).

  Does not trigger a query automatically.

  #### Parameters

  - ##### value: FacetValue | string

    Can be a `FacetValue` or a string.

  #### Returns void

### unexcludeMultipleValues

- unexcludeMultipleValues(values: FacetValue[] | string[]): void

- - Defined in ui/Facet/Facet.ts :967

  Unexcludes multiple values.

  Does not trigger a query automatically.

  #### Parameters

  - ##### values: FacetValue[] | string[]

    Can be an array of `FacetValue` or an array of strings.

  #### Returns void

### unexcludeValue

- unexcludeValue(value: FacetValue | string): void

- - Defined in ui/Facet/Facet.ts :953

  Unexcludes a single value.

  Does not trigger a query automatically.

  #### Parameters

  - ##### value: FacetValue | string

    Can be a `FacetValue` or a string.

  #### Returns void

### updateSort

- updateSort(criteria: string): void

- - Defined in ui/Facet/Facet.ts :1106

  Changes the sort parameter for the facet.

  See Facet.options.availableSorts for the list of possible values.

  Also triggers a new query.

  #### Parameters

  - ##### criteria: string

    The new sort parameter for the facet.

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

### facetSearch

facetSearch: FacetSearch

- Defined in ui/Facet/Facet.ts :731

Renders and handles the facet Search part of the component.

### facetSettings

facetSettings: FacetSettings

- Defined in ui/Facet/Facet.ts :736

Renders and handles the facet Settings part of the component

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

### additionalFilter

additionalFilter: string

- Defined in ui/Facet/Facet.ts :627

Specifies an additional query expression (query override) to add to each `GroupByRequest` that this facet performs.

Example: `@date>=2014/01/01`

Not supported in

  Coveo for Salesforce Free

Markup configuration example(s) :

    data-additional-filter='foo'

### allowedValues

allowedValues: string[]

- Defined in ui/Facet/Facet.ts :619

Specifies an explicit list of `allowedValues` in the `GroupByRequest`.

If you specify a list of values for this option, the facet uses only these values (if they are available in the current result set).

Example:

The following facet only uses the `Contact`, `Account`, and `File` values of the `@objecttype` field. Even if the current result set contains other `@objecttype` values, such as `Message`, or `Product`, the facet does not use those other values.

    <div class="CoveoFacet" data-field="@objecttype" data-title="Object Type" data-tab="All" data-allowed-values="Contact,Account,File"></div>

Default value is `undefined`, and the facet uses all available values for its `field` in the current result set.

### availableSorts

availableSorts: string[] | ("occurrences" | "score" | "alphaascending" | "alphadescending" | "computedfieldascending" | "computedfielddescending" | "chisquare" | "nosort")[]

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

If the `enableSettings` option is `true`, specifies the sort criteria options to display in the facet Settings menu.

Possible values are:

- `"occurrences"`
- `"score"`
- `"alphaascending"`
- `"alphadescending"`
- `"computedfieldascending"`
- `"computedfielddescending"`
- `"custom"`

See IGroupByRequest.sortCriteria for a description of each possible value.

Notes:

> - The `FacetRange` component does not support this option.

> - Using value captions will disable alphabetical sorts (see the valueCaption option).

Default value is `occurrences,score,alphaascending,alphadescending`.

Only effective when

  `enableSettings` is truthy

Default

  `[occurrences, score, alphaascending, alphadescending]`

### computedField

computedField: IFieldOption

- Defined in ui/Facet/Facet.ts :469

Specifies the name of a field on which to execute an aggregate operation for all distinct values of the facet `field`.

The facet displays the result of the operation along with the number of occurrences for each value.

You can use this option to compute the sum of a field (like a money amount) for each listed facet value.

Works in conjunction with the `computedFieldOperation`, `computedFieldFormat`, and `computedFieldCaption` options.

Not supported in

  Coveo for Salesforce Free

Markup configuration example(s) :

    data-computed-field='@foo'

### computedFieldCaption

computedFieldCaption: string

- Defined in ui/Facet/Facet.ts :517

Specifies what the caption of the `computedField` should be in the facet Settings menu for sorting.

For example, setting this option to `"Money"` will display `"Money Ascending"` for computed field ascending.

Note:

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

Default value is the localized string for `ComputedField`.

Not supported in

  Coveo for Salesforce Free

Markup configuration example(s) :

    data-computed-field-caption='foo'

### computedFieldFormat

computedFieldFormat: "c0" | "n0" | "n2"

- Defined in ui/Facet/Facet.ts :501

Specifies how to format the values resulting from a `computedFieldOperation`.

The Globalize library defines all available formats (see Globalize).

The most commonly used formats are:

- `c0` - Formats the value as a currency.
- `n0` - Formats the value as an integer.
- `n2` - Formats the value as a floating point with 2 decimal digits.

Default value is `"c0"`.

Not supported in

  Coveo for Salesforce Free

Default

  `c0`

### computedFieldOperation

computedFieldOperation: "sum" | "average" | "minimum" | "maximum"

- Defined in ui/Facet/Facet.ts :482

Specifies the type of aggregate operation to perform on the `computedField`.

The possible values are:

- `sum` - Computes the sum of the computed field values.
- `average` - Computes the average of the computed field values.
- `minimum` - Finds the minimum value of the computed field values.
- `maximum` - Finds the maximum value of the computed field values.

Default value is `sum`.

Not supported in

  Coveo for Salesforce Free

Default

  `sum`

### customSort

customSort: string[]

- Defined in ui/Facet/Facet.ts :304

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

Example:

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

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

Note:

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

### dependsOn

dependsOn: string

- Defined in ui/Facet/Facet.ts :658

Specifies whether this facet only appears when a value is selected in its "parent" facet.

To specify the parent facet, use its `id`.

Remember that by default, a facet `id` value is the same as its `field` option value.

Examples:

First case: the "parent" facet has no custom `id`:

    <!-- "Parent" Facet: -->
    <div class='CoveoFacet' data-field='@myfield' data-title='My Parent Facet'></div>

    <!-- The "dependent" Facet must refer to the default `id` of its "parent" Facet, which is the name of its field. -->
    <div class='CoveoFacet' data-field='@myotherfield' data-title='My Dependent Facet' data-depends-on='@myfield'></div>

Second case: the "parent" facet has a custom `id`:

    <!-- "Parent" Facet: -->
    <div class='CoveoFacet' data-field='@myfield' data-title='My Parent Facet' data-id='myParentCustomId'></div>

    <!-- The "dependent" Facet must refer to the custom `id` of its "parent" Facet, which is 'myParentCustomId'. -->
    <div class='CoveoFacet' data-field='@myotherfield' data-title='My Dependent Facet' data-depends-on='myParentCustomId'></div>

Default value is `undefined`

Markup configuration example(s) :

    data-depends-on='foo'

### dependsOnCondition

dependsOnCondition: IDependentFacetCondition

- Defined in ui/Facet/Facet.ts :669

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/Facet/Facet.ts :597

If the `enableSettings` option is `true`, specifies whether the Collapse \ Expand menu option is available in the facet Settings menu.

Note:

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

Default value is `true`.

Only effective when

  `enableSettings` is truthy

Default

  `true`

Markup configuration example(s) :

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

### enableFacetSearch

enableFacetSearch: boolean

- Defined in ui/Facet/Facet.ts :364

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

See also the `facetSearchDelay`, `facetSearchIgnoreAccents`, and `numberOfValuesInFacetSearch` options.

Note:

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

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/Facet/Facet.ts :577

Specifies whether to enable the More and Less buttons in the Facet.

See also the `pageSize` option.

Note:

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

Default value is `true`.

Default

  `true`

Markup configuration example(s) :

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

### enableSettings

enableSettings: boolean

- Defined in ui/Facet/Facet.ts :230

Specifies whether to display the facet Settings menu.

See also the `enableSettingsFacetState`, `availableSorts`, and `enableCollapse` options.

Note:

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

Default value is `true`.

Default

  `true`

Markup configuration example(s) :

    data-enable-settings='true'
    data-enable-settings='false'

### enableSettingsFacetState

enableSettingsFacetState: boolean

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

If the `enableSettings` option is `true`, specifies whether the Save state menu option is available in the facet Settings menu.

Note:

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

Default value is `false`.

Only effective when

  `enableSettings` is truthy

Default

  `false`

Markup configuration example(s) :

    data-enable-settings-facet-state='true'
    data-enable-settings-facet-state='false'

### enableTogglingOperator

enableTogglingOperator: boolean

- Defined in ui/Facet/Facet.ts :347

Specifies whether to allow the user to toggle between the `OR` and `AND` modes in the facet.

Setting this option to `true` displays an icon in the top right corner of the facet. The user can click this icon to toggle between between the two modes.

Default value is `false`.

Default

  `false`

Markup configuration example(s) :

    data-enable-toggling-operator='true'
    data-enable-toggling-operator='false'

### facetSearchDelay

facetSearchDelay: number

- Defined in ui/Facet/Facet.ts :377

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

Note:

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

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

Only effective when

  `enableFacetSearch` is truthy

Minimum

  `0`

Default

  `100`

Markup configuration example(s) :

    data-facet-search-delay='10'

### facetSearchIgnoreAccents

facetSearchIgnoreAccents: boolean

- Defined in ui/Facet/Facet.ts :387

If the `enableFacetSearch` option is `true`, specifies whether to ignore accents in the facet search box.

Note:

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

Default value is `false`.

Only effective when

  `enableFacetSearch` is truthy

Default

  `false`

Markup configuration example(s) :

    data-facet-search-ignore-accents='true'
    data-facet-search-ignore-accents='false'

### field

field: IFieldOption

- Defined in ui/Facet/Facet.ts :174

Specifies the index field whose values the facet should use.

The field must of the `string` type.

This requires the given field to be configured correctly in the index as a Facet field (see Add or Edit Fields).

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

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/Facet/Facet.ts :189

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

Non-word characters except - @ $ _ . + ! * ' ( ) , , ( `^a-zA-Z0-9-@$_.+!*'(),,]+` ) are automatically removed from the `id` value.

Default value is the `field` option value.

Markup configuration example(s) :

    data-id='foo'

### includeInBreadcrumb

includeInBreadcrumb: boolean

- Defined in ui/Facet/Facet.ts :416

Specifies whether the facet should push data to the `Breadcrumb` component.

See also the `numberOfValuesInBreadcrumb` option.

Default value is `true`.

Default

  `true`

Markup configuration example(s) :

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

### includeInOmnibox

includeInOmnibox: boolean

- Defined in ui/Facet/Facet.ts :438

Specifies whether the Facet should push data to the Omnibox component.

See also Facet.options.numberOfValuesInOmnibox.

Default value is `false`.

deprecated

  This option is exposed for legacy reasons. It is not recommended to use this option.

Default

  `false`

Markup configuration example(s) :

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

### injectionDepth

injectionDepth: number

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

Specifies the injection depth to use for the `GroupByRequest` operation.

The injection depth determines how many results to scan in the index to ensure that the 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'

### isMultiValueField

isMultiValueField: boolean

- Defined in ui/Facet/Facet.ts :209

Specifies whether the facet `field` is configured in the index as a multi-value field (semicolon separated values such as `abc;def;ghi`).

Default value is `false`.

Default

  `false`

Markup configuration example(s) :

    data-is-multi-value-field='true'
    data-is-multi-value-field='false'

### lookupField

lookupField: IFieldOption

- Defined in ui/Facet/Facet.ts :215

Specifies the field whose values the Facet should display.

deprecated

  This option is exposed for legacy reasons. It is not recommended to use this option.

Markup configuration example(s) :

    data-lookup-field='@foo'

### numberOfValues

numberOfValues: number

- Defined in ui/Facet/Facet.ts :311

Specifies 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'

### numberOfValuesInBreadcrumb

numberOfValuesInBreadcrumb: number

- Defined in ui/Facet/Facet.ts :424

If the `includeInBreadcrumb` option is `true`, specifies the maximum number of values that the facet should display in the `Breadcrumb` before outputting a more... button.

Default value is `5` on a desktop computer and `3` on a mobile device. Minimum value is `0`.

Only effective when

  `includeInBreadcrumb` is truthy

Minimum

  `0`

Markup configuration example(s) :

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

### numberOfValuesInFacetSearch

numberOfValuesInFacetSearch: number

- Defined in ui/Facet/Facet.ts :397

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

Note:

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

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

Minimum

  `1`

Default

  `15`

Markup configuration example(s) :

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

### numberOfValuesInOmnibox

numberOfValuesInOmnibox: number

- Defined in ui/Facet/Facet.ts :450

When Facet.options.includeInOmnibox is `true`, specifies the number of values to populate the Breadcrumb with.

Default value is `5` on desktop computer and `3` on a mobile device. Minimum value is `0`.

deprecated

  This option is exposed for legacy reasons. It is not recommended to use this option.

Only effective when

  `includeInOmnibox` is truthy

Minimum

  `0`

Markup configuration example(s) :

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

### paddingContainer

paddingContainer: HTMLElement

- Defined in ui/Facet/Facet.ts :549

Specifies the parent container of the facets.

Used by the `preservePosition` option.

Default value is `element.parentElement`.

### pageSize

pageSize: number

- Defined in ui/Facet/Facet.ts :587

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

Note:

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

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'

### preservePosition

preservePosition: boolean

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

Specifies whether the facet should remain stable in its current position in the viewport while the mouse cursor is over it.

Whenever the value selection changes in a facet, the search interface automatically performs a query. This new query might cause other elements in the page to resize themselves (typically, other facets above or below the one the user is interacting with).

This option is responsible for adding the `<div class='coveo-topSpace'>` and `<div class='coveo-bottomSpace'>` around the Facet container. The Facet adjusts the scroll amount of the page to ensure that it does not move relatively to the mouse when the results are updated.

In some cases, the facet also adds margins to the `scrollContainer`, if scrolling alone is not enough to preserve position.

See also the `paddingContainer`, and `scrollContainer` options.

Default value is `true`.

Default

  `true`

Markup configuration example(s) :

    data-preserve-position='true'
    data-preserve-position='false'

### scrollContainer

scrollContainer: HTMLElement

- Defined in ui/Facet/Facet.ts :566

Specifies the HTML element (through a CSS selector) whose scroll amount the facet should adjust to preserve its position when results are updated.

Used by the `preservePosition` option.

Default value is `document.body`.

### sortCriteria

sortCriteria: "occurrences" | "score" | "alphaascending" | "alphadescending" | "computedfieldascending" | "computedfielddescending" | "chisquare" | "nosort"

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

Specifies the criteria to use to sort the facet values.

See IGroupByRequest.sortCriteria for the list and description of possible values.

Default value is the first sort criteria specified in the `availableSorts` option, or `occurrences` if no sort criteria is specified.

### title

title: string

- Defined in ui/Facet/Facet.ts :159

Specifies 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'

### useAnd

useAnd: boolean

- Defined in ui/Facet/Facet.ts :338

Specifies whether to use the `AND` operator in the resulting filter when multiple values are selected in the facet.

Setting this option to `true` means that items must have all of the selected values to match the resulting query.

Default value is `false`, which means that the filter uses the `OR` operator. Thus, by default, items must have at least one of the selected values to match the query.

Default

  `false`

Markup configuration example(s) :

    data-use-and='true'
    data-use-and='false'

### useWildcardsInFacetSearch

useWildcardsInFacetSearch: boolean

- Defined in ui/Facet/Facet.ts :408

Specifies whether [wildcards]{@link AllowedValuesPatternType.wildcards} are used as the allowedValuesPatternType in the groupBy for the facet search.

Enabling this option returns results that end with the entered value. For example, searching for `veo` would match with `Coveo`.

Note:

> If you are experiencing slow facet search and/or timeouts when this option is set to `true`, consider enabling the Use cache for nested queries option on your facet field in the Coveo Cloud Admninistration Console (see Add or Edit Fields).

Default

  `false`

Markup configuration example(s) :

    data-use-wildcards-in-facet-search='true'
    data-use-wildcards-in-facet-search='false'

### valueCaption

valueCaption: IStringMap<string>

- Defined in ui/Facet/Facet.ts :714

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

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='CoveoFacet' data-field='@myotherfield' data-value-caption='{"txt":"Text files","html":"Web page"}'></div>

Note:

> Using value captions will disable alphabetical sorts (see the availableSorts option).

## Constructors

### constructor

- new Facet(element: HTMLElement, options: IFacetOptions, bindings?: IComponentBindings, facetClassId?: string): Facet

- Overwrites Component.constructor

  - Defined in ui/Facet/Facet.ts :762

  Creates a new `Facet` component. Binds multiple query events as well.

  #### Parameters

  - ##### element: HTMLElement

    The HTMLElement on which to instantiate the component.

  - ##### options: IFacetOptions

    The options for the `Facet` component.

  - ##### Optional bindings: IComponentBindings

    The bindings that the component requires to function normally. If not set, these will be automatically resolved (with a slower execution time).

  - ##### Default value facetClassId: string = Facet.ID

    The ID to use for this facet (as `Facet` inherited from by other component (e.g., `FacetRange`). Default value is `Facet`.

  #### Returns Facet

### Implements

- IFieldValueCompatibleFacet