Skip to end of metadata
Go to start of metadata


This component displays a facet of the results for the current query. A facet consists of a list of values for a given field occurring in the results, ordered using a configurable criteria. The list of values is obtained using a groupBy   operation performed at the same time as the main query (see Group By Parameters).

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



title : "the title"
element data-title="the title"/>  

Specifies the title displayed at the top of the facet.


field : "@field"
<element data-field="@field"/>

Specifies the field whose values will be use in the facet.


lookupField : "@field"
<element data-lookup-field="@field"/>

Specifies the field whose values will be displayed in the facet.


numberOfValues : 5
<element data-number-of-values="5"/>

Specifies the maximum number of field values that will be displayed by default in the facet. The default value is 5.


sortCriteria: "occurrences"
<element data-sort-criteria="occurrences"/>

Specifies the criteria used to sort facet values. The default value is the first value of availableSorts list. If sortCriteria is empty, the default value will be occurrences. Refer to the Group By Parameters page for the list of available values.


availableSorts: ["occurrences","score","alphaAscending","alphaDescending"]
<element data-available-sorts="occurrences,score,alphaAscending,alphaDescending"/>

Specifies the criteria you want to be displayed in the facet settings menu. The default value is occurrences,score,alphaAscending,alphaDescending.

Available values are: occurrencesscorealphaAscendingalphaDescendingcomputedfieldascendingcomputedfielddescendingcustom.


customSort: ["New","Opened","Feedback","Resolved","Feedback"]
<element data-custom-sort="New,Opened,Feedback,Resolved"/>

Specifies a custom order by which facet values are sorted. For example, you could use this to specify a logical order for support tickets.


This option is intended for facets with a low cardinality, i.e. that have just a few values.



Specifies the injection depth that will be used for the group by operation. The default value is 1000.

The injection depth determines how many results are scanned to ensure all potential facet values are listed. Increasing this value enhances the accuracy of the listed values, at the cost of performance.

injectionDepth : 1000
<element data-injection-depth="1000"/>


showIcon: true
<element data-show-icon="true"/>

Specifies whether an icon is displayed next to each facet value. The default value is false.

You can also use the valueIcon option to register a callback used to resolve icons.


headerIcon: "the css class"

<element data-header-icon="the css class" />

Specifies the css class to change the facet header icon. 


useAnd: false
<element data-use-and="false"/>

Specifies whether the filter generated when multiple values are selected uses the AND operator, meaning that only items having all selected values match the resulting query. By default, filters use the OR operator, and the resulting query matches all items with at least one of the selected values.


allowTogglingOperator: false
<element data-allow-toggling-operator="false"/>

Specifies whether the user is allowed to toggle between OR and AND mode, using an icon in the top right corner of the facet. The default value is false.


Specifies a function which takes the facet value as a parameter and returns the URL of the icon to use. 

This option can only be set in the init call of your interface, not directly as an HTML attribute.


Specifies a JSON object describing a map of facet value -> desired caption

This option can only be set in the init call of your interface, not directly as an HTML attribute.

You can also use a function to do the same thing, but :


Using a function to determine the facet caption is not recommended. The facet search and the OmniBox Component would be deactivated for this facet since they would not be able to work correctly due to technical reason. It can still however be useful in certain specific case.


Using valueCaption will disabled sort by alpha


enableFacetSearch: true
<element data-enable-facet-search="true"/>

Specifies whether the search box for searching inside the available values will be displayed at the bottom of the facet. The default value is true.


facetSearchDelay: 100
<element data-facet-search-delay="100"/>

Specifies the delay (in milliseconds) before a search is sent to the server when the user starts typing in the facet search box. Using a smaller value means that results will arrive faster, but it increases the chances that many of the requests sent to the server get cancelled as the user continues typing in characters. Default is 100


enableSettings: true
<element data-enable-settings="true"/>

Specifies whether to show the facet settings menu. The default value is true


numberOfValuesInFacetSearch: 15
<element data-number-of-values-in-facet-search="15"/>

Specifies the number of values displayed in the facet search results popup. The default value is 15.


includeInBreadCrumb: true
<element data-include-in-breadcrumb="true"/>

Specifies if the facet should push data to the Coveo.Ui.Breadcrumb. The default value is true


numberOfValuesInBreadcrumb: 5
<element data-number-of-values-in-breadcrumb="5"/>

Specifies the maximum number of values that the facet should display in the breadcrumb. Default is 5


uniqueId: MyFacet
<element data-id="MyFacet"/>

Specifies a unique identifier for a facet. This identifier will be used to save the facet state in the url hash, for example. Optional, since the default will be the field option.


If you have two facets with the same field on the same page, you should specify a data-id for at least one of those two facets. That id need to be unique on the page.


includeInOmniBox: true
<element data-include-in-omnibox="true"/>

Specifies if the facet should push data to the OmniBox Component. The default value is false.


computedField: @syssize
<element data-computed-field="@syssize"/>

Specifies the name of a field on which an aggregate operation should be executed for all distinct values of the facet's field. The result of the operation is displayed along with the number of occurrences for each value.


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


