> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# useDashboardSelector

> Read Dashboard component state with useDashboardSelector and the select* selectors, from components, event handlers, and outside code.

API reference: [useDashboardSelector](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.usedashboardselector/index.md) (variable), [DashboardSelector](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboardselector/index.md) (type-alias), [DashboardSelectorEvaluator](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboardselectorevaluator/index.md) (type-alias), [SingleDashboardStoreAccessor](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.singledashboardstoreaccessor/index.md) (class)

`useDashboardSelector` reads one value from the state of the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component. Pass it a selector; it returns the selector's result and re-renders your component when that result changes.

Selectors are memoized: for the same state they return the same reference, so their results are safe to use as dependencies of `useMemo` and `useEffect`.

The component that calls the hook must render inside the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component. That covers custom widgets, components registered through the customization API, and plugin decorators. For code that runs outside the component, see [Read state outside the Dashboard component](#read-state-outside-the-dashboard-component).

## [Basic usage](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-selector/#basic-usage)

The most common use is to hand rendering back to the built-in component in edit mode:

```tsx
import {
    DefaultDashboardInsight,
    selectIsInEditMode,
    useDashboardSelector,
    type IDashboardInsightProps,
} from "@gooddata/sdk-ui-dashboard";

export function CustomInsight(props: IDashboardInsightProps) {
    const isInEditMode = useDashboardSelector(selectIsInEditMode);

    return isInEditMode ? (
        <DefaultDashboardInsight {...props} />
    ) : (
        <div>Custom rendering of {props.widget.title}</div>
    );
}
```

Register the component with `customize.insightWidgets().withCustomProvider(...)` in your plugin. See [Dashboard plugins API](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard-plugins-api/index.md).

### [Selectors with parameters](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-selector/#selectors-with-parameters)

Some selectors are factories. Call the factory with the parameter and pass the result to the hook. Factories are memoized per argument, so calling one during render doesn't create a new selector each time.

```tsx
import { attributeDisplayFormRef } from "@gooddata/sdk-model";
import { selectFilterContextAttributeFilterItemByDisplayForm, useDashboardSelector } from "@gooddata/sdk-ui-dashboard";
import * as Md from "./catalog.js";

const regionDisplayForm = attributeDisplayFormRef(Md.Region.Default);

export function RegionFilterSummary() {
    const regionFilter = useDashboardSelector(
        selectFilterContextAttributeFilterItemByDisplayForm(regionDisplayForm),
    );

    return <span>{regionFilter ? "Region filter is set" : "No region filter"}</span>;
}
```

### [Turn a customization on per dashboard](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-selector/#turn-a-customization-on-per-dashboard)

Dashboard tags let a plugin decide, per dashboard, whether to apply itself. Dashboard authors add or remove the tag in GoodData Cloud, so you don't need to redeploy the plugin. Use the pattern from [Basic usage](#basic-usage), with a tag check in place of the edit-mode check:

```tsx
const isEnabled = useDashboardSelector(selectDashboardTags).includes("custom-rendering");
```

To decide by the visualization's tag instead of the dashboard's, use `customize.insightWidgets().withTag(tag, component)`.

## [Parameters](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-selector/#parameters)

| Parameter | Type | Description |
|-----------|------|-------------|
| `selector` | `(state: DashboardState) => TResult` | The selector to evaluate, usually one of the `select*` functions exported by `@gooddata/sdk-ui-dashboard`. |

### [Commonly used selectors](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-selector/#commonly-used-selectors)

| Selector | Returns | Use it to |
|----------|---------|-----------|
| [`selectIsInEditMode`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectisineditmode/index.md) | `boolean` | Fall back to the default component in edit mode |
| [`selectIsExport`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectisexport/index.md) | `boolean` | Simplify rendering when the dashboard is exported to PDF |
| [`selectDashboardId`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectdashboardid/index.md) | `string \| undefined` | Key persisted UI state or build links to the dashboard |
| [`selectDashboardRef`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectdashboardref/index.md) | `ObjRef \| undefined` | Pass the dashboard to [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) calls |
| [`selectDashboardTitle`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectdashboardtitle/index.md) | `string` | Show the title in a custom top bar |
| [`selectDashboardTags`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectdashboardtags/index.md) | `string[]` | Turn a customization on for selected dashboards |
| [`selectFilterContextFilters`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectfiltercontextfilters/index.md) | [`FilterContextItem[]`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.filtercontextitem/index.md) | Read every dashboard-level filter |
| [`selectFilterContextDateFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectfiltercontextdatefilter/index.md) | `IDashboardDateFilter \| undefined` | Read the dashboard date filter |
| [`selectFilterContextAttributeFilterItemByDisplayForm(ref)`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectfiltercontextattributefilteritembydisplayform/index.md) | `DashboardAttributeFilterItem \| undefined` | Read one attribute filter by its display form |
| [`selectLayout`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectlayout/index.md) | [`IDashboardLayout`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.idashboardlayout/index.md) | Walk sections, items, and widgets |
| [`selectInsights`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectinsights/index.md) | [`IInsight[]`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iinsight/index.md) | List the visualizations placed on the dashboard |
| [`selectSettings`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectsettings/index.md) | [`ISettings`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.isettings/index.md) | Read workspace and user settings |
| [`selectLocale`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.selectlocale/index.md) | [`ILocale`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.ilocale/index.md) | Format text for the dashboard locale |

The full list is in the [API reference](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/index.md).

## [Return value](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-selector/#return-value)

The selector's result for the current dashboard state. The component re-renders when the result changes.

## [Notes](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-selector/#notes)

- Selectors marked `@alpha` or `@internal` on their reference page can change or disappear in a minor release. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
- To get the effective [`IFilter[]`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.ifilter/index.md) for a widget, use `useWidgetFilters` instead of merging `selectFilterContextFilters` with the visualization's own filters yourself. The hook applies the widget's ignored filters and date dataset for you.
- Selectors only read. To change the dashboard, dispatch a command with `useDispatchDashboardCommand`; see [Dashboard component](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard/index.md#commands).
- `useDashboardSelector` throws when rendered outside the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component tree. Code outside the tree reads state through [`SingleDashboardStoreAccessor`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.singledashboardstoreaccessor/index.md); see [Read state outside the Dashboard component](#read-state-outside-the-dashboard-component).
### [Read state in an event handler](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-selector/#read-state-in-an-event-handler)

Event handlers receive a `stateSelect` function that accepts the same selectors as the hook. See [Handle dashboard events](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard-events/index.md#read-state-and-dispatch-from-a-handler).

### [Read state outside the Dashboard component](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-selector/#read-state-outside-the-dashboard-component)

Pass the change handler of [`SingleDashboardStoreAccessor`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.singledashboardstoreaccessor/index.md) to the `onStateChange` prop. The accessor then exposes a [`DashboardSelectorEvaluator`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboardselectorevaluator/index.md) you can call from anywhere in your application.

```tsx
import { Dashboard, selectDashboardTitle, SingleDashboardStoreAccessor } from "@gooddata/sdk-ui-dashboard";

export function DashboardPage({ dashboard }: { dashboard: string }) {
    return <Dashboard dashboard={dashboard} onStateChange={SingleDashboardStoreAccessor.getOnChangeHandler()} />;
}

export function currentDashboardTitle(): string | undefined {
    if (!SingleDashboardStoreAccessor.isAccessorInitialized()) {
        return undefined;
    }

    return SingleDashboardStoreAccessor.getDashboardSelect()(selectDashboardTitle);
}
```

Call `getDashboardSelect()` each time you need a value. The component replaces the evaluator after every state change, so a stored one keeps returning stale state.

To follow more than one dashboard, use [`DashboardStoreAccessorRepository`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboardstoreaccessorrepository/index.md). See [Access the state of the Dashboard component from outside the component](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard/index.md#access-the-state-of-the-dashboard-component-from-outside-the-component).