Input element which accepts search terms and triggers a new search query.

Example


import { SearchBox } from "@elastic/react-search-ui";

...

<SearchBox />

Configuring search queries

The input from SearchBox will be used to trigger a new search query. That query can be further customized in the SearchProvider configuration, using the searchQuery property. See the Search Query Configuration guide for more information.

Example of passing custom props to text input element

<SearchBox inputProps={{ placeholder: "custom placeholder" }} />

Example using autocomplete results

"Results" are search results. The default behavior for autocomplete results is to link the user directly to a result when selected, which is why a "titleField" and "urlField" are required for the default view.

<SearchBox
  autocompleteResults={{
    titleField: "title",
    urlField: "nps_link"
  }}
/>

Example using autocomplete suggestions

"Suggestions" are different than "results". Suggestions are suggested queries. Unlike an autocomplete result, a suggestion does not go straight to a result page when selected. It acts as a regular search query and refreshes the result set.

<SearchBox autocompleteSuggestions={true} />

Example using autocomplete suggestions and autocomplete results

The default view will show both results and suggestions, divided into sections. Section titles can be added to help distinguish between the two.

<SearchBox
  autocompleteResults={{
    sectionTitle: "Suggested Results",
    titleField: "title",
    urlField: "nps_link"
  }}
  autocompleteSuggestions={{
    sectionTitle: "Suggested Queries"
  }}
/>

Example retrieving suggestions from another index

Supported only by the Elasticsearch-connector

A different index can be used for the suggestions. Some examples:

  • Popular queries index from analytics
  • Brands index from product data
  • Categories index from product data

Below we are using the popular_queries index and performing a prefix match search on the query.suggest field. One thing to note, make sure the api-key has access to the index.


#### Autocomplete Configuration

