instantsearch()

Main factory function to create an InstantSearch instance

The instantsearch() function creates and returns an InstantSearch instance that manages your search UI and coordinates all widgets.

Signature

function instantsearch<TUiState = Record<string, unknown>, TRouteState = TUiState>(
  options: InstantSearchOptions<Expand<UiState & TUiState>, TRouteState>
): InstantSearch<Expand<UiState & TUiState>, TRouteState>

Parameters

options · InstantSearchOptions · required

Configuration options for the InstantSearch instance. See InstantSearchOptions for all available options.

Returns

Returns an InstantSearch instance with the following properties and methods.

InstantSearch Class

Properties

client · SearchClient | CompositionClient

The search client used to communicate with Algolia.

indexName · string

The name of the main index.

compositionID · string | undefined

The objectID of the composition when using the composition API.

helper · AlgoliaSearchHelper | null

The Algolia search helper instance. Available after start() is called.

mainHelper · AlgoliaSearchHelper | null

The main helper instance used for queries.

started · boolean

Whether the InstantSearch instance has been started.

status · InstantSearchStatus

The current status of the search. Can be "idle", "loading", "stalled", or "error".

error · Error | undefined

The last error returned from the Search API. Cleared when the next valid search response is rendered.

renderState · RenderState

The current render state containing all widget render information.

Methods

start()

Initializes InstantSearch.js and triggers the first search.

start(): void

Example:

const search = instantsearch({
  indexName: 'products',
  searchClient: algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey')
});

search.start();

The start() method can only be called once. Calling it multiple times will throw an error.

addWidgets()

Adds multiple widgets to the search instance. Widgets can be added before or after InstantSearch has started.

addWidgets(
  widgets: Array<Widget | IndexWidget | Array<IndexWidget | Widget>>
): this

widgets · Array<Widget | IndexWidget | Array<Widget | IndexWidget>> · required

Array of widget instances to add to InstantSearch.

Example:

search.addWidgets([
  searchBox({ container: '#searchbox' }),
  hits({ container: '#hits' }),
  pagination({ container: '#pagination' })
]);

removeWidgets()

Removes multiple widgets from the search instance.

removeWidgets(
  widgets: Array<Widget | IndexWidget | Widget[]>
): this

widgets · Array<Widget | IndexWidget | Widget[]> · required

Array of widget instances to remove from InstantSearch. Widgets must implement a dispose() method.

Example:

const paginationWidget = pagination({ container: '#pagination' });
search.addWidgets([paginationWidget]);

// Later...
search.removeWidgets([paginationWidget]);

setUiState()

Sets the UI state and triggers a search.

setUiState(
  uiState: TUiState | ((previousUiState: TUiState) => TUiState),
  callOnStateChange?: boolean
): void

uiState · TUiState | ((previousUiState: TUiState) => TUiState) · required

The next UI state or a function that computes it from the current state.

callOnStateChange · boolean · default: "true"

Internal parameter used to control whether the onStateChange callback is called.

Example:

// Set UI state directly
search.setUiState({
  indexName: {
    query: 'laptop',
    page: 2
  }
});

// Update UI state from previous state
search.setUiState((prevState) => ({
  ...prevState,
  indexName: {
    ...prevState.indexName,
    query: 'laptop'
  }
}));

getUiState()

Returns the current UI state.

getUiState(): TUiState

Returns: The current UI state object.

Example:

const uiState = search.getUiState();
console.log(uiState);
// { indexName: { query: 'laptop', page: 1 } }

createURL()

Creates a URL from a UI state.

createURL(nextState?: TUiState): string

nextState · TUiState

The UI state to create a URL from. Defaults to the current UI state.

Returns: A URL string representing the UI state.

The start() method must be called before using createURL().

use()

Hooks middleware into the InstantSearch lifecycle.

use(...middleware: Array<Middleware<TUiState>>): this

middleware · Array<Middleware<TUiState>> · required

One or more middleware functions to add to the InstantSearch instance.

Example:

import { createInsightsMiddleware } from 'instantsearch.js/es/middlewares';

const insightsMiddleware = createInsightsMiddleware({
  insightsClient: window.aa
});

search.use(insightsMiddleware);

unuse()

Removes middleware from the InstantSearch lifecycle.

unuse(...middleware: Array<Middleware<TUiState>>): this

middleware · Array<Middleware<TUiState>> · required

One or more middleware functions to remove from the InstantSearch instance.

Example:

search.unuse(insightsMiddleware);

refresh()

Clears the cache and triggers a new search.

refresh(): void

Example:

search.refresh();

The start() method must be called before using refresh().

dispose()

Removes all widgets and cleans up the InstantSearch instance without triggering a search.

dispose(): void

Example:

search.dispose();

Events

The InstantSearch instance extends EventEmitter and emits the following events:

render

Emitted every time a search is done and the UI is rendered.

search.on('render', () => {
  console.log('Search complete and UI updated');
});

error

Emitted when an error occurs during search.

search.on('error', (error) => {
  console.error('Search error:', error);
});

Basic Example

import instantsearch from 'instantsearch.js';
import algoliasearch from 'algoliasearch/lite';
import { searchBox, hits, pagination } from 'instantsearch.js/es/widgets';

const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

const search = instantsearch({
  indexName: 'products',
  searchClient,
  routing: true
});

search.addWidgets([
  searchBox({ container: '#searchbox' }),
  hits({ container: '#hits' }),
  pagination({ container: '#pagination' })
]);

search.start();

TypeScript Example

import instantsearch from 'instantsearch.js';
import algoliasearch from 'algoliasearch/lite';
import type { UiState } from 'instantsearch.js';

interface MyUiState extends UiState {
  products: {
    query?: string;
    page?: number;
    refinementList?: {
      category?: string[];
    };
  };
}

const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

const search = instantsearch<MyUiState>({
  indexName: 'products',
  searchClient,
  initialUiState: {
    products: {
      query: 'laptop'
    }
  }
});

search.start();

Deprecated Methods

The following methods are deprecated and will be removed in future versions.

addWidget()

Deprecated. Use addWidgets([widget]) instead.

addWidget(widget: Widget): this

removeWidget()

Deprecated. Use removeWidgets([widget]) instead.

removeWidget(widget: Widget | IndexWidget): this

EXPERIMENTAL_use()

Deprecated. Use use() instead. The middleware API is now stable.

EXPERIMENTAL_use(...middleware: Middleware[]): this