API Reference / InstantSearch.js / searchBox

searchBox

A
Signature 
instantsearch.widgets.searchBox({
  container: string|HTMLElement,
  // Optional parameters
  placeholder: string,
  autofocus: boolean,
  searchAsYouType: boolean,
  showReset: boolean,
  showSubmit: boolean,
  showLoadingIndicator: boolean,
  queryHook: function,
  templates: object,
  cssClasses: object,
});
See code examples
See live example

About this widget # A

The searchBox widget is used to let the user perform a text-based query.

This usually is the main entry point to start the search in an InstantSearch context. It’s usually placed at the top of a search experience, so that the user can start searching right away.

Examples # A

Copy 
1
2
3

instantsearch.widgets.searchBox({
  container: '#searchbox',
});

Options # A

container #
type: string|HTMLElement
Required

The CSS Selector or HTMLElement to insert the widget into.
Copy 
1
2
3

instantsearch.widgets.searchBox({
  container: '#searchbox',
});
placeholder #
type: string
Optional

The placeholder text of the input.
Copy 
1
2
3
4

instantsearch.widgets.searchBox({
  // ...
  placeholder: 'Search for products',
});
autofocus #
type: boolean
default: false
Optional

Whether the input should be autofocused.
Copy 
1
2
3
4

instantsearch.widgets.searchBox({
  // ...
  autofocus: true,
});
searchAsYouType #
type: boolean
default: true
Optional

If false, triggers the search only on submit.
Copy 
1
2
3
4

instantsearch.widgets.searchBox({
  // ...
  searchAsYouType: false,
});
showReset #
type: boolean
default: true
Optional

Whether to show the reset button.
Copy 
1
2
3
4

instantsearch.widgets.searchBox({
  // ...
  showReset: false,
});
showSubmit #
type: boolean
default: true
Optional

Whether to show the submit button.
Copy 
1
2
3
4

instantsearch.widgets.searchBox({
  // ...
  showSubmit: false,
});
showLoadingIndicator #
type: boolean
default: true
Optional

Whether to show the loading indicator (replaces the submit button if the search is stalled).
Copy 
1
2
3
4

instantsearch.widgets.searchBox({
  // ...
  showLoadingIndicator: false,
});
queryHook #
type: function
Optional

A function that is called just before the search is triggered. It takes two parameters:

  • query: string: the current query string
  • search: function: a function to trigger the search.

If the search method is not called, no search is made to Algolia and the UI doesn’t refresh. If the search method is called, the widget is rendered.

This can be useful if you need to:

  • debounce the number of searches done from the searchBox. You can find more information in the guide on slow network.
  • programmatically alter the query.
Copy 
1
2
3
4
5
6

instantsearch.widgets.searchBox({
  // ...
  queryHook(query, search) {
    search(query);
  },
});
templates #
type: object
Optional

The templates to use for the widget.
Copy 
1
2
3
4
5
6

instantsearch.widgets.searchBox({
  // ...
  templates: {
    // ...
  },
});
cssClasses #
type: object

The CSS classes to override.

  • root: the root element of the widget.
  • form: the form element.
  • input: the input element.
  • reset: the reset button element.
  • resetIcon: the reset button icon.
  • loadingIndicator: the loading indicator element.
  • loadingIcon: the loading indicator icon.
  • submit: the submit button element.
  • submitIcon: the submit button icon.
Copy 
1
2
3
4
5
6
7
8
9
10

instantsearch.widgets.searchBox({
  // ...
  cssClasses: {
    root: 'MyCustomSearchBox',
    form: [
      'MyCustomSearchBoxForm',
      'MyCustomSearchBoxForm--subclass',
    ],
  },
});

Templates # A

submit #
type: string|function
Optional

The template used for displaying the submit button.
Copy 
1
2
3
4
5
6

instantsearch.widgets.searchBox({
  // ...
  templates: {
    submit: 'submit',
  },
});
reset #
type: string|function
Optional

The template used for displaying the reset button.
Copy 
1
2
3
4
5
6

instantsearch.widgets.searchBox({
  // ...
  templates: {
    reset: 'reset',
  },
});
loadingIndicator #
type: string|function
Optional

The template used for displaying the loading indicator.
Copy 
1
2
3
4
5
6

instantsearch.widgets.searchBox({
  // ...
  templates: {
    loadingIndicator: 'loading',
  },
});

HTML output# A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<div class="ais-SearchBox">
  <form class="ais-SearchBox-form" novalidate>
    <input class="ais-SearchBox-input" autocomplete="off" autocorrect="off" autocapitalize="off" placeholder="Search for products" spellcheck="false" maxlength="512" type="search" value="" />
    <button class="ais-SearchBox-submit" type="submit" title="Submit the search query.">
      <svg class="ais-SearchBox-submitIcon" xmlns="http://www.w3.org/2000/svg" width="10" height="10" viewBox="0 0 40 40">
        ...
      </svg>
    </button>
    <button class="ais-SearchBox-reset" type="reset" title="Clear the search query." hidden>
      <svg class="ais-SearchBox-resetIcon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="10" height="10">
        ...
      </svg>
    </button>
    <span class="ais-SearchBox-loadingIndicator" hidden>
      <svg width="16" height="16" viewBox="0 0 38 38" xmlns="http://www.w3.org/2000/svg" stroke="#444" class="ais-SearchBox-loadingIcon">
        ...
      </svg>
    </span>
  </form>
</div>

Customize the UI with connectSearchBox# A

If you want to create your own UI of the searchBox widget, you can use connectors.

It’s a 3-step process:

// 1. Create a render function
const renderSearchBox = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customSearchBox = instantsearch.connectors.connectSearchBox(
  renderSearchBox
);

// 3. Instantiate
search.addWidgets([
  customSearchBox({
    // instance params
  })
]);

See code examples

Create a render function#

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

const renderSearchBox = (renderOptions, isFirstRender) => {
  const {
    string query,
    function refine,
    function clear,
    boolean isSearchStalled,
    object widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
}

Render options #

query #
type: string

The query from the current search.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

const renderSearchBox = (renderOptions, isFirstRender) => {
  const { query, refine } = renderOptions;

  const container = document.querySelector('#searchbox');

  if (isFirstRender) {
    const input = document.createElement('input');

    input.addEventListener('input', event => {
      refine(event.target.value);
    });

    container.appendChild(input);
  }

  container.querySelector('input').value = query;
};
refine #
type: function

Sets a new query and triggers a new search.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

const renderSearchBox = (renderOptions, isFirstRender) => {
  const { query, refine } = renderOptions;

  const container = document.querySelector('#searchbox');

  if (isFirstRender) {
    const input = document.createElement('input');

    input.addEventListener('input', event => {
      refine(event.target.value);
    });

    container.appendChild(input);
  }

  container.querySelector('input').value = query;
};
clear #
type: function

Removes the query and triggers a new search.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

const renderSearchBox = (renderOptions, isFirstRender) => {
  const { query, refine, clear } = renderOptions;

  const container = document.querySelector('#searchbox');

  if (isFirstRender) {
    const input = document.createElement('input');
    const button = document.createElement('button');
    button.textContent = 'X';

    input.addEventListener('input', event => {
      refine(event.target.value);
    });

    button.addEventListener('click', () => {
      clear();
    });

    container.appendChild(input);
    container.appendChild(button);
  }

  container.querySelector('input').value = query;
};
isSearchStalled #
type: boolean

Returns true if the search results take more than a certain time to come back from Algolia servers. This can be configured on the instantsearch constructor with the attribute stalledSearchDelay.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

const renderSearchBox = (renderOptions, isFirstRender) => {
  const { query, refine, isSearchStalled } = renderOptions;

  const container = document.querySelector('#searchbox');

  if (isFirstRender) {
    const input = document.createElement('input');
    const loadingIndicator = document.createElement('span');
    loadingIndicator.textContent = 'Loading...';

    input.addEventListener('input', event => {
      refine(event.target.value);
    });

    container.appendChild(input);
    container.appendChild(loadingIndicator);
  }

  container.querySelector('input').value = query;
  container.querySelector('span').hidden = !isSearchStalled;
};
widgetParams #
type: object

All original widget options forwarded to the render function.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

const renderRangeInput = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = '...';
};

// ...

search.addWidgets([
  customRangeInput({
    container: document.querySelector('#searchbox'),
  })
]);

Create and instantiate the custom widget#

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

  • Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
  • Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customSearchBox = instantsearch.connectors.connectSearchBox(
  renderSearchBox
);

search.addWidgets([
  customSearchBox({
    // Optional parameters
    queryHook: function,
  })
]);

Instance options #

queryHook #
type: function
Optional

A function that is called just before the search is triggered. It takes two parameters

  • query: string: the current query string
  • search: function: a function to trigger the search.

If the search method is not called, no search is made to Algolia and the UI doesn’t refresh. If the search method is called, the widget is rendered.

This can be useful if you need to:

  • debounce the number of searches done from the searchBox. You can find more information in the guide on slow network.
  • programmatically alter the query.
Copy 
1
2
3
4
5

customSearchBox({
  queryHook(query, search) {
    search(query);
  },
});

Full example#

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// Create a render function
const renderSearchBox = (renderOptions, isFirstRender) => {
  const { query, refine, clear, isSearchStalled, widgetParams } = renderOptions;

  if (isFirstRender) {
    const input = document.createElement('input');

    const loadingIndicator = document.createElement('span');
    loadingIndicator.textContent = 'Loading...';

    const button = document.createElement('button');
    button.textContent = 'X';

    input.addEventListener('input', event => {
      refine(event.target.value);
    });

    button.addEventListener('click', () => {
      clear();
    });

    widgetParams.container.appendChild(input);
    widgetParams.container.appendChild(loadingIndicator);
    widgetParams.container.appendChild(button);
  }

  widgetParams.container.querySelector('input').value = query;
  widgetParams.container.querySelector('span').hidden = !isSearchStalled;
};

// create custom widget
const customSearchBox = instantsearch.connectors.connectSearchBox(
  renderSearchBox
);

// instantiate custom widget
search.addWidgets([
  customSearchBox({
    container: document.querySelector('#searchbox'),
  })
]);
Did you find this page helpful?
InstantSearch.js v4