UI libraries / React InstantSearch / Widgets

uiState

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

About this object

The uiState object represents the state of the search UI and can be saved and returned to later. It’s updated whenever the user interacts with the UI and can be used to:

  • Store the current search query and parameters
  • Pass data to widgets
  • Determine which results to show when a user visits a new page (the routing system)

It doesn’t directly store search results: just the state that leads to those results.

Example

This is an example of an InstantSearch uiState object. It represents what the user has searched for, how they’ve refined the results, and how the results are displayed.

Replace INDEX_NAME with the name of your Algolia index.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

import type { UiState } from 'instantsearch.js';

const uiState: UiState = {
  INDEX_NAME: {
    query: 'Hill Valley',
    refinementList: {
      colors: ['white', 'black']
    },
    configure: {
      distinct: true,
    },
    menu: {
      category: 'Decoration'
    },
    hierarchicalMenu: {
      categories: ['Decoration > Clocks']
    },
    numericMenu: {
      price: '100:500'
    },
    ratingMenu: {
      rating: 4
    },
    range: {
      ageInYears: '2:10'
    },
    toggle: {
      freeShipping: true
    },
    geoSearch: {
      boundingBox: '47.3165,4.9665,47.3424,5.0201'
    },
    sortBy: 'most_popular_index',
    page: 2,
    hitsPerPage: 20
  },
};

Custom widgets

To have your custom widgets interact with the uiState object, you need to implement the getWidgetUiState and getWidgetSearchParameters methods in the connector. You can find more information in the Custom widgets guide.

Did you find this page helpful?
React InstantSearch v7