Support Menu

Coveo component SearchInterface

The SearchInterface component is the root and main component of your Coveo search interface. You should place all other Coveo components inside the SearchInterface component.

It is also on the HTMLElement of the SearchInterface component that you call the init function.

It is advisable to specify a unique HTML id attribute for the SearchInterface component in order to be able to reference it easily.

Example:

<head>

[ ... ]

<script>
  document.addEventListener('DOMContentLoaded', function() {

    [ ... ]
    // The init function is called on the SearchInterface element, in this case, the body of the page.
    Coveo.init(document.body);

    [ ... ]

    });
</script>

[ ... ]
</head>

<!-- Specifying a unique HTML id attribute for the SearchInterface component is good practice. -->
<body id='search' class='CoveoSearchInterface' [ ... other options ... ]>

  [ ... ]

  <!-- You should place all other Coveo components here, inside the SearchInterface component. -->

  [ ... ]

</body>

Index

Component Options

autoTriggerQuery

autoTriggerQuery: boolean

Specifies whether to trigger the first query automatically when the page finishes loading.

Note:

If you set this option to false while the hideUntilFirstQuery option is true, the loading animation will still run until the first query successfully returns.

Default value is true.

Markup configuration example(s) :
data-auto-trigger-query='true'
data-auto-trigger-query='false'

enableAutomaticResponsiveMode

enableAutomaticResponsiveMode: boolean

Specifies whether to enable automatic responsive mode (i.e., automatically placing Facet and Tab components in dropdown menus under the search box when the width of the SearchInterface HTML element reaches or falls behind a certain pixel threshold).

You might want to set this option to false if automatic responsive mode does not suit the specific design needs of your implementation.

Note:

If this option is true, you can also specify whether to enable responsive mode for Facet components (see Facet.options.enableResponsiveMode) and for Tab components (see Tab.options.enableResponsiveMode).

In addition, you can specify the label you wish to display on the dropdown buttons (see Facet.options.dropdownHeaderLabel and Tab.options.dropdownHeaderLabel).

Default value is true.

Markup configuration example(s) :
data-enable-automatic-responsive-mode='true'
data-enable-automatic-responsive-mode='false'

enableCollaborativeRating

enableCollaborativeRating: boolean

Specifies whether to enable the collaborative rating for the index and to include user ratings on each results in addition to the normal index ranking.

If you set this option to true, you can leverage it with the ResultRating component.

Default value is false.

Markup configuration example(s) :
data-enable-collaborative-rating='true'
data-enable-collaborative-rating='false'

enableDebugInfo

enableDebugInfo: boolean

Specifies whether to enable the feature that allows the end user to ALT + double click any result to open a debug page with detailed information about all properties and fields for that result.

Enabling this feature causes no security concern; the entire debug information is always visible to the end user through the browser developer console or by calling the Coveo API directly.

Default value is true.

Markup configuration example(s) :
data-enable-debug-info='true'
data-enable-debug-info='false'

enableDuplicateFiltering

enableDuplicateFiltering: boolean

Specifies whether to filter duplicates in the search results.

Setting this option to true forces duplicates to not appear in search results. However, Facet counts still include the duplicates, which can be confusing for the end user. This is a limitation of the index.

Example:

The end user narrows a query down to a single document that has a duplicate. If the enableDuplicateFiltering option is true, then only one document appears in the search results while the Facet count is still 2.

Note:

It also is possible to set this option separately for each Tab component (see Tab.options.enableDuplicateFiltering).

Default value is false.

Markup configuration example(s) :
data-enable-duplicate-filtering='true'
data-enable-duplicate-filtering='false'

enableHistory

enableHistory: boolean

Specifies whether to allow the end user to navigate search history using the Back and Forward buttons of the browser.

If this options is true, the SearchInterface component saves the state of the current query in the hash portion of the URL when the user submits the query.

Example:

If the enableHistory option is true and the current query is foobar, the SearchInterface component saves q=foobar in the URL hash when the user submits the query.

Default value is false.

Markup configuration example(s) :
data-enable-history='true'
data-enable-history='false'

