---
title: "Config reference"
description: "Reference for the page-level config settings for web components, and the props you can pass to the React SDK’s MetabaseProvider."
url: "https://www.metabase.com/docs/latest/embedding/config-reference"
version: "65"
---

> For the complete documentation index, see [llms.txt](https://www.metabase.com/docs/llms.txt).

# Config reference

Reference material for the config that every modular embed on a page shares: the `defineMetabaseConfig()` settings for web components, and the `MetabaseProvider` props for the React SDK.

For how to set all this up, check out [Configure your embeds](https://www.metabase.com/docs/latest/embedding/config.md).

## Web component `defineMetabaseConfig()` settings

Every web component on the page uses these settings. For the SDK, see [`MetabaseProvider` props](#react-sdk-metabaseprovider-props).

| Property                                                               | Type                                                                                                                            | Description                                                                                                                                                                                                                                                                                                                                 |
| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="allowedcustomvisualizations"></a> `allowedCustomVisualizations` | `` `custom:${string}` ``[]                                                                                                      | The custom visualizations that components on the page can load, each prefixed with `custom:`, like `["custom:Calendar Heatmap"]`. Not available in guest embeds. See [Custom visualizations in embeds](https://www.metabase.com/docs/latest/embedding/custom-visualizations.md).<br>---<br>Optional                                            |
| <a id="apikey"></a> `apiKey`                                           | `string`                                                                                                                        | Development only. An API key from your Metabase, which embeds use to render on localhost. See [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config.md#preview-embeds-during-development).<br>---<br>Optional                                                                                              |
| <a id="fetchrequesttoken"></a> `fetchRequestToken`                     | () => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<\{ `jwt`: `string`; \}\> | SSO embeds with JWT only. A function that fetches the JWT for embeds. See [Customizing JWT authentication](https://www.metabase.com/docs/latest/embedding/authentication.md#customizing-jwt-authentication).<br>---<br>Optional                                                                                                                |
| <a id="guestembedprovideruri"></a> `guestEmbedProviderUri`             | `string`                                                                                                                        | Guest embeds only. Your app's endpoint that signs guest tokens. The embed calls this endpoint for a token on load, and again when the current token expires. The endpoint should return `{ jwt: string }`. See [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config.md#configure-a-guest-embed).<br>---<br>Optional |
| <a id="instanceurl"></a> `instanceUrl`                                 | `string`                                                                                                                        | The URL of your Metabase, like `https://youlooknicetoday.metabaseapp.com`.                                                                                                                                                                                                                                                                  |
| <a id="isguest"></a> `isGuest`                                         | `boolean`                                                                                                                       | Whether the components authenticate as guest embeds, with a signed JWT instead of a Metabase session. See [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config.md#configure-a-guest-embed).<br>---<br>Optional<br>Default: `false`                                                                                  |
| <a id="jwtprovideruri"></a> `jwtProviderUri`                           | `string`                                                                                                                        | SSO embeds with JWT only. The URL of your JWT provider. When set, embeds use JWT and skip the request that discovers the SSO method.<br>---<br>Optional                                                                                                                                                                                     |
| <a id="locale"></a> `locale`                                           | `string`                                                                                                                        | The display language for every embed, as an ISO language code like `en` or `de`. Defaults to your Metabase instance's locale. See [Set the language](https://www.metabase.com/docs/latest/embedding/config.md#set-the-language).<br>---<br>Optional                                                                                            |
| <a id="pluginsconfig"></a> `pluginsConfig`                             | \{ `handleLink`: (`url`: `string`) => \{ `handled`: `boolean`; \}; \}                                                           | Plugins that customize component behavior. Web components support `handleLink`, for customizing what happens when people click a link. See [Web component plugins](https://www.metabase.com/docs/latest/embedding/config.md#web-component-plugins).<br>---<br>Optional                                                                         |
| `pluginsConfig.handleLink`                                             | (`url`: `string`) => \{ `handled`: `boolean`; \}                                                                                | Called when people click a link in an embed. Return `{ handled: true }` to handle the link yourself, or `{ handled: false }` to open the link in a new tab.<br>---<br>Optional                                                                                                                                                              |
| <a id="preferredauthmethod"></a> `preferredAuthMethod`                 | `string`                                                                                                                        | SSO embeds only. Which SSO method to use. If you've set up both SAML and JWT, embeds default to SAML. See [Authentication](https://www.metabase.com/docs/latest/embedding/authentication.md#if-both-saml-and-jwt-are-enabled-modular-embedding-will-default-to-saml).<br>---<br>Optional<br>Possible values: `"jwt"`, `"saml"`                 |
| <a id="theme"></a> `theme`                                             | `object`                                                                                                                        | Colors, fonts, and per-component appearance overrides. See [Appearance](https://www.metabase.com/docs/latest/embedding/appearance.md).<br>---<br>Optional                                                                                                                                                                                      |
| <a id="useexistingusersession"></a> `useExistingUserSession`           | `boolean`                                                                                                                       | Development only. Whether to render embeds with your own Metabase session. Only supported in Google Chrome. See [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config.md#preview-embeds-during-development).<br>---<br>Optional<br>Default: `false`                                                        |

## React SDK `MetabaseProvider` props

> Modular embedding SDK is only available on [Pro](https://store.metabase.com/checkout/embedding) and [Enterprise](https://www.metabase.com/product/enterprise) plans (both self-hosted and on Metabase Cloud).

`MetabaseProvider` provides the [configuration](https://www.metabase.com/docs/latest/embedding/config.md#configure-the-react-sdk) that every Metabase component inside it uses.

- [Component](https://www.metabase.com/docs/latest/embedding/sdk/api/MetabaseProvider.md)
- [Props](https://www.metabase.com/docs/latest/embedding/sdk/api/MetabaseProviderProps.md)

| Property                                                                | Type                                                                                                                                                                         | Description                                                                                                                                                                                                                                                                                            |
| :---------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="allowconsolelog"></a> `allowConsoleLog?`                         | `boolean`                                                                                                                                                                    | Whether to allow logging to the DevTools console. Defaults to true.                                                                                                                                                                                                                                    |
| <a id="allowedcustomvisualizations"></a> `allowedCustomVisualizations?` | `` `custom:${string}` ``[]                                                                                                                                                   | Opt-in support for EE custom visualization plugins inside the SDK. Pass an allowlist of `custom:`-prefixed plugin identifiers (manifest `name`), e.g. `["custom:Thumbs", "custom:Calendar"]`. Only listed plugins are loaded. Omit or pass `[]` to disable. Requires the `custom-viz` premium feature. |
| <a id="authconfig"></a> `authConfig`                                    | [`MetabaseAuthConfig`](https://www.metabase.com/docs/latest/embedding/api/MetabaseAuthConfig)                                                                                                                          | Defines how to authenticate with Metabase.                                                                                                                                                                                                                                                             |
| <a id="children"></a> `children`                                        | [`ReactNode`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L478)                                  | The children of the MetabaseProvider component.                                                                                                                                                                                                                                                        |
| <a id="classname"></a> ~~`className?`~~                                 | `string`                                                                                                                                                                     | A custom class name to be added to the root element. **Deprecated** This prop is not used anymore.                                                                                                                                                                                                     |
| <a id="errorcomponent"></a> `errorComponent?`                           | [`SdkErrorComponent`](https://www.metabase.com/docs/latest/embedding/api/SdkErrorComponent)                                                                                                                            | A custom error component to display when the SDK encounters an error.                                                                                                                                                                                                                                  |
| <a id="eventhandlers"></a> `eventHandlers?`                             | [`SdkEventHandlersConfig`](https://www.metabase.com/docs/latest/embedding/api/SdkEventHandlersConfig)                                                                                                                  | See [Handle embed events](https://www.metabase.com/docs/latest/embedding/config.md#handle-embed-events-react-sdk-only).                                                                                                                                                                                   |
| <a id="loadercomponent"></a> `loaderComponent?`                         | [`ComponentType`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L104)\<\{ `label?`: `string`; \}\> | A custom loader component to display while the SDK is loading. The component receives an optional `label` prop that can be used to display a loading message.                                                                                                                                          |
| <a id="locale"></a> `locale?`                                           | `string`                                                                                                                                                                     | Defines the display language. Accepts an ISO language code such as `en` or `de`. Defaults to the instance locale.                                                                                                                                                                                      |
| <a id="pluginsconfig"></a> `pluginsConfig?`                             | [`MetabaseGlobalPluginsConfig`](https://www.metabase.com/docs/latest/embedding/api/MetabaseGlobalPluginsConfig)                                                                                                        | See [Plugins](https://www.metabase.com/docs/latest/embedding/sdk/plugins.md).                                                                                                                                                                                                                             |
| <a id="theme"></a> `theme?`                                             | [`MetabaseEmbeddingTheme`](https://www.metabase.com/docs/latest/embedding/api/MetabaseEmbeddingTheme)                                                                                                                  | See [Appearance](https://www.metabase.com/docs/latest/embedding/sdk/appearance).                                                                                                                                                                                                                       |
| <a id="uselegacymonolithicbundle"></a> `useLegacyMonolithicBundle?`     | `boolean`                                                                                                                                                                    | Whether to load the full SDK bundle directly as a single file (legacy behavior), instead of the optimized bootstrap that loads chunks in parallel and starts authentication early. Defaults to false (uses the optimized bootstrap loader).                                                            |

## React SDK `eventHandlers`

> Modular embedding SDK is only available on [Pro](https://store.metabase.com/checkout/embedding) and [Enterprise](https://www.metabase.com/product/enterprise) plans (both self-hosted and on Metabase Cloud).

The `eventHandlers` prop on `MetabaseProvider` maps event types to handler functions. See [Handle embed events](https://www.metabase.com/docs/latest/embedding/config.md#handle-embed-events-react-sdk-only).

- [Type](https://www.metabase.com/docs/latest/embedding/sdk/api/SdkEventHandlersConfig.md)

| Property                                                                | Type                                                      | Description                                                                                                                                                                         |
| :---------------------------------------------------------------------- | :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="ondashboardload"></a> `onDashboardLoad?`                         | [`SdkDashboardLoadEvent`](https://www.metabase.com/docs/latest/embedding/api/SdkDashboardLoadEvent) | Triggers when a dashboard loads with all visible cards and their content                                                                                                            |
| <a id="ondashboardloadwithoutcards"></a> `onDashboardLoadWithoutCards?` | [`SdkDashboardLoadEvent`](https://www.metabase.com/docs/latest/embedding/api/SdkDashboardLoadEvent) | Triggers after a dashboard loads, but without its cards (at this stage only the dashboard title, tabs, and cards grid are rendered, but the contents of the cards have yet to load. |

## Further reading

- [Configure your embeds](https://www.metabase.com/docs/latest/embedding/config.md)
- [Appearance](https://www.metabase.com/docs/latest/embedding/appearance.md)
- [Authentication](https://www.metabase.com/docs/latest/embedding/authentication.md)
- [Guest embedding](https://www.metabase.com/docs/latest/embedding/guest-embedding.md)
- [Modular embedding components](https://www.metabase.com/docs/latest/embedding/components.md)
