index

Scopes a group of widgets to a specific index in multi-index search interfaces.

Signature

index({
  // Required unless isolated is true
  indexName?: string,
  // Optional parameters
  indexId?: string,
  isolated?: boolean,
});

Import

Package manager

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

See this widget in action

Preview this widget and its behavior.

About this widget

This widget lets you apply widgets to a specific index.

It’s useful when building interfaces that target multiple indices such as federated searches.

The position of index in the widgets tree affects which search parameters apply. Widgets that create search parameters forward them to their child index widgets.

JavaScript

search.addWidgets([
  searchBox(),
  hits(),

  index({ indexName: "instant_search" }).addWidgets([
    // The index inherits from the parent's `searchBox` search parameters
    hits(),
  ]),
]);

The only exception to this rule is when two widgets own the same part of your UI state, like two searchBox widgets or two refinementList widgets on the same attribute. In that case, the latter takes precedence and overrides the search parameters.

JavaScript

search.addWidgets([
  searchBox(),
  hits(),

  index({ indexName: "instant_search" }).addWidgets([
    // The index does not inherit from the parent's `searchBox` search parameters
    searchBox(),
    hits(),
  ]),
]);

The same rule applies when you nest multiple index widgets.

Examples

JavaScript

index({ indexName: "instant_search" }).addWidgets([
  // Add widgets
  // ...
]);

Options

indexName · string

The index to search into. This option is required unless isolated is true.

JavaScript

index({
  indexName: "instant_search",
});

indexId · string · default: "value provided for indexName"

An identifier for the index widget.

Providing an indexId lets different index widgets target the same Algolia index. It’s helpful for routing. It lets you find the refinements that match an index widget.

JavaScript

index({
  // ...
  indexId: "instant_search_one",
});

isolated · boolean · default: false

By default, an index widget is included in the main InstantSearch request. When isolated is true, the widget performs its own search requests instead. It doesn’t send an initial search request when InstantSearch starts. Instead, it searches only after one of its child widgets changes the search state.

When isolated is true, the index:

• Searches separately instead of being included in the main search request.
• Isn’t included in the URL or UI state.
• Isn’t included in server-side rendering.

You can omit indexName when isolated is true. EXPERIMENTAL_isolated is a deprecated alias. Use isolated instead.

JavaScript

index({
  indexName: "instant_search",
  isolated: true,
});

Methods

addWidgets

Adds one or more widgets to the index.

JavaScript

const index = index({
  indexName: "instant_search",
});

const searchBox = searchBox({
  // ...
});

const hits = hits({
  // ...
});

index.addWidgets([searchBox, hits]);

removeWidgets

Removes one or more widgets from the index widget. To be properly removed, the widget instances you pass must have a dispose() method.

JavaScript

const index = index({
  indexName: "instant_search",
});

const searchBox = searchBox({
  // ...
});

const hits = hits({
  // ...
});

index.removeWidgets([searchBox, hits]);

updateWidget

Replaces one widget with another, in place. Use it to change a widget’s parameters without losing the state that widget owns: the previous widget’s UI state is handed over to the new one.

State the new widget doesn’t claim anymore, such as a refinement on an attribute that changed, is dropped, as when you remove a widget. The new widget also keeps the position of the widget it replaces, so the order in which widgets contribute to the search parameters is unchanged.

The previous widget must have a dispose() method, and the new one an init() or a render() method.

JavaScript

const searchIndex = index({
  indexName: "instant_search",
});

const previousBrands = refinementList({
  container: "#brands",
  attribute: "brand",
  limit: 5,
});

searchIndex.addWidgets([previousBrands]);

const nextBrands = refinementList({
  container: "#brands",
  attribute: "brand",
  limit: 10,
});

// The brands users refined by are preserved
searchIndex.updateWidget(previousBrands, nextBrands);