UI libraries / InstantSearch.js / Widgets

searchBox

Signature 
searchBox({
  container: string|HTMLElement,
  // Optional parameters
  placeholder: string,
  autofocus: boolean,
  ignoreCompositionEvents: boolean,
  searchAsYouType: boolean,
  showReset: boolean,
  showSubmit: boolean,
  showLoadingIndicator: boolean,
  queryHook: function,
  templates: object,
  cssClasses: object,
});
Import
Copy 
1

import { searchBox } from 'instantsearch.js/es/widgets';
See code examples
See live example

About this widget

The searchBox widget is used to let users 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 users can start searching right away.

Examples

Copy 
1
2
3

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

Options

Parameter Description
container
type: string|HTMLElement
Required

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

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

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

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

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

searchBox({
  // ...
  autofocus: true,
});
ignoreCompositionEvents
since: v4.64.2
type: boolean
default: false
Optional

Whether to update the search state in the middle of a composition session. This is useful when users need to search using non-latin characters.
Copy 
1
2
3
4

searchBox({
  // ...
  ignoreCompositionEvents: true,
});
searchAsYouType
type: boolean
default: true
Optional

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

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

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

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

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

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

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

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

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

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

The CSS classes you can 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

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

Templates

You can customize parts of the widget’s UI using the Templates API.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.

The html function is available starting from v4.46.0.

Parameter Description
submit
type: string|function
Optional

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

searchBox({
  // ...
  templates: {
    submit({ cssClasses }, { html }) {
      return html`<span class="${cssClasses.submit}">submit</span>`;
    },
  },
});
reset
type: string|function
Optional

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

searchBox({
  // ...
  templates: {
    reset({ cssClasses }, { html }) {
      return html`<span class="${cssClasses.reset}">reset</span>`;
    },
  },
});
loadingIndicator
type: string|function
Optional

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

searchBox({
  // ...
  templates: {
    loadingIndicator({ cssClasses }, { html }) {
      return html`<span class="${cssClasses.loadingIndicator}">loading</span>`;
    },
  },
});

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.

To use connectSearchBox, you can import it with the declaration relevant to how you installed InstantSearch.js.

Copy 
1

import { connectSearchBox } from 'instantsearch.js/es/connectors';

Then it’s a 3-step process:

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

// 2. Create the custom widget
const customSearchBox = 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

Parameter Description
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 = connectSearchBox(
  renderSearchBox
);

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

Instance options

Parameter Description
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 = connectSearchBox(
  renderSearchBox
);

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