---
title: State
slug: '344'
canonical_url: https://docs.coveo.com/en/344/
collection: javascript-search-framework
source_format: adoc
---
# State
The Coveo JavaScript Search Framework stores its state in a centralized location using a key-value set (see the [`QueryStateModel`](https://coveo.github.io/search-ui/classes/querystatemodel.html) class).
This state object is updated each time a component state changes, such as when the query in the search box is modified, or when a facet value is selected.
All state changes trigger events which you can monitor with external code.
Certain Coveo components also monitor those state events in order to be able to update themselves when appropriate.
Optionally, the state can be persisted in the query string of the URL to enable browser history management (see the `HistoryController` class).

## Reading and modifying the state

You can read and modify the state object using the [`Coveo.state`](https://coveo.github.io/search-ui/globals.html#state) top-level function:

**Examples**

* Getting the state object:

```javascript
Coveo.state(Coveo.$$(document).find("#search"));
```

* Getting the value of a specific state attribute:

```javascript
Coveo.state(Coveo.$$(document).find("#search"), "q");
```

* Setting the value of a specific state attribute:

```javascript
Coveo.state(Coveo.$$(document).find("#search"), "q", "new value");
```

The `q` attribute in the previous two examples corresponds to the current query in the `Querybox`.
When setting a new value (as in the third example), the `Querybox` component automatically updates its content to the new value.

It's also possible to set many state attribute values using a single `Coveo.state` function call:

**Example**

Setting many state attribute values:

```javascript
Coveo.state(Coveo.$$(document).find("#search"), {
  "q" : "new query",
  "sort" : "relevancy"
});
```

## State events

Whenever a value in the state is modified, events are triggered to inform potential listeners of the change.
For example, when changing the `q` attribute as in the examples above, the following events are triggered on the root HTML element of the search interface:

* `state:change:q` to signal that the `q` attribute has changed.
* `state:change` to signal that at least one attribute in the model has changed.

Here is an example of code that monitors the value of the `q` attribute:

**Example**

Registering a state change event handler:

```javascript
var root = Coveo.$$(document).find("#search");

Coveo.$$(root).on("state:change:q", function(e, data) {
  alert("q has changed, the new value is: " + data.value);
});
```

You can find the full list of available event types in the reference documentation of the `Model` class (see [`eventTypes`](https://coveo.github.io/search-ui/classes/model.html#eventtypes)).

### Silent mode

When setting one or several state attribute values, you can pass an additional argument containing the `silent` option to prevent those changes from triggering state change events.

**Example**

Modifying the state without triggering events:

```javascript
Coveo.state(Coveo.$$(document).find("#search"), "q", "new value", {
  silent : true
});
```

## Common state attributes

This section describes the common state attributes used in a typical search interface.

### `q` (string [query expression])

The current {basic-query-expression-(`q`)} (see the [`Searchbox`](https://coveo.github.io/search-ui/components/searchbox.html) component).

**Examples**

* Setting `q` in the URL fragment identifier.

`sort=modifying%20state`

* Setting `q` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "q", "modifying state");`

### first (unsigned integer)

The 0-based position of the first [item](https://docs.coveo.com/en/210/) currently being displayed in the paginated [query](https://docs.coveo.com/en/231/) result set (see the [`Pager`](https://coveo.github.io/search-ui/components/pager.html) component).

**Default value:** `0`.

**Examples**

* Setting `first` in the URL fragment identifier.

`first=10`

* Setting `first` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "first", 10);`

### `t` (string)

The [`id`](https://coveo.github.io/search-ui/components/tab.html#options.id-1) option of the currently selected [tab](https://docs.coveo.com/en/1406/) (see the [`Tab`](https://coveo.github.io/search-ui/components/tab.html) component).

**Examples**

* Setting `t` in the URL fragment identifier.

`t=All`

* Setting `t` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "t", "All");`

### `tg` (string)

[jsui-deprecated Deprecated]


The `id` option value of the currently selected tab group.

**Examples**

* Setting `tg` in the URL fragment identifier..

`t=General`

* Setting `tg` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "t", "General");`

### sort (string)

The currently selected sort criteria (see the [`Sort`](https://coveo.github.io/search-ui/components/sort.html) component).

**Default value:** `relevancy`.

**Examples**

* Setting `sort` in the URL fragment identifier..

`sort=date%20descending`

* Setting `sort` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "sort", "date descending");`

### layout (string [enum])

The currently active result layout (see the [`ResultLayoutSelector`](https://coveo.github.io/search-ui/components/resultlayoutselector.html) component).

**Allowed values:** `card`, `list`, `table` (see [`ValidLayout`](https://coveo.github.io/search-ui/globals.html#validlayout)).

**Default value:** `list`.

**Examples**

* Setting `layout` in the URL fragment identifier..

`layout=card`

* Setting `sort` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "layout", "card");`

### f:[id] (array of string)

The list of currently selected values in the [facet](https://docs.coveo.com/en/198/) whose [`id`](https://coveo.github.io/search-ui/components/facet.html#options.id-1) option value is `[id]` (see the [`Facet`](https://coveo.github.io/search-ui/components/facet.html) component).

> **Important**
>
> The `id` option value of a facet defaults to its [`field`](https://coveo.github.io/search-ui/components/facet.html#options.field) option value.
> 
> * The following facet has `@author` as its `id` (by default).
> 
> ```html
<div class="CoveoFacet" data-field="@author"></div>
```
> 
> * The following facet has `Author` as an `id` (capital `A` and no preceding `@`).
> 
> ```html
<div class="CoveoFacet" data-id="Author" data-field="@author"></div>
```

**Examples**

* Setting `f:@author` in the URL fragment identifier.

`f:@author=[Alice%20Smith,Bob%20Jones]`

* Setting `f:@author` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "f:@author", ["Alice Smith", "Bob Jones"]);`

**Sample query string value:** `f:@author=[Alice%20Smith,Bob%20Jones]`

### f:[id]:not (array of string)

The list of currently excluded values in the facet whose `id` option value is `[id]` (see the [`Facet`](https://coveo.github.io/search-ui/components/facet.html) component).

**Examples**

* Setting `f:@author:not` in the URL fragment identifier.

`f:@author:not=[Chloe%20Brown,David%20Moore]`

* Setting `f:@author:not` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "f:@author:not", ["Chloe Brown", "David Moore"]);`

### f:[id]:operator (string [enum])

The currently selected operator of the facet whose `id` option value is `[id]` (see the [`useAnd`](https://coveo.github.io/search-ui/components/facet.html#options.useand) and [`enableTogglingOperator`](https://coveo.github.io/search-ui/components/facet.html#options.enabletogglingoperator) options of the [`Facet`](https://coveo.github.io/search-ui/components/facet.html) component).

**Allowed values:** `and`, `or`.

**Default value:** `or`.

**Examples**

* Setting `f:@category:operator` in the URL fragment identifier.

`f:@category:operator=and`

* Setting `f:@category:operator` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "f:@category:operator", "and");`

### `h&#113;` (string [query expression])

The current hidden query expression (see the [`HiddenQuery`](https://coveo.github.io/search-ui/components/hiddenquery.html) component).

**Examples**

* Setting the hidden query value in the URL fragment identifier.

`h&#113;=coveo`

* Setting the hidden query value in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "h&#113;", "coveo");`

### `hd` (string)

The current hidden query description (see the [`HiddenQuery`](https://coveo.github.io/search-ui/components/hiddenquery.html) component).

**Examples**

* Setting `hd` in the URL fragment identifier.

`hq=Add%20'Coveo'%20to%20the%20advanced%20query%20expression`

* Setting `hd` in the `state` object.

`Coveo.state(Coveo.$$(document).find("#search"), "hd", "Add 'Coveo' to the advanced query expression");`

## Registering a custom state attribute

You may want to persist the state of a custom component in the hash part of the URL.
To do so, register your custom attribute (or attributes) in the state object after the Coveo components have been initialized (see [Events - Initialization events](https://docs.coveo.com/en/417#initialization-events)).

**Example**

You create a custom component which allows users to choose a predefined theme when displaying your search page.

You want to persist the currently selected theme in the hash part of the URL, so you register a `theme` state attribute and set its default value to `standard`:

```javascript
// Suppose that this is the root of your search interface...
var root = Coveo.$$(document).find("#search");

Coveo.$$(root).on("afterComponentsInitialization", function(e) {
  Coveo.state(root).registerNewAttribute("theme", "standard");
});
```

When a user interacts with your component to select a theme, your component updates the `theme` state attribute value accordingly:

```javascript
// When a user selects the "zen" theme from the custom component...

Coveo.state(root, "theme", "zen")
```

You also bind an event handler on the `state:change:theme` event to update your component when a user changes the `colorTheme` state attribute value directly in the hash part of the URL:

```javascript
Coveo.$$(root).on("state:change:theme", function(e, data)

  // Update your custom component...
})
```