API Reference / InstantSearch.js / searchBox

searchBox

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

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

Copy 
1
2
3

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

Options

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

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

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

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