computedFieldOperation: sum
<element data-computed-field-operation="sum"/>

Specifies the type of aggregate operation to use on the computed field. The default value is sum

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


computedFieldFormat: c0
<element data-computed-field-format="c0"/>

Specifies how to format the values resulting from a computed field operation. The formats available are defined by the Globalize library. The most common 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.

More information can be obtained in the library's documentation (see Globalize.format). 


Specifies what will be the caption of the computed field in the settings menu for sort. For example, the value Money will be displayed as Money Ascending for computed field ascending. the default value is Computed Field.

computedFieldCaption : "caption"
<element data-computed-field-caption="caption"/>


preservePosition: true
<element data-preserve-position="true"/>

Specifies whether the facet should remain stable in its current position in the viewport while the mouse is over it. The default value is true.

Whenever values are selected in a facet, a new query is automatically performed. This new query might cause other elements in the page to be resized (typically other facets above the one being used). When this option is enabled, the facet will adjust the scroll amount of the page to ensure that it does not move relative to the mouse when the results are updated. In some cases, the facet will also add margin to the scrollContainer, if scrolling alone is not enough to preserve position.


scrollContainer: #myContainerId
<element data-scroll-container="#myContainerId"/>

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


isMultiValueField: boolean
<element data-is-multi-value-field="false"/>

Specifies if the facet has multiple values. The default value is false.


morePageSize: number
<element data-page-size="5"/>

Specifies the number of additional pages to fetch. The default value is 10.


enableCollapse: boolean
<element data-enable-collapse="true"/>

Specifies if the facet is collapsible. The default value is true.


enableMoreLess: boolean
<element data-enable-more-less="true"/>

Specifies if the more/less button is enabled. The default value is true.


paddingContainer: HTMLElement
<element data-padding-container="true"/>

Specifies the parent container of the facets. The default value is element.parentElement.


allowedValues: ["File","People"]

<element data-allowed-values='File,People' />

Specifies an explicit list of allowedValues in the group by request. (See :  Group By Parameters )


additionalFilter: @sysdate>=2014/01/01

<element data-additional-filter='@sysdate>=2014/01/01' />

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


facetSearchIgnoreAccentsfalse by default

<element data-facet-search-ignore-accents='true' />

Specifies if the accents are ignored in the facet search.


enableSettingsFacetStatefalse by default

<element data-enable-settings-facet-state='true' />

Specifies if the save state is available on the facet.


Available in: June 2015 Release

dependsOn: undefined by default

<element data-depends-on='@parentfacetfield' />

Specifies that the facet appears only when a value is selected in its "parent" facet. 



$('#myFacet').coveo('selectValue', value:string)

Selects a field value in the facet.

value : The field value to select.


$('#myFacet').coveo('selectMultipleValues', values: string[])

Selects multiple field values in the facet.

values : The field values to select.


$('#myFacet').coveo('deselectValue', value:string)

Deselects a field value in the facet.

value  : The field value to deselect.


$('#myFacet').coveo('deselectMultipleValues', values: string[])

Deselects multiple field values in the facet.

values : The field values to deselect.


$('#myFacet').coveo('excludeValue', value:string)

Excludes a field value in the facet.

value  : The field value to exclude.


$('#myFacet').coveo('excludeMultipleValues', values: string[])

Excludes field values in the facet.

values : The field values to exclude.


$('#myFacet').coveo('unexcludeValue', value:string)

Unexcludes a field value in the facet.

value  : The field value to unexclude.


$('#myFacet').coveo('unexcludeMultipleValues', values: string[])

Unexcludes field values in the facet.

values : The field values to unexclude.



Returns the list of values currently being displayed in the facet.



Returns the list of values currently selected in the facet.



Returns the list of values currently excluded in the facet.



Clears any currently selected or excluded value from the facet.



Enable the facet.



Disable the facet.



Returns the endpoint.



Switches the facet mode to AND.



Switches the facet mode to OR.



Expands the facet if it is currently collapsed.



Collapses the facet if it is currently expanded.





  • No labels


  1. Is there a way to wrap long facet item labels instead of the default behavior consisting in truncating with ellipsis?

    1. Add this css rule to your page :

  2. Hi All! Is there a way to assign code to the "click" or "change" function of a facet value in the list? I'm looking to use the search option of a facet to show the type-ahead list as the user types...then when they select an item in the list, redirect them to a "results" page, filtered by the same item they selected.



    1. From what I understand, you could you use the OmniBox Component and the TopFieldSuggestions Component (this component does exactly the same thing as a facet search) to achieve the same result.

      You would only need to change the onSelect option of the TopFieldSuggestions Component to redirect to your page with  /mySearchPage.html#f:@thefieldname=[theselectedvalue]

  3. Would that limit the user to only select a value from the list? We don't want them to enter random text and click the search button.


    1. If you create only an OmniBox Component instead of a SearchBox Component (which create both a query box and a SearchButton Component ) there will be no search button.

      Then you can hijack the keyup event on the search box, and if it's Enter (keycode 13), you can block the query from being sent by blocking the event propagation.
      You could also reset the query box content when they hit Enter.