> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: observeState()

## Article: observeState()

## Article Link: https://dev.wix.com/docs/sdk/host-modules/dashboard/observe-state.md

## Article Content:

# observeState()
Allows you to receive the contextual state and environmental information of the dashboard.
The callback function provided to `observeState` receives the state data. The function is triggered when the dashboard page or component initializes and whenever the state data is updated.

## Common use cases for this method
1. A dashboard page in an app receiving environment data from the host, such as the user's locale.
2. A widget rendered within the dashboard, receiving contextual data from the page that's hosting it.
3. A modal opened from a dashboard page or from a widget, receiving data from the page that opened it.
4. A dashboard component adjusting its behavior when rendered inside an iframe.

## Method Declaration

```ts
observeState<P>(observer: Observer<P>): void
```

## Method Parameters

| Name       | Type       | Description                                    |
|:-----------|:-----------|------------------------------------------------|
| `observer` | `Observer` | Callback function for receiving state data that takes two parameters:<br/>`componentParams`: The data that is sent to your component by your host, who is responsible for rendering it.<br/>`environmentState`: General information about the user's present environment. |

### Observer
```ts
(componentParams: P | PageParams, environmentState: EnvironmentState) => void
```

| Name        | Type               | Description                                    |
|:------------|:-------------------|------------------------------------------------|
| `componentParams` | `P \| PageParams`                | A generic type parameter that contains the data sent to your component by your host (which is responsible for rendering your component). In the case of a dashboard page, which is rendered by the platform itself, `componentParams` is of type [`PageParams`](#pageparams). |
| `environmentState`  | `EnvironmentState` | Information about the state of the dashboard's environment.          |


#### PageParams
```ts
{
  location: PageLocation;
  // displayMode: "main" | "overlay";
}
```

| Name           | Type           | Description                                          |
|:---------------|:---------------|------------------------------------------------------|
| `location`     | `PageLocation` | Information about the location of the rendered page. |
<!-- | `displayMode ` | `"main" \| "overlay"` | Whether the page is being rendered as a main page or an overlay page. | -->


#### EnvironmentState
```ts
{
  locale: string;
  embedded: boolean;
  /** @deprecated */
  pageLocation: PageLocation;
}
```

| Name           | Type           | Description                                            |
|:---------------|:---------------|--------------------------------------------------------|
| `locale`       | `string`       | User's locale in [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) format.                    |
| `embedded`     | `boolean`      | Whether the dashboard is being rendered inside an iframe.  |
| `pageLocation` | `PageLocation` | Deprecated. Information about the currently rendered page location. |


#### PageLocation
```ts
{
  pageId: string;
  pathname: string;
  search?: string;
  hash?: string;
}
```

| Name       | Type     | Description                                                   |
|:-----------|:---------|-------------------------------------------------------------------|
| `pageId`   | `string` | ID of the current page.             |
| `pathname` | `string` | Any parts of the current URL path appended to the page's full URL path. [Learn more](#about-pathname). |
| `search`   | `string` | Optional. The current URL's query string.          |
| `hash`     | `string` | Optional. The current URL's fragment identifier.                   |

##### About `pathname`
The value of `pathname` is any part of the URL path that comes after the route to the current dashboard page.

For third-party app dashboard pages, this is anything appended to the URL after the **Relative route** value that you set when [creating the dashboard page](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/dashboard-extensions/dashboard-pages/add-dashboard-page-extensions-with-the-cli.md) extension in the Wix Developers Center.

## Examples
> **Note:** To use this method in [self-hosted apps](https://dev.wix.com/docs/sdk/articles/get-started/about-self-hosted-apps.md), you need to create a [client](https://dev.wix.com/docs/sdk/articles/set-up-a-client/about-the-wix-client.md). See the [setup](https://dev.wix.com/docs/sdk/host-modules/dashboard/introduction.md) guide for more details.

### Receive state passed by your host

```javascript
dashboard.observeState((componentParams, environmentState) => {
  // This value is logged on initialization and whenever either `componentParams` or `environmentState` changes. 
  console.log(componentParams.customPageParameter);
});
```

### Receive user's locale

```javascript
dashboard.observeState((componentParams, environmentState) => {
  // This value is logged on initialization and whenever either `componentParams` or `environmentState` changes. 
  console.log(environmentState.locale);  
});
```

<!-- ### Handle page display mode

```javascript
dashboard.observeState((pageParams, environmentState) => {
  // This value is logged on initialization and whenever either `componentParams` or `environmentState` changes. 
  const {displayMode} = pageParams
  if (displayMode === "overlay") {
    console.log("Rendering as an overlay page.")
  } else {
    console.log("Rendering as the main page.)
  }
});
``` -->

### Handle embedded context

```javascript
dashboard.observeState((componentParams, environmentState) => {
  const { embedded } = environmentState;
  
  if (embedded) {
    console.log("Dashboard is running in an embedded iframe context");
    // Adjust behavior for iframe environment
    // - Disable features that don't work in iframes
    // - Adjust UI layout for constrained space
  } else {
    console.log("Dashboard is running in standalone mode");
    // Normal dashboard behavior
  }
});
```

### Handle internal page routes

```javascript
dashboard.observeState((pageParams, environmentState) => {
  // This value is logged on initialization and whenever either of the `componentParams` or `environmentState` objects change.
  const {pathname, search} = pageParams.location
  if (pathname.startsWith("/list")) {
      const queryParams = new URLSearchParams(search)
      const sortBy = queryParams.get("sortyBy")
      console.log("Show items list sorted by", sortBy)
  } else if (pathname.startsWith("/item")) {
      const {itemId} = pathname.match("\/item\/(?<itemId>.*)").groups
      console.log("Show item with id", itemId)
  }
  console.log("Unknown route")
});
```