excerptLength

excerptLength: number

Specifies the number of characters to get at query time to create an excerpt of the result.

This setting is global and cannot be modified on a per-result basis.

See also the Excerpt component.

Default value is 200. Minimum value is 0.

Markup configuration example(s) :
data-excerpt-length='10'

expression

expression: string

Specifies an expression to add to each query.

You might want to use this options to add a global filter to your entire search interface that applies for all tabs.

You should not use this option to address security concerns (it is JavaScript, after all).

Note:

It also is possible to set this option separately for each Tab component (see Tab.options.expression).

Default value is ''.

Markup configuration example(s) :
data-expression='foo'

filterField

filterField: IFieldOption

Specifies the name of a field to use as a custom filter when executing the query (also referred to as "folding").

Setting a value for this option causes the index to return only one result having any particular value inside the filter field. Any other matching result is "folded" inside the childResults member of each JSON query result.

This feature is typically useful with threaded conversations to include only one top-level result per conversation. Thus, the field you specify for this option will typically be value unique to each thread that is shared by all items (e.g., posts, emails, etc) in the thread.

For more advanced features, see the Folding component.

Default value is the empty string ('').

Markup configuration example(s) :
data-filter-field='@foo'

firstLoadingAnimation

firstLoadingAnimation: HTMLElement

Specifies the animation that you wish to display while your interface is loading.

You can either specify the CSS selector of an HTML element that matches the default CSS class (coveo-first-loading-animation), or add -selector to the markup attribute of this option to specify the CSS selector of an HTML element that matches any CSS class.

See also the hideUntilFirstQuery option.

Examples:

In this first case, the SearchInterface uses the HTML element whose id attribute is MyAnimation as the loading animation only if the class attribute of this element also matches coveo-first-loading-animation. Default loading animation CSS, which you can customize as you see fit, applies to this HTML element.

<div class='CoveoSearchInterface' data-first-loading-animation='#MyAnimation'>
  <div id='MyAnimation' class='coveo-first-loading-animation'>
    <!-- ... -->
  </div>
  <!-- ... -->
</div>

In this second case, the SearchInterface uses the HTML element whose id attribute is MyAnimation as the loading animation no matter what CSS class it matches. However, if the class attribute of the HTML element does not match coveo-first-loading-animation, no default loading animation CSS applies to this HTML element. Normally, you should only use data-first-loading-animation-selector if you want to completely override the default loading animation CSS.

<div class='CoveoSearchInterface' data-first-loading-animation-selector='#MyAnimation'>
  <div id='MyAnimation' class='my-custom-loading-animation-class'>
    <!-- ... -->
  </div>
  <!-- ... -->
</div>

See Branding Customization.

By default, the loading animation is a Coveo CSS animation (which you can customize with CSS).

hideUntilFirstQuery

hideUntilFirstQuery: boolean

Specifies whether to display a loading animation before the first query successfully returns.

Note:

If you do not set this options to false, the loading animation will still run until the first query successfully returns even if the autoTriggerQuery option is false.

See also the firstLoadingAnimation option.

Default value is true.

Markup configuration example(s) :
data-hide-until-first-query='true'
data-hide-until-first-query='false'

maximumAge

maximumAge: number

Specifies the maximum age (in milliseconds) that cached query results can have to still be usable as results instead of performing a new query on the index. The cache is located in the Coveo Search API (which resides between the index and the search interface).

If cached results that are older than the age you specify in this option are available, the framework will not use these results; it will rather perform a new query on the index.

On high-volume public web sites, specifying a higher value for this option can greatly improve query response time at the cost of result freshness.

Note:

It also is possible to set this option separately for each Tab component (see Tab.options.maximumAge).

Default value is undefined, which means that the search interface lets the Coveo Search API determine the maximum cache age. This is typically equivalent to 30 minutes (see Query Parameters - maximumAge).

Markup configuration example(s) :
data-maximum-age='10'

pipeline

pipeline: string

Specifies the name of the query pipeline to use for the queries.

You can specify a value for this option if your index is in a Coveo Cloud organization in which pipelines have been created (see Managing Query Pipelines).

