uiState

About this widget

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.

Vue InstantSearch v2

uiState only works when the widgets responsible for each UI state attribute are mounted. For example, a searchBox widget is necessary to provide a query`.

FVue InstantSearch v3 and later

The uiState passed to initialUiState or through routing needs to be nested per index. For example, if you only have a root index called “INDEX_NAME”, you should use a value like { INDEX_NAME: { query: 'query' } }.≈

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.

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
const uiState = {
  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.