> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# uiState

> Object with the state of your search UI.

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

<div className="not-prose algolia-flavor-switcher">
  <div className="afs-dropdown">
    <div className="afs-trigger" role="button" tabIndex="0" aria-haspopup="listbox">
      <span className="afs-current">JavaScript</span>

      <svg className="afs-chevron lucide lucide-chevron-down" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <path d="m6 9 6 6 6-6" />
      </svg>
    </div>

    <ul className="afs-menu" role="listbox">
      <li role="option" aria-selected="true"><a className="afs-option is-current" href="/doc/api-reference/widgets/ui-state/js"><span className="afs-option-name">JavaScript</span><span className="afs-option-lib">InstantSearch.js</span></a></li>
      <li role="option" aria-selected="false"><a className="afs-option" href="/doc/api-reference/widgets/ui-state/react"><span className="afs-option-name">React</span><span className="afs-option-lib">React InstantSearch</span></a></li>
      <li role="option" aria-selected="false"><a className="afs-option" href="/doc/api-reference/widgets/ui-state/vue"><span className="afs-option-name">Vue</span><span className="afs-option-lib">Vue InstantSearch</span></a></li>
    </ul>
  </div>
</div>

<Note>
  You are viewing the documentation for **InstantSearch.js v4**.
  To upgrade from v3, see the [migration guide](/doc/guides/building-search-ui/upgrade-guides/js#upgrade-from-v3-to-v4).
  Looking for the v3 version of this page?
  [View the v3 docs](https://algolia.com/old-docs/deprecated/instantsearch/js/v3/api-reference/ui-state).
</Note>

## 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
  ([routing](/doc/api-reference/widgets/instantsearch/js#param-routing))

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 />.

```js JavaScript icon=code theme={"system"}
const 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.
To learn more, see [Custom widgets](/doc/guides/building-search-ui/widgets/create-your-own-widgets/js#interact-with-routing).