Note:

It also is possible to set this option separately for each Tab component (see Tab.options.pipeline).

Default value is undefined, which means that the search interface uses the default pipeline.

Markup configuration example(s) :
data-pipeline='foo'

resultsPerPage

resultsPerPage: number

Specifies the number of results to display on each page.

For more advanced features, see the ResultsPerPage component.

Default value is 10. Minimum value is 0.

Markup configuration example(s) :
data-results-per-page='10'

searchPageUri

searchPageUri: string

Specifies the search page you wish to navigate to when instantiating a standalone search box interface.

Default value is undefined, which means that the search interface does not redirect.

Markup configuration example(s) :
data-search-page-uri='foo'

timezone

timezone: string

Specifies the timezone in which the search interface is loaded. This allows the index to recognize some special query syntax.

This option must have a valid IANA zone info key (AKA the Olson time zone database) as its value.

Example: America/New_York.

By default, the search interface allows a library to try to detect the timezone automatically.

Markup configuration example(s) :
data-timezone='foo'

useLocalStorageForHistory

useLocalStorageForHistory: boolean

Specifies whether to save the interface state in the local storage of the browser.

You might want to set this option to true for reasons specifically important for your implementation.

Default value is false.

Markup configuration example(s) :
data-use-local-storage-for-history='true'
data-use-local-storage-for-history='false'

Methods

attachComponent

  • Attaches a component to the search interface. This allows the search interface to easily list and iterate over its components.

    Parameters

    • type: string

      Normally, the component type is a unique identifier without the Coveo prefix (e.g., CoveoFacet -> Facet, CoveoPager -> Pager, CoveoQuerybox -> Querybox, etc.).

    • component: BaseComponent

      The component instance to attach.

    Returns void

debugInfo

  • debugInfo(): any

detachComponent

  • Detaches a component from the search interface.

    Parameters

    • type: string

      Normally, the component type is a unique identifier without the Coveo prefix (e.g., CoveoFacet -> Facet, CoveoPager -> Pager, CoveoQuerybox -> Querybox, etc.).

    • component: BaseComponent

      The component instance to detach.

    Returns void

disable

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

    Returns void

enable

  • enable(): void
  • 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

getBindings

  • getBindings(): object

getComponents

  • getComponents<T>(type: string): T[]
  • Gets all the components of a given type.

    Type parameters

    • T

    Parameters

    • type: string

      Normally, the component type is a unique identifier without the Coveo prefix (e.g., CoveoFacet -> Facet, CoveoPager -> Pager, CoveoQuerybox -> Querybox, etc.).

    Returns T[]

hideWaitAnimation

  • hideWaitAnimation(): void

isNewDesign

  • isNewDesign(): boolean

showWaitAnimation

  • showWaitAnimation(): void

Properties

disabled

disabled: boolean

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

type

{boolean}

logger

logger: Logger

Allows component to log in the dev console.

responsiveComponents

responsiveComponents: ResponsiveComponents

Allows to get and set the different breakpoints for mobile and tablet devices.

This is useful, among other things, for Facet, Tab and ResultList components.

Static ID

ID: string

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

Constructors

constructor

  • new SearchInterface(element: HTMLElement, options?: ISearchInterfaceOptions, analyticsOptions?: any, _window?: Window): SearchInterface
  • Creates a new SearchInterface. Initialize various singletons for the interface (e.g., usage analytics, query controller, state model, etc.). Binds events related to the query. Hides and shows the loading animation, if activated (see the hideUntilFirstQuery option).

    Parameters

    • element: HTMLElement

      The HTMLElement on which to instantiate the component. This cannot be an HTMLInputElement for technical reasons.

    • Optional options: ISearchInterfaceOptions

      The options for the SearchInterface.

    • Optional analyticsOptions: any

      The options for the Analytics component. Since the Analytics component is normally global, it needs to be passed at initialization of the whole interface.

    • Default value _window: Window = window

      The window object for the search interface. Used for unit tests, which can pass a mock. Default is the global window object.

    Returns SearchInterface

Implements