Config reference

Reference for the page-level config settings for web components, and the props you can pass to the React SDK’s MetabaseProvider.

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.
Optional
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.
Optional
authConfig Defines how to authenticate with Metabase.
children 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
A custom error component to display when the SDK encounters an error.
Optional
eventHandlers
Optional
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.
Optional
locale
string
Defines the display language. Accepts an ISO language code such as en or de. Defaults to the instance locale.
Optional
pluginsConfig
See Plugins.
Optional
theme
Optional
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).
Optional

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
Triggers when a dashboard loads with all visible cards and their content
Optional
onDashboardLoadWithoutCards
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.
Optional

Further reading

Read docs for other versions of Metabase.