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

# useDashboardLoader

> Load, bootstrap, and tear down a plugin-enhanced dashboard from React, returning status, result, and error state.

API reference: [useDashboardLoader()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.usedashboardloader/index.md) (function), [DashboardStub()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.dashboardstub/index.md) (function), [DashboardLoader](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.dashboardloader/index.md) (class)

`useDashboardLoader` loads a dashboard together with its plugins, runs the plugins' registration, and returns a `DashboardComponent` ready to render. It's the main hook for embedding a plugin-enhanced dashboard in React. For the webpack setup that plugins linked to a dashboard need, and for combining them with your own plugins, see [Embed a dashboard with plugins](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/embed-dashboard-with-plugins/index.md).

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

```tsx
import { useDashboardLoader } from "@gooddata/sdk-ui-loaders";

function MyDashboard({ dashboardRef }) {
    const { status, result, error } = useDashboardLoader({
        dashboard: dashboardRef,
        // Use "adaptive" with adaptiveLoadOptions to load plugins linked to the dashboard on the backend.
        loadingMode: "staticOnly",
        // See IDashboardLoadOptions for full configuration
    });

    if (status === "loading" || status === "pending") {
        return <div>Loading dashboard...</div>;
    }

    if (status === "error") {
        return <div>Error: {error.message}</div>;
    }

    // result contains the loaded dashboard with plugins applied
    const { DashboardComponent, props } = result;
    return <DashboardComponent {...props} />;
}
```

### [Render with DashboardStub](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-dashboard-loader/#render-with-dashboardstub)

[`DashboardStub`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.dashboardstub/index.md) wraps `useDashboardLoader` and renders the loading, error, and
success states for you. Use it instead of the hook when you don't need custom
branching on `status` — pass it the same [`IDashboardLoadOptions`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardloadoptions/index.md), plus an
optional [`ErrorComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.errorcomponent/index.md) and [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.loadingcomponent/index.md):

```tsx
import { DashboardStub } from "@gooddata/sdk-ui-loaders";

function MyDashboard({ dashboardRef }) {
    return (
        <DashboardStub
            dashboard={dashboardRef}
            loadingMode="staticOnly"
            ErrorComponent={({ message }) => <div>Error: {message}</div>}
            LoadingComponent={() => <div>Loading dashboard...</div>}
        />
    );
}
```

Reach for the hook directly instead when you need to render something other
than the dashboard while it loads (for example, a skeleton laid out around
other page content) or when you need the `result`/`error` values for
something besides rendering.

### [Add layout content from a plugin passed through `extraPlugins`](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-dashboard-loader/#add-layout-content-from-a-plugin-passed-through-extraplugins)

A plugin registered through `extraPlugins` can insert widgets into the
loaded dashboard from its `register` method, using the layout customization
API (`customize.layout().customizeFluidLayout()`):

```tsx
import {
    DashboardPluginV1,
    newCustomWidget,
    newDashboardItem,
    type DashboardContext,
    type IDashboardCustomizer,
} from "@gooddata/sdk-ui-dashboard";
import { useDashboardLoader } from "@gooddata/sdk-ui-loaders";

class AddSectionPlugin extends DashboardPluginV1 {
    public readonly author = "acme";
    public readonly displayName = "Add section plugin";
    public readonly version = "1.0";
    public readonly minEngineVersion = "bundled";

    public register(_ctx: DashboardContext, customize: IDashboardCustomizer): void {
        customize.layout().customizeFluidLayout((_layout, layoutCustomizer) => {
            layoutCustomizer.addSectionToPath(
                { sectionIndex: 0 },
                {
                    type: "IDashboardLayoutSection",
                    items: [newDashboardItem(newCustomWidget("myWidget", "myCustomWidget"), 12)],
                },
            );
        });
    }
}

const { status, result } = useDashboardLoader({
    dashboard: dashboardRef,
    loadingMode: "staticOnly",
    extraPlugins: { factory: () => new AddSectionPlugin() },
});
```

### [Set initial filters two ways](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-dashboard-loader/#set-initial-filters-two-ways)

To change the filters a dashboard opens with, either pass an already loaded
[`IDashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.idashboard/index.md) with a modified `filterContext` as the `dashboard` option, or pass
`overrideDefaultFilters` through `config` at load time:

```tsx
// `dashboard` is an IDashboard you loaded, for example with
// backend.workspace(workspace).dashboards().getDashboard(dashboardRef)
useDashboardLoader({
    dashboard: { ...dashboard, filterContext: withMyFilter(dashboard.filterContext) },
    loadingMode: "staticOnly",
});
```

```tsx
useDashboardLoader({
    dashboard: dashboardRef,
    loadingMode: "staticOnly",
    config: { overrideDefaultFilters: myFilters },
});
```

Passing a modified [`IDashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.idashboard/index.md) changes the stored filter context the dashboard
starts from; passing `config.overrideDefaultFilters` keeps the stored filter
context and applies your filters on top of it on every load, including reloads
triggered by a change in the hook's dependencies.

### [Override chrome components on the loaded dashboard](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-dashboard-loader/#override-chrome-components-on-the-loaded-dashboard)

The `DashboardComponent` the loader returns accepts the same customization
props as `<Dashboard />`. Spread `result.props` and override the ones you
need, such as `FilterBarComponent` or `TopBarComponent`:

```tsx
const { DashboardComponent, props } = result;
return <DashboardComponent {...props} FilterBarComponent={CustomFilterBar} TopBarComponent={CustomTopBar} />;
```

See [Dashboard component](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard/index.md) for the full
list of overridable components.

### [Dispatch dashboard commands from a plugin-provided component](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-dashboard-loader/#dispatch-dashboard-commands-from-a-plugin-provided-component)

A component a plugin registers (for example, a custom filter provider) runs
inside the loaded dashboard's store context, so it can dispatch commands the
same way any other dashboard-rendered component does. See
[useDispatchDashboardCommand](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard/index.md#commands).

### [Load a dashboard outside React](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-dashboard-loader/#load-a-dashboard-outside-react)

The [`DashboardLoader`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.dashboardloader/index.md) builder class does the same loading without React. Use it
when you need to load a dashboard outside a component, or need more control
over the loading sequence than the hook's options give you:

```tsx
import { DashboardLoader } from "@gooddata/sdk-ui-loaders";

const { DashboardComponent, props } = await DashboardLoader.staticOnly()
    .withBaseProps({ workspace, dashboard: dashboardRef })
    .withEmbeddedPlugins({ factory: () => new MyPlugin() })
    .load();
```

Start the chain with `DashboardLoader.staticOnly()` or
`DashboardLoader.adaptive(adaptiveLoadOptions)`, configure it with
`withBaseProps`, `withEmbeddedPlugins`, `withFilterContext`,
`fromClientWorkspace`, `fromWorkspace`, `forDashboard`, or `onBackend`, then
call `load()` to resolve the same [`DashboardLoadResult`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.dashboardloadresult/index.md) the hook's `result`
carries.

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `options` | [`IDashboardLoadOptions`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardloadoptions/index.md) | Load options including the dashboard reference, the loading mode, and the plugin configuration. |

The options that decide how plugins load:

- `loadingMode`: `"adaptive"` (default) loads and bootstraps the plugins linked to the dashboard on the backend and requires `adaptiveLoadOptions`, the Module Federation integration of your bundler; the hook throws an invariant error without them. `"staticOnly"` skips dynamic plugin loading and uses only the plugins in `extraPlugins`, for environments where running remote plugin code isn't acceptable or that don't use Module Federation.
- `extraPlugins`: plugins bundled with your application.
- `allowUnfinishedFeatures`: `"alwaysPrevent"` (default), `"staticOnly"`, or `"alwaysAllow"`; decides whether the dashboard exposes features still in preview.

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

[`DashboardLoadStatus`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.dashboardloadstatus/index.md), a `UseCancelablePromiseState<DashboardLoadResult, any>` with:

- `status`: `"pending" | "loading" | "success" | "error"`
- `result`: [`DashboardLoadResult`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.dashboardloadresult/index.md) (on success), which holds the loaded `DashboardComponent` and its `props`
- `error`: Error details (on error)

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

- When `dashboard`, `backend`, `workspace`, `filterContextRef`, `config`, `permissions`, `clientWorkspace`, `extraPlugins`, or `loadingMode` change, the hook loads the dashboard again and cancels the load in flight.
- When the component that uses the hook unmounts, the hook calls `onPluginUnload` on each loaded plugin.
- The hook logs the engine version and the plugin list with `console.debug`, which helps when you diagnose plugin registration.
- Pass `backend` and `workspace` as options, or render the hook inside [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md) and [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md).

## [Props](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-dashboard-loader/#props)

| Prop | Type | Required | Description | Inherited from |
|------|------|----------|-------------|----------------|
| [`adaptiveLoadOptions`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardloadoptions/index.md#idashboardloadoptionsadaptiveloadoptions) | [`AdaptiveLoadOptions`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.adaptiveloadoptions/index.md) | No | Specify configuration related adaptive loading. | — |
| [`adhocItems`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardloadoptions/index.md#idashboardloadoptionsadhocitems) | [`DashboardItem`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboarditem/index.md)`[]` | No | List of ad-hoc items to render in the dashboard. These items are not part of the dashboard definition and are not persisted, it will be rendered into empty layout. | — |
| [`allowUnfinishedFeatures`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardloadoptions/index.md#idashboardloadoptionsallowunfinishedfeatures) | `"staticOnly" \| "alwaysAllow" \| "alwaysPrevent"` | No | Specify when will be in progress features allowed | — |
| [`clientWorkspace`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardloadoptions/index.md#idashboardloadoptionsclientworkspace) | [`IClientWorkspaceIdentifiers`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iclientworkspaceidentifiers/index.md) | No | Specify client workspace identifiers to use in order to identify exact workspace to load the dashboard from. | — |
| [`extraPlugins`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardloadoptions/index.md#idashboardloadoptionsextraplugins) | [`IEmbeddedPlugin`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.iembeddedplugin/index.md) `\|` [`IEmbeddedPlugin`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.iembeddedplugin/index.md)`[]` | No | Specify extra plugins to use during the bootstrap of the dashboard. | — |
| [`loadingMode`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardloadoptions/index.md#idashboardloadoptionsloadingmode) | [`DashboardLoadingMode`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.dashboardloadingmode/index.md) | No | Loading mode to use. | — |
| [`dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardbasepropsforloader/index.md#idashboardbasepropsforloaderdashboard) | `string \|` [`ObjRef`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.objref/index.md) `\| undefined \|` [`IDashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.idashboard/index.md) | Yes | Specify reference to an existing dashboard that should be loaded or undefined to initialize an empty one. | [`IDashboardBasePropsForLoader`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-loaders/sdk-ui-loaders.idashboardbasepropsforloader/index.md) |
| [`backend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md#idashboardbasepropsbackend) | [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) | No | Analytical backend from which the dashboard obtains data to render. | [`IDashboardBaseProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md) |
| [`config`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md#idashboardbasepropsconfig) | [`DashboardConfig`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboardconfig/index.md) | No | Configuration that can be used to modify dashboard features, capabilities and behavior. | [`IDashboardBaseProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md) |
| [`filterContextRef`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md#idashboardbasepropsfiltercontextref) | [`ObjRef`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.objref/index.md) | No | Specify reference to a filter context that should be used instead of the default, built-in filter context. | [`IDashboardBaseProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md) |
| [`initialTabId`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md#idashboardbasepropsinitialtabid) | `string` | No | _(Alpha)_ Explicitly specify which tab should be opened first when the dashboard is rendered. | [`IDashboardBaseProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md) |
| [`keyboardNavigation`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md#idashboardbasepropskeyboardnavigation) | `KeyboardNavigationConfig` | No | Specify tab index and addressable id for the dashboard components used by keyboard navigation | [`IDashboardBaseProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md) |
| [`permissions`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md#idashboardbasepropspermissions) | [`IWorkspacePermissions`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iworkspacepermissions/index.md) | No | Specify permissions to use when determining availability of the different features of the dashboard component. | [`IDashboardBaseProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md) |
| [`workspace`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md#idashboardbasepropsworkspace) | `string` | No | Identifier of analytical workspace, from which the dashboard obtains data to render. | [`IDashboardBaseProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.idashboardbaseprops/index.md) |