Skip to main content
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

import { searchBox } from "instantsearch.js/es/widgets";
View demo

​
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

JavaScript
searchBox({
  container: "#searchbox",
});

​
Options

​
container
string | HTMLElement
required
The CSS Selector or HTMLElement to insert the widget into.
searchBox({
  container: "#searchbox",
});
​
placeholder
string
The placeholder text of the input.
JavaScript
searchBox({
  // ...
  placeholder: "Search for products",
});
​
autofocus
boolean
default:false
Whether the input should be autofocused.
JavaScript
searchBox({
  // ...
  autofocus: true,
});
​
ignoreCompositionEvents
boolean
default:false
since: v4.64.2
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.
JavaScript
searchBox({
  // ...
  ignoreCompositionEvents: true,
});
​
searchAsYouType
boolean
default:true
If false, triggers the search only on submit.
JavaScript
searchBox({
  // ...
  searchAsYouType: false,
});
​
showReset
boolean
default:true
Whether to show the reset button.
JavaScript
searchBox({
  // ...
  showReset: false,
});
​
showSubmit
boolean
default:true
Whether to show the submit button.
JavaScript
searchBox({
  // ...
  showSubmit: false,
});
​
showLoadingIndicator
boolean
default:true
Whether to show the loading indicator (replaces the submit button if the search is stalled).
JavaScript
searchBox({
  // ...
  showLoadingIndicator: false,
});
​
queryHook
function
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.
JavaScript
searchBox({
  // ...
  queryHook(query, search) {
    search(query);
  },
});
​
templates
object
The templates to use for the widget.
JavaScript
searchBox({
  // ...
  templates: {
    // ...
  },
});
​
cssClasses
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.
JavaScript
searchBox({
  // ...
  cssClasses: {
    root: "MyCustomSearchBox",
    form: ["MyCustomSearchBoxForm", "MyCustomSearchBoxForm--subclass"],
  },
});

​
Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.
The html function is available in InstantSearch.js version 4.46.0 or later.
​
submit
string | function
The template used for displaying the submit button.
searchBox({
  // ...
  templates: {
    submit({ cssClasses }, { html }) {
      return html`<span class="${cssClasses.submit}">submit</span>`;
    },
  },
});
​
reset
string | function
The template used for displaying the reset button.
searchBox({
  // ...
  templates: {
    reset({ cssClasses }, { html }) {
      return html`<span class="${cssClasses.reset}">reset</span>`;
    },
  },
});
​
loadingIndicator
string | function
The template used for displaying the loading indicator.
searchBox({
  // ...
  templates: {
    loadingIndicator({ cssClasses }, { html }) {
      return html`<span class="${cssClasses.loadingIndicator}">loading</span>`;
    },
  },
});

​
HTML output

HTML
<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. 
import { connectSearchBox } from "instantsearch.js/es/connectors";
Then it’s a 3-step process:
JavaScript
// 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
  }),
]);

​
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).
JavaScript
const renderSearchBox = (renderOptions, isFirstRender) => {
  const { query, refine, clear, isSearchStalled, widgetParams } = renderOptions;

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

  // Render the widget
};

​
Render options

​
query
string
The query from the current search.
JavaScript
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
function
Sets a new query and triggers a new search.
JavaScript
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
function
Removes the query and triggers a new search.
JavaScript
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
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.
JavaScript
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
object
All original widget options forwarded to the render function.
JavaScript
const renderRangeInput = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = "...";
};

// ...

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

​
Create and instantiate the custom widget

First, create your custom widgets using a rendering function. Then, instantiate them with parameters. There are two kinds of parameters you can pass:
  • Instance parameters. Predefined options that configure Algolia’s behavior.
  • Custom parameters. Parameters you define to make the widget reusable and adaptable.
Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.
JavaScript
const customSearchBox = connectSearchBox(renderSearchBox);

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

​
Instance options

​
queryHook
function
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.
JavaScript
customSearchBox({
  queryHook(query, search) {
    search(query);
  },
});

​
Full example

<div id="searchbox"></div>
⌘I