searchBox

Lets users perform a search using text input.

Signature

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

Import

Package manager

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

const { searchBox } = instantsearch.widgets;
// or directly use instantsearch.widgets.searchBox()

See this widget in action

Preview this widget and its behavior.

About this widget

The searchBox widget is used to let users perform a text-based .

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.

string

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

searchBox({
  container: document.querySelector("#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,
});

aiMode · boolean · default: false

Whether to show an AI Mode button in the search box. When users click this button, it opens the Chat widget and sends the current query.

To use this option, add a chat() widget on the same index. For an end-to-end walkthrough, see Build an AI-powered search experience.

JavaScript

searchBox({
  // ...
  aiMode: true,
});

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.
• aiModeButton: the AI mode button.
• aiModeIcon: the AI mode icon.
• aiModeLabel: the AI mode label.

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.

function

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

// String-based templates are deprecated, use functions instead.
searchBox({
  // ...
  templates: {
    submit: "submit",
  },
});

reset · string | function

The template used for displaying the reset button.

function

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

// String-based templates are deprecated, use functions instead.
searchBox({
  // ...
  templates: {
    reset: "reset",
  },
});

loadingIndicator · string | function

The template used for displaying the loading indicator.

function

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

// String-based templates are deprecated, use functions instead.
searchBox({
  // ...
  templates: {
    loadingIndicator: "loading",
  },
});

aiMode · string | function

The template used for displaying the AI Mode button.

function

searchBox({
  // ...
  templates: {
    aiMode({ cssClasses }, { html }) {
      return html`<span class="${cssClasses.aiModeLabel}">Ask AI</span>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
searchBox({
  // ...
  templates: {
    aiMode: "Ask AI",
  },
});

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>
    <button
      class="ais-AiModeButton"
      type="button"
      title="AI Mode"
    >
      <svg class="ais-AiModeButton-icon" viewBox="0 0 24 24">
        ...
      </svg>
      <span class="ais-AiModeButton-label">AI Mode</span>
    </button>
  </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.

Package manager

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

const { connectSearchBox } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectSearchBox()

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

HTML

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

// 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"),
  }),
]);