StandaloneSearchBox (Search Engine)

This is for:

Developer

Example Implementation

standalone-search-box.fn.tsx

import {
  buildStandaloneSearchBox,
  StandaloneSearchBoxOptions,
} from '@coveo/headless';
import {useEffect, useState, FunctionComponent, useContext} from 'react';
import {AppContext} from '../../context/engine';
import {standaloneSearchBoxStorageKey} from './standalone-search-box-storage-key';
 
export const StandaloneSearchBox: FunctionComponent<
  StandaloneSearchBoxOptions
> = (props) => {
  const {engine} = useContext(AppContext);
  const controller = buildStandaloneSearchBox(engine!, {options: props});
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  function isEnterKey(e: React.KeyboardEvent<HTMLInputElement>) {
    return e.key === 'Enter';
  }
 
  if (!state) {
    return null;
  }
 
  if (state.redirectTo) {
    const {redirectTo, value, analytics} = state;
    const data = JSON.stringify({value, analytics});
    localStorage.setItem(standaloneSearchBoxStorageKey, data);
    window.location.href = redirectTo;
    return null;
  }
 
  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
 * <StandaloneSearchBox id="ssb-1" redirectionUrl="/search-page"/>;
 * ```
 */

The StandaloneSearchBox headless controller offers a high-level interface for designing a common search box UI controller. Meant to be used for a search box that will redirect instead of executing a query.

Methods

afterRedirection

Resets the standalone search box state. To be dispatched on single page applications after the redirection has been triggered.

submit

Triggers a redirection.

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.

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

A scoped and simplified part of the headless state that is relevant to the StandaloneSearchBox controller.

Properties

  • analytics: InitialData | SearchFromLinkData | OmniboxFromLinkData

    The analytics data to send when performing the first query on the search page the user is redirected to.

  • redirectTo: string

    The Url to redirect to.

  • 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

buildStandaloneSearchBox

Creates a StandaloneSearchBox instance.

Parameters

  • engine: SearchEngine

    The headless engine.

  • props: StandaloneSearchBoxProps

    The configurable StandaloneSearchBox properties.

Returns StandaloneSearchBox

StandaloneSearchBoxProps

The configurable StandaloneSearchBox properties.

Properties

StandaloneSearchBoxOptions

Properties

  • redirectionUrl: string

    The default Url the user should be redirected to, when a query is submitted. If a query pipeline redirect is triggered, it will redirect to that Url instead.

  • 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 (e.g., 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;