```js
autocompleteQuery: {
  suggestions: {
    types: {
      popularQueries: {
        search_fields: {
          "query.suggest": {} // fields used to query
        },
        result_fields: {
          query: { // fields used for display
            raw: {}
          }
        },
        index: "popular_queries",
        queryType: "results"
      }
    },
    size: 4
  }
}

Component Configuration

<SearchBox
  autocompleteSuggestions={{
    popularQueries: {
      queryType: "results",
      displayField: "query" // specify which field used to display the suggestion
    },
    }
  }}
/>

You also have the option to customise the view of the autocomplete to show more fields.

Configuring autocomplete queries

Autocomplete queries can be customized in the SearchProvider configuration, using the autocompleteQuery property. See the Autocomplete Query Configuration for more information.

<SearchProvider
    config={{
      ...
      autocompleteQuery: {
        // Customize the query for autocompleteResults
        results: {
          result_fields: {
            // Add snippet highlighting
            title: { snippet: { size: 100, fallback: true } },
            nps_link: { raw: {} }
          }
        },
        // Customize the query for autocompleteSuggestions
        suggestions: {
          types: {
            // Limit query to only suggest based on "title" field
            documents: { fields: ["title"] }
          },
          // Limit the number of suggestions returned from the server
          size: 4
        }
      }
    }}
>
    <SearchBox
      autocompleteResults={{
        sectionTitle: "Suggested Results",
        titleField: "title",
        urlField: "nps_link"
      }}
      autocompleteSuggestions={{
        sectionTitle: "Suggested Queries",
      }}
    />
</SearchProvider>

Example using multiple types of autocomplete suggestions

"Suggestions" can be generated via multiple methods. They can be derived from common terms and phrases inside of documents, or be "popular" queries generated from actual search queries made by users. This will differ depending on the particular Search API you are using.

Note: Elastic App Search currently only supports type "documents", and Elastic Site Search and Workplace Search do not support suggestions. This is purely illustrative in case a Connector is used that does support multiple types.

<SearchProvider
    config={{
      ...
      autocompleteQuery: {
        suggestions: {
          types: {
            documents: { },
            // FYI, this is not a supported suggestion type in any current connector, it's an example only
            popular_queries: { }
          }
        }
      }
    }}
>
    <SearchBox
      autocompleteSuggestions={{
        // Types used here need to match types requested from the server
        documents: {
          sectionTitle: "Suggested Queries",
        },
        popular_queries: {
          sectionTitle: "Popular Queries"
        }
      }}
    />
</SearchProvider>

Example using autocomplete in a site header

This is an example from a Gatsby site, which overrides "submit" to navigate a user to the search page for suggestions, and maintaining the default behavior when selecting a result.

<SearchBox
  autocompleteResults={{
    titleField: "title",
    urlField: "nps_link"
  }}
  autocompleteSuggestions={true}
  onSubmit={(searchTerm) => {
    navigate("/search?q=" + searchTerm);
  }}
  onSelectAutocomplete={(selection, {}, defaultOnSelectAutocomplete) => {
    if (selection.suggestion) {
      navigate("/search?q=" + selection.suggestion);
    } else {
      defaultOnSelectAutocomplete(selection);
    }
  }}
/>

Properties

NameDescription
className
shouldClearFilters
Should existing filters be cleared when a new search is performed?
inputProps
Props for underlying 'input' element. I.e., { placeholder: "Enter Text"}.
searchAsYouType
Executes a new search query with every key stroke. You can fine tune the number of queries made by adjusting the debounceLength parameter.
debounceLength
When using searchAsYouType, it can be useful to "debounce" search requests to avoid creating an excessive number of requests. This controls the length to debounce / wait.
autocompleteResults
Configure and autocomplete search results. Boolean option is primarily available for implementing custom views.
autocompleteSuggestions
Configure and autocomplete query suggestions. Boolean option is primarily available for implementing custom views. Configuration may or may not be keyed by "Suggestion Type", as APIs for suggestions may support may than 1 type of suggestion. If it is not keyed by Suggestion Type, then the configuration will be applied to the first type available.
autocompleteMinimumCharacters
Minimum number of characters before autocompleting.
onSelectAutocomplete
Allows overriding behavior when selected, to avoid creating an entirely new view. In addition to the current selection, various helpers are passed as options to the second parameter. This third parameter is the default onSelectAutocomplete, which allows you to defer to the original behavior.
onSubmit
Allows overriding behavior when submitted. Receives the search term from the search box.
autocompleteView
Used to override only the autocomplete dropdown. See Autocomplete view customization below.
inputView
Used to override only the input box. See Input view customization below.
view
Used to override the default view for this Component. See Full view customization below.
*
Any other property passed will be passed through and available to use in a Custom View

AutocompleteResultsOptions

NameDescription
linkTarget
Used to open links in a new tab.
sectionTitle
Title to show in section within dropdown.
shouldTrackClickThrough
Only applies to Results, not Suggestions.
clickThroughTags
Tags to send to analytics API when tracking clickthrough.
titleField
Field within a Result to use as the "title".
urlField
Field within a Result to use for linking.

AutocompleteSuggestionsOptions

NameDescription
sectionTitle
Title to show in section within dropdown

View customization

A complete guide to view customization can be found in the Customization: Component views and HTML section.

Full view customization

You can customize the entire view using the view prop. This is useful to use an entirely different autocomplete library (we use downshift). A SearchBox component at its simplest could look like the following:

<SearchBox
  view={({ value, onChange, onSubmit }) => (
    <form onSubmit={onSubmit}>
      <input
        type="text"
        value={value}
        onChange={(e) => onChange(e.target.value)}
      />
      <input type="submit" value="Search" />
    </form>
  )}
/>

The full list of props available to this view are as follows:

NameDescription
className
Passed through from main component.
inputView
Component to use for text input. When rendering, pass all props documented below in the Input view customization section.
Note that this can be challenging to do since some of the required props are generated by Downshift. It's generally advised not to try to use this property directly when creating a custom view.
isFocused
Type: boolean. Whether or not the input currently has focus. Will only work if you have correct spread inputProps over your input box.
onChange
Type: (value: string) => void. When a user changes the input of the search input box, call this with the new value.
onSubmit
Type: (e: FormEvent) => void. Handle a "submission" of the search box. Typically used directly on a form element surrounding your input box.
value
Type: string. The current user input to show in the input box.
inputProps
An object containing props that should be spread over the input box element. You'll need to do this in order to have the isFocused prop work.
autocompleteView
Component to use for Autocomplete. When rendering, pass all props documented below in the Autocomplete view customization section.
Note that this can be challenging to do since some of the required props are generated by Downshift. It's generally advised not to try to use this property directly when creating a custom view.
completeSuggestion
Type: (searchQuery: string) => void.
notifyAutocompleteSelected
Type: (selection: any) => void.
autocompletedSuggestionsCount
Type: number.
autocompleteSuggestions
Type: boolean | AutocompleteSuggestion.
autocompletedSuggestions
Type: AutocompletedSuggestions.
autocompletedResults
Type: AutocompletedResult[].
autocompleteResults
Type: AutocompleteResult | boolean.
onSelectAutocomplete
Type: (selectedItem: any) => void. Call this with the selected item (whether it is a result or a suggestion) when an autocomplete selection is made in the autocomplete dropdown.
allAutocompletedItemsCount
Type: number. The number of items that would be shown in an autocomplete. If 0, no need to show the autocomplete.
useAutocomplete
Type: boolean. Whether or not to show an autocomplete dropdown.

See SearchBox.tsx for an example.

Input view customization

For making small customizations, like simply hiding the search button, or rearranging DOM structure, full customization is often overkill.

You can also just customize the input section of the search box using the inputView prop.

<SearchBox
  inputView={({ getAutocomplete, getInputProps, getButtonProps }) => (
    <>
      <div className="sui-search-box__wrapper">
        <input
          {...getInputProps({
            placeholder: "I am a custom placeholder"
          })}
        />
        {getAutocomplete()}
      </div>
      <input
        {...getButtonProps({
          "data-custom-attr": "some value"
        })}
      />
    </>
  )}
/>

Note that getInputProps and getButtonProps are prop getters. They are meant return a props object to spread over their corresponding UI elements. This lets you arrange elements however you'd like in the DOM. It also lets you pass additional properties. You should pass properties through these functions, rather directly on elements, in order to not override base values. For instance, adding a className through these functions will assure that the className is only appended, not overriding the base class values.

getAutocomplete is used to determine where the autocomplete dropdown will be shown.

The full list of props available to this view are as follows:

NameDescription
getAutocomplete
Type: () => JSX.Element. Call this method wherever you would like your autocomplete to appear. Typically, directly below your input box.
getButtonProps
Type: () => Object. Spread the return value of this function over your "Search" button, which submit your search.
getInputProps
Type: () => JSX. Spread the return value of this function over the input element you are using for your search box.

See SearchInput.tsx for an example.

Autocomplete view customization

In addition to the inputView customization, you can also make targed customization to the autocomplete view using the autocompleteView prop.

For example:

<SearchBox
  autocompleteView={({ autocompletedResults, getItemProps }) => (
    <div className="sui-search-box__autocomplete-container">
      {autocompletedResults.map((result, i) => (
        <div
          {...getItemProps({
            key: result.id.raw,
            item: result
          })}
        >
          Result {i}: {result.title.snippet}
        </div>
      ))}
    </div>
  )}
/>

The full list of props available to this view are as follows:

NameDescription
allAutocompletedItemsCount
Type: number. The number of items that would be shown in an autocomplete. If 0, no need to show the autocomplete.
autocompleteResults
Type: boolean | AutocompleteResult. Configuration object passed through from main component.
autocompletedResults
Type: AutocompletedResult[]. The search results generated by an autocomplete query.
autocompletedSuggestions
Type: AutocompletedSuggestions. The suggestions generated by an autocomplete suggestions query.
autocompletedSuggestionsCount
Type: number. The total number of suggestions generated by an autocomplete suggestions query.
autocompleteSuggestions
Type: boolean | AutocompleteSuggestion. Configuration object passed through from main component.
onSelectAutocomplete
Type: (selectedItem: any) => void. Call this with the selected item (whether it is a result or a suggestion) when an autocomplete selection is made in the autocomplete dropdown.
getItemProps
Type: { key: string, index: number, item: AutocompletedSuggestion }) => any. A function that will generate props to spread over an individual item in the autocomplete list.
getMenuProps
Type: ({ className: string }) => any. A function that will generate props to spread over the main autocomplete dropdown element.

See Autocomplete.tsx for an example.