widgets searchBox

Description

The searchbox widget is used to let the user set a text based query.

This is usually the main entry point to start the search in an instantsearch context. For that reason is usually placed on top, and not hidden so that the user can start searching right away.

Live example

You can find an example at the end of the page or a live example in our widget showcase.

Usage

const search = instantsearch( /* parameters */ );

const widget = instantsearch.widgets.searchBox({ 
  container: string|HTMLElement, 
  placeholder: [string], 
  autofocus: [boolean], 
  searchAsYouType: [boolean], 
  showReset: [boolean], 
  showSubmit: [boolean], 
  showLoadingIndicator: [boolean], 
  cssClasses: [SearchBoxCSSClasses], 
  templates: [SearchBoxTemplates], 
  queryHook: [function], 
}: SearchBoxWidgetOptions);

search.addWidget(widget);

Options

SearchBoxWidgetOptions

• containerstring|HTMLElement

  CSS Selector or HTMLElement to insert the widget

• placeholder[string]

  The placeholder of the input

• autofocus[boolean]
  Default value: false

  Whether the input should be autofocused

• searchAsYouType[boolean]
  Default value: true

  If set, trigger the search once <Enter> is pressed only.

• showReset[boolean]
  Default value: true

  Whether to show the reset button

• showSubmit[boolean]
  Default value: true

  Whether to show the submit button

• showLoadingIndicator[boolean]
  Default value: true

  Whether to show the loading indicator (replaces the submit if the search is stalled)

• cssClasses[SearchBoxCSSClasses]

  CSS classes to add

• templates[SearchBoxTemplates]

  Templates used for customizing the rendering of the searchbox

• queryHook[function]

  A function that is called every time a new search is done. You will get the query as the first parameter and a search (query) function to call as the second parameter. This queryHook can be used to debounce the number of searches done from the search box.

SearchBoxCSSClasses

• root[string|Array<string>]

  CSS class to add to the wrapping <div>

• form[string|Array<string>]

  CSS class to add to the form

• input[string|Array<string>]

  CSS class to add to the input.

• submit[string|Array<string>]

  CSS classes added to the submit button.

• submitIcon[string|Array<string>]

  CSS classes added to the submit icon.

• reset[string|Array<string>]

  CSS classes added to the reset button.

• resetIcon[string|Array<string>]

  CSS classes added to the reset icon.

• loadingIndicator[string|Array<string>]

  CSS classes added to the loading indicator element.

• loadingIcon[string|Array<string>]

  CSS classes added to the loading indicator icon.

SearchBoxTemplates

• submitfunction|string

  Template used for displaying the submit. Can accept a function or a Hogan string.

• resetfunction|string

  Template used for displaying the button. Can accept a function or a Hogan string.

• loadingIndicatorfunction|string

  Template used for displaying the button. Can accept a function or a Hogan string.

Widget

• render[function]

  Called after each search response has been received

• getConfiguration[function]

  Let the widget update the configuration of the search with new parameters

• init[function]

  Called once before the first search

Example

search.addWidget(
  instantsearch.widgets.searchBox({
    container: '#q',
    placeholder: 'Search for products',
  })
);

Can't find what you are looking for? Open an issue, we'll get back to you.