widgets searchBox

Edit this page

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

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

const widget = instantsearch.widgets.searchBox({ container: string|HTMLElement, placeholder: [string], poweredBy: [boolean|SearchBoxPoweredByOption], reset: [boolean|SearchBoxResetOption], magnifier: [boolean|SearchBoxMagnifierOption], loadingIndicator: [boolean|SearchBoxLoadingIndicatorOption], wrapInput: [boolean], autofocus: [boolean|string], searchOnEnterKeyPressOnly: [boolean], cssClasses: [SearchBoxCSSClasses], queryHook: [function], }: SearchBoxWidgetOptions);
search.addWidget(widget);

Options

SearchBoxWidgetOptions

  • containerstring|HTMLElement

    CSS Selector or HTMLElement to insert the widget. If the CSS selector or the HTMLElement is an existing input, the widget will use it.

  • placeholder[string]

    Input’s placeholder.

  • poweredBy[boolean|SearchBoxPoweredByOption]
    Default value: false

    Define if a “powered by Algolia” link should be added near the input.

  • reset[boolean|SearchBoxResetOption]
    Default value: true

    Define if a reset button should be added in the input when there is a query.

  • magnifier[boolean|SearchBoxMagnifierOption]
    Default value: true

    Define if a magnifier should be added at beginning of the input to indicate a search input.

  • loadingIndicator[boolean|SearchBoxLoadingIndicatorOption]
    Default value: false

    Define if a loading indicator should be added at beginning of the input to indicate that search is currently stalled.

  • wrapInput[boolean]
    Default value: true

    Wrap the input in a div.ais-search-box.

  • autofocus[boolean|string]
    Default value: "auto"

    autofocus on the input.

  • searchOnEnterKeyPressOnly[boolean]
    Default value: false

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

  • cssClasses[SearchBoxCSSClasses]

    CSS classes to add.

  • queryHook[function]

    A function that will be called every time a new search would be done. You will get the query as 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 searchBox.

SearchBoxPoweredByOption

  • templatefunction|string

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

  • cssClasses[SearchBoxPoweredByCSSClasses]

    CSS classes added to the powered-by badge.

SearchBoxPoweredByCSSClasses

  • root[string|Array<string>]

    CSS class to add to the root element.

SearchBoxResetOption

  • templatefunction|string

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

  • cssClasses[{root: string}]

    CSS classes added to the reset button.

SearchBoxMagnifierOption

  • templatefunction|string

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

  • cssClasses[{root: string}]

    CSS classes added to the magnifier.

SearchBoxLoadingIndicatorOption

  • templatefunction|string

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

  • cssClasses[{root: string}]

    CSS classes added to the loading-indicator element.

SearchBoxCSSClasses

  • root[string|Array<string>]

    CSS class to add to the wrapping <div> (if wrapInput set to true).

  • input[string|Array<string>]

    CSS class to add to the input.

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',
    autofocus: false,
    poweredBy: true,
    reset: true,
    loadingIndicator: false
  })
);

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