SearchBox (Search Engine)

This is for:

Developer

Example Implementation

search-box.fn.tsx

import {SearchBox as HeadlessSearchBox} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
 
interface SearchBoxProps {
  controller: HeadlessSearchBox;
}
 
export const SearchBox: FunctionComponent<SearchBoxProps> = (props) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
  const isEnterKey = (e: React.KeyboardEvent<HTMLInputElement>) =>
    e.key === 'Enter';
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  return (
    <div>
      <input
        value={state.value}
        onChange={(e) => controller.updateText(e.target.value)}
        onKeyDown={(e) => isEnterKey(e) && controller.submit()}
      />
      <ul>
        {state.suggestions.map((suggestion) => {
          const value = suggestion.rawValue;
          return (
            <li key={value} onClick={() => controller.selectSuggestion(value)}>
              {value}
            </li>
          );
        })}
      </ul>
    </div>
  );
};
 
// usage
 
/**
 * ```tsx
 * const options: SearchBoxOptions = {numberOfSuggestions: 8};
 * const controller = buildSearchBox(engine, {options});
 *
 * <SearchBox controller={controller} />;
 * ```
 */

The SearchBox headless controller offers a high-level interface for designing a common search box UI controller with highlighting for query suggestions.

Methods

clear

Clears the search box text and the suggestions.

selectSuggestion

Selects a suggestion and calls submit.

Parameters

  • value: string

    The string value of the suggestion to select

showSuggestions

Shows the suggestions for the current search box value.

submit

Deselects all facets and triggers a search query.

updateText

Updates the search box text value and shows the suggestions for that value.

Parameters

  • value: string

    The string value to update the search box with.

subscribe

Adds a callback that’s invoked on state change.

Parameters

  • listener: () => void

    A callback that’s invoked on state change.

Returns Unsubscribe: A function to remove the listener.

Attributes

state

The state of the SearchBox controller.

Properties

  • isLoading: boolean

    Determines if a search is in progress.

  • isLoadingSuggestions: boolean

    Determines if a query suggest request is in progress.

  • suggestions: Suggestion[]

    The query suggestions for the search box query.

  • value: string

    The current query in the search box.

Initialize

buildSearchBox

Creates a SearchBox controller instance.

Parameters

  • engine: SearchEngine

    The headless engine.

  • props: SearchBoxProps

    The configurable SearchBox properties.

Returns SearchBox

SearchBoxProps

The configurable SearchBox properties.

Properties

SearchBoxOptions

The SearchBox controller options.

Properties

  • clearFilters?: boolean

    Whether to clear all active query filters when the end user submits a new query from the search box. Setting this option to "false" is not recommended & can lead to an increasing number of queries returning no results.

  • enableQuerySyntax?: boolean

    Whether to interpret advanced Coveo Cloud query syntax in the query.

    Default: false

  • highlightOptions?: SuggestionHighlightingOptions

    Specifies delimiters to highlight parts of a query suggestion that e.g match, do not match the query.

  • id?: string

    A unique identifier for the controller. By default, a unique random identifier is generated.

  • numberOfSuggestions?: number

    The number of query suggestions to request from Coveo ML (for example, 3).

    Using the value 0 disables the query suggest feature.

    Default: 5

Delimiters

Properties

  • close: string

    Closing delimiter

  • open: string

    Opening delimiter

Suggestion

Properties

  • highlightedValue: string

    The suggestion after applying any highlightOptions.

  • rawValue: string

    The suggestion text.

SuggestionHighlightingOptions

Properties

  • correctionDelimiters?: Delimiters

    Delimiters for substrings that are correction of the input

  • exactMatchDelimiters?: Delimiters

    Delimiters for substrings that are exact match of the input

  • notMatchDelimiters?: Delimiters

    Delimiters for substrings that do not match the input

Unsubscribe

Call signatures

  • (): void