SearchBox

This is for:

Developer

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

Methods

clear

Clears the search box text and the suggestions.

hideSuggestions

Clears 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

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 will be called on state change.

Parameters

  • listener: () ⇒ void

    A callback to be invoked on state change.

Returns Unsubscribe: An unsubscribe function to remove the listener.

Attributes

state

The state of the SearchBox controller.

Properties

  • isLoading: boolean

    Determines if a search 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: Engine<QuerySection & QuerySuggestionSection & ConfigurationSection & QuerySetSection & SearchSection>

    The headless engine.

  • props: SearchBoxProps

    The configurable SearchBox properties.

Returns SearchBox

SearchBoxProps

The configurable SearchBox properties.

Properties

SearchBoxOptions

Properties

  • enableQuerySyntax?: boolean

    Whether to interpret advanced query syntax in the query.

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

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

Example Implementation

search-box.fn.tsx

import {useEffect, useState, FunctionComponent} from 'react';
import {
  buildSearchBox,
  SearchBox as HeadlessSearchBox,
  SearchBoxOptions,
} from '@coveo/headless';
import {engine} from '../../engine';
 
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
 
const options: SearchBoxOptions = {numberOfSuggestions: 8};
const controller = buildSearchBox(engine, {options});
 
<SearchBox controller={controller} />;