renderState

Object with state data about all widgets.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

const { renderState } = useInstantSearch();

About this widget

The renderState property provides all the data and functions from the widgets. It lets you access the render state of any widget, so you can create custom widgets or refine the search outside the InstantSearch lifecycle.

This is mainly useful for creating components that interact with multiple widgets at once, without mounting as many widgets. A good example would be showing which individual hit is applied.

Examples

You can access the render state of the searchBox widget.

JavaScript

const indexName = "<index-name>";

function App({ searchClient }) {
  return (
    <InstantSearch indexName={indexName} searchClient={searchClient}>
      <SearchBox />
      <RenderState />
    </InstantSearch>
  );
}

function RenderState() {
  const { renderState, indexRenderState } = useInstantSearch();

  console.log(renderState[indexName].searchBox);
  console.log(indexRenderState.searchBox);
  /*
  {
    query: string;
    refine: Function;
    clear: Function;
    isSearchStalled: boolean;
    widgetParams: object;
  }
*/

  return null;
}

Working with virtual widgets

To access the renderState of widgets, you must add them to InstantSearch. If you don’t want to add a widget to the UI, but want to get access to its renderState, you can add it as a virtual, or renderless widget.

JavaScript

function VirtualPagination(props) {
  usePagination(props);
  return null;
}

function NextPage() {
  const { indexRenderState } = useInstantSearch();

  return (
    <button
      onClick={() =>
        indexRenderState.pagination?.refine(
          indexRenderState.pagination?.currentRefinement + 1,
        )
      }
    >
      Next Page
    </button>
  );
}

function App({ searchClient }) {
  return (
    <InstantSearch indexName="indexName" searchClient={searchClient}>
      <VirtualPagination />
      <NextPage />
    </InstantSearch>
  );
}

Example: interactive categories in a hit

This example displays a list of categories in a hit, and lets users refine the search by clicking on them.

JavaScript

function App({ searchClient }) {
  return (
    <InstantSearch indexName="indexName" searchClient={searchClient}>
      <SearchBox />
      <RefinementList attribute="categories" />
      <Hits hitComponent={HitComponent} />
    </InstantSearch>
  );
}

function HitComponent({ hit }) {
  const { indexRenderState } = useInstantSearch();
  const refine = indexRenderState.refinementList?.categories?.refine;

  return (
    <div>
      <Highlight hit={hit} attribute="name" />
      <ul>
        {hit.categories.map((category) => (
          <li key={category}>
            <button
              onClick={() => {
                refine(category);
              }}
            >
              {category}
            </button>
          </li>
        ))}
      </ul>
    </div>
  );
}

Type definition

TypeScript

type RenderState = {
  [indexId: string]: IndexRenderState;
}

type IndexRenderState = Partial<{
  searchBox: SearchBoxState;
  autocomplete: AutocompleteState;
  breadcrumb: BreadcrumbState;
  clearRefinements: ClearRefinementsState;
  configure: ConfigureState;
  currentRefinements: CurrentRefinementsState;
  hierarchicalMenu: {
    [attribute: string]: HierarchicalMenuState;
  }
  hits: HitsState;
  infiniteHits: InfiniteHitsState;
  analytics: AnalyticsState;
  places: PlacesState;
  poweredBy: PoweredByState;
  range: {
    [attribute: string]: RangeState;
  ratingMenu: {
    [attribute: string]: RatingMenuState;
  };
  numericMenu: {
    [attribute: string]: NumericMenuState;
  };
  voiceSearch: VoiceSearchState;
  geoSearch: GeoSearchState;
  queryRules: QueryRulesState;
  hitsPerPage: HitsPerPageState;
  pagination: PaginationState;
  refinementList: {
    [attribute: string]: RefinementListState;
  };
  answers: AnswersState;
}>;