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.
Web component defineMetabaseConfig() settings
Every web component on the page uses these settings. For the SDK, see MetabaseProvider props.
| Property | Type | Description |
|---|---|---|
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.— Optional |
apiKey |
string |
Development only. An API key from your Metabase, which embeds use to render on localhost. See Preview embeds during development. — Optional |
fetchRequestToken |
() => Promise<{ jwt: string; }> |
SSO embeds with JWT only. A function that fetches the JWT for embeds. See Customizing JWT authentication. — Optional |
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.— Optional |
instanceUrl |
string |
The URL of your Metabase, like https://youlooknicetoday.metabaseapp.com. |
isGuest |
boolean |
Whether the components authenticate as guest embeds, with a signed JWT instead of a Metabase session. See Configure a guest embed. — Optional Default: false |
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. — Optional |
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.— Optional |
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.— 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.— Optional |
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. — Optional Possible values: "jwt", "saml" |
theme |
object |
Colors, fonts, and per-component appearance overrides. See Appearance. — Optional |
useExistingUserSession |
boolean |
Development only. Whether to render embeds with your own Metabase session. Only supported in Google Chrome. See Preview embeds during development. — Optional Default: false |
React SDK MetabaseProvider props
Modular embedding SDK is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).
MetabaseProvider provides the configuration that every Metabase component inside it uses.
| Property | Type | Description |
|---|---|---|
allowConsoleLog? |
boolean |
Whether to allow logging to the DevTools console. Defaults to true. |
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. |
authConfig |
MetabaseAuthConfig |
Defines how to authenticate with Metabase. |
children |
ReactNode |
The children of the MetabaseProvider component. |
className? |
string |
A custom class name to be added to the root element. Deprecated This prop is not used anymore. |
errorComponent? |
SdkErrorComponent |
A custom error component to display when the SDK encounters an error. |
eventHandlers? |
SdkEventHandlersConfig |
See Handle embed events. |
loaderComponent? |
ComponentType<{ 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. |
locale? |
string |
Defines the display language. Accepts an ISO language code such as en or de. Defaults to the instance locale. |
pluginsConfig? |
MetabaseGlobalPluginsConfig |
See Plugins. |
theme? |
MetabaseEmbeddingTheme |
See Appearance. |
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 and Enterprise plans (both self-hosted and on Metabase Cloud).
The eventHandlers prop on MetabaseProvider maps event types to handler functions. See Handle embed events.
| Property | Type | Description |
|---|---|---|
onDashboardLoad? |
SdkDashboardLoadEvent |
Triggers when a dashboard loads with all visible cards and their content |
onDashboardLoadWithoutCards? |
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
Read docs for other versions of Metabase.