> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# searchBox
> Lets users perform a search using text input.
export const SearchQuery = () =>
search query
;
```ts Signature theme={"system"}
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
```js Package manager theme={"system"}
import { searchBox } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { searchBox } = instantsearch.widgets;
// or directly use instantsearch.widgets.searchBox()
```
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
```js JavaScript icon=code theme={"system"}
searchBox({
container: "#searchbox",
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
searchBox({
container: "#searchbox",
});
```
```js HTMLElement theme={"system"}
searchBox({
container: document.querySelector("#searchbox"),
});
```
The placeholder text of the input.
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
placeholder: "Search for products",
});
```
Whether the input should be autofocused.
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
autofocus: true,
});
```
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.
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
ignoreCompositionEvents: true,
});
```
If `false`, triggers the search only on submit.
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
searchAsYouType: false,
});
```
Whether to show the reset button.
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
showReset: false,
});
```
Whether to show the submit button.
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
showSubmit: false,
});
```
Whether to show the loading indicator (replaces the submit button if the search is stalled).
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
showLoadingIndicator: false,
});
```
Whether to show an AI Mode button in the search box.
When users click this button, it opens the [Chat](/doc/api-reference/widgets/chat/js) 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](/doc/guides/building-search-ui/going-further/chat-customization/ai-search-experience/js).
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
aiMode: true,
});
```
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](/doc/guides/building-search-ui/going-further/improve-performance/js).
* Programmatically alter the query.
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
queryHook(query, search) {
search(query);
},
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
searchBox({
// ...
templates: {
// ...
},
});
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):
* `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.
```js JavaScript icon=code theme={"system"}
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
The template used for displaying the submit button.
```js function theme={"system"}
searchBox({
// ...
templates: {
submit({ cssClasses }, { html }) {
return html`submit`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
searchBox({
// ...
templates: {
submit: "submit",
},
});
```
The template used for displaying the reset button.
```js function theme={"system"}
searchBox({
// ...
templates: {
reset({ cssClasses }, { html }) {
return html`reset`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
searchBox({
// ...
templates: {
reset: "reset",
},
});
```
The template used for displaying the loading indicator.
```js function theme={"system"}
searchBox({
// ...
templates: {
loadingIndicator({ cssClasses }, { html }) {
return html`loading`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
searchBox({
// ...
templates: {
loadingIndicator: "loading",
},
});
```
The template used for displaying the AI Mode button.
```js function theme={"system"}
searchBox({
// ...
templates: {
aiMode({ cssClasses }, { html }) {
return html`Ask AI`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
searchBox({
// ...
templates: {
aiMode: "Ask AI",
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## 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.
```js Package manager theme={"system"}
import { connectSearchBox } from "instantsearch.js/es/connectors";
```
```js CDN theme={"system"}
const { connectSearchBox } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectSearchBox()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 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).
```js JavaScript icon=code theme={"system"}
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
The query from the current search.
```js JavaScript icon=code theme={"system"}
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;
};
```
Sets a new query and triggers a new search.
```js JavaScript icon=code theme={"system"}
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;
};
```
Removes the query and triggers a new search.
```js JavaScript icon=code theme={"system"}
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;
};
```
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`](/doc/api-reference/widgets/instantsearch/js)
constructor with the attribute `stalledSearchDelay`.
```js JavaScript icon=code theme={"system"}
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;
};
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
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`.
```js JavaScript icon=code theme={"system"}
const customSearchBox = connectSearchBox(renderSearchBox);
search.addWidgets([
customSearchBox({
// Optional parametersqueryHook:function,
}),
]);
```
#### Instance options
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](/doc/guides/building-search-ui/going-further/improve-performance/js).
* programmatically alter the query.
```js JavaScript icon=code theme={"system"}
customSearchBox({
queryHook(query, search) {
search(query);
},
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// 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"),
}),
]);
```