Configure your embeds

Every modular embed on a page shares one configuration. How you configure your embeds depends on which embedding method you use:

• Web components: call defineMetabaseConfig() once per page. All Metabase components on the page use that config.
• React SDK: pass your config as props to MetabaseProvider. All Metabase components inside the provider use that config.

Settings for one embed, like a dashboard’s ID, go on the component. Settings for every embed, like your Metabase URL or theme, go in the shared configuration.

Configure web components

To configure web components, add a script tag to your page that loads embed.js from your Metabase, then call defineMetabaseConfig():

<!-- embed.js defines <metabase-dashboard> and other elements -->
<script defer src="https://your-metabase.example.com/app/embed.js"></script>
<script>
  function defineMetabaseConfig(config) {
    window.metabaseConfig = config;
  }
</script>

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase.example.com",
  });
</script>

<metabase-dashboard dashboard-id="1"></metabase-dashboard>

instanceUrl, the URL of your Metabase, is the only required setting.

For the full list of settings, see web component settings.

Configure the React SDK

To configure the React SDK, pass your config as props to MetabaseProvider. The only required prop is authConfig, which you create with defineMetabaseAuthConfig():

import React from "react";
import {
  MetabaseProvider,
  StaticDashboard,
  defineMetabaseAuthConfig,
} from "@metabase/embedding-sdk-react";

const authConfig = defineMetabaseAuthConfig({
  metabaseInstanceUrl: "https://your-metabase.example.com", // Required
});

export default function App() {
  return (
    <MetabaseProvider authConfig={authConfig}>
      {/* Metabase components go here */}
      <StaticDashboard dashboardId={1} />
    </MetabaseProvider>
  );
}

For the full list of props, see MetabaseProvider props.

Set how your embeds authenticate

Your config determines how every embed on the page authenticates:

• Guest embeds: view-only. Your server signs a token for each embed, so people don’t need Metabase accounts. See Configure a guest embed.
• SSO embeds: the default. Your app signs each person in to their own Metabase account, so their permissions apply. See Configure an SSO embed.

You can only use one type of authentication per page. To pick one, check out SSO or guest embeds.

Configure a guest embed

To configure guest embeds, set isGuest: true, which tells the components to authenticate with a signed JWT instead of a Metabase session. Where the setting goes depends on how you’re embedding.

With web components, add isGuest to the page-level config. You can also add guestEmbedProviderUri, which points to the endpoint in your app that signs the tokens:

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase.example.com",
    isGuest: true,
    guestEmbedProviderUri: "/api/metabase-guest-token",
  });
</script>

The embed calls the endpoint for a token on load, and again when the current token expires. Without guestEmbedProviderUri, your server must generate a token for each component and set the token in that component’s token attribute when building the page.

With the SDK, add isGuest to your auth config, and pass each component a token that your server signs. The SDK doesn’t support guestEmbedProviderUri.

// A JWT that your server signs with your Metabase embedding secret key.
const token = "YOUR_SIGNED_JWT";

const authConfig = defineMetabaseAuthConfig({
  metabaseInstanceUrl: "https://your-metabase.example.com",
  isGuest: true,
});

export default function App() {
  return (
    <MetabaseProvider authConfig={authConfig}>
      <StaticDashboard token={token} />
    </MetabaseProvider>
  );
}

Either way, you’ll need to publish each item you want to embed. For publishing and the server-side code, see guest embedding.

Configure an SSO embed

Embeds use SSO unless you set isGuest, so there’s no setting to turn SSO on. You’ll need to set up SSO in your Metabase and your app.

To customize how embeds fetch the JWT, set fetchRequestToken in defineMetabaseConfig() (web components) or defineMetabaseAuthConfig() (SDK). See customizing JWT authentication.

Preview embeds during development

To preview embeds without setting up authentication, use your own Metabase session or an API key. Both are for development only.

• Use your existing session (web components only): in defineMetabaseConfig(), set useExistingUserSession: true. The embed renders using your Metabase session. Only supported in Google Chrome.
• Use an API key: set apiKey in defineMetabaseConfig() (web components) or defineMetabaseAuthConfig() (SDK). Only works on localhost. See authenticating locally with API keys.

Set the language

To set the display language for every embed, add a locale with an ISO language code. The locale defaults to your Metabase instance’s locale.

Setting a locale translates Metabase’s UI, like menus and filter widgets. It doesn’t translate content you create, like dashboard names and filter labels. To translate your content, upload a translation dictionary.

• Web component
• React SDK

Web component locale

Add locale to the page-level config:

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase.example.com",
    locale: "de",
  });
</script>

React SDK locale

Pass locale to MetabaseProvider:

<MetabaseProvider authConfig={authConfig} locale="de">
  {children}
</MetabaseProvider>

Set a theme

To customize colors and fonts for every embed, add a theme object. The theme object is the same for web components and the SDK. For all the theme options, see Appearance.

• Web component
• React SDK

Web component theme

Add theme to the page-level config:

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase.example.com",
    theme: {
      colors: {
        brand: "#509EE3",
      },
    },
  });
</script>

React SDK theme

Create a theme with defineMetabaseTheme() and pass it to MetabaseProvider:

const theme = defineMetabaseTheme({
  colors: {
    brand: "#509EE3",
  },
});

return (
  <MetabaseProvider authConfig={authConfig} theme={theme}>
    {children}
  </MetabaseProvider>
);

Configure plugins

To customize the behavior of embedded components, add plugins with pluginsConfig. Plugins you set in the shared config apply to every embed.

• Web component
• React SDK

Web component plugins

Web components support one plugin, handleLink, which customizes what happens when people click a link in an embed. Add pluginsConfig to the page-level config:

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase.example.com",
    pluginsConfig: {
      handleLink: (urlString) => {
        const url = new URL(urlString, window.location.origin);
        if (url.origin === window.location.origin) {
          // Handle the link yourself, like with your app's router
          return { handled: true };
        }
        return { handled: false }; // Open the link in a new tab
      },
    },
  });
</script>

React SDK plugins

Pass pluginsConfig to MetabaseProvider:

<MetabaseProvider
  authConfig={authConfig}
  pluginsConfig={{
    // Return the default actions, plus any custom actions you add
    mapQuestionClickActions: (clickActions) => clickActions,
  }}
>
  {children}
</MetabaseProvider>

SDK components also take their own plugins prop, which overrides the global config.

For available plugins and their APIs, see plugins.

Allow custom visualizations

To render custom visualizations in your embeds, add the allowedCustomVisualizations allowlist to defineMetabaseConfig() (web components) or pass it to MetabaseProvider (SDK).

Custom visualizations require SSO. Guest embeds ignore the allowlist and show the default visualization instead.

For examples and the naming rules, see custom visualizations in embeds.

Handle embed events (React SDK only)

To run your own code when embeds load, like sending analytics events, pass an eventHandlers object to MetabaseProvider. There’s no web component equivalent.

const handleDashboardLoad: SdkDashboardLoadEvent = (dashboard) => {
  // Send analytics events, show notifications, etc.
};

const eventHandlers = {
  onDashboardLoad: handleDashboardLoad,
};

return (
  <MetabaseProvider authConfig={authConfig} eventHandlers={eventHandlers}>
    {children}
  </MetabaseProvider>
);

onDashboardLoad fires when a dashboard loads with all visible cards and their content.

For the full list of handlers, see eventHandlers.

Customize loading and error states (React SDK only)

To replace the SDK’s default loading and error screens, pass loaderComponent and errorComponent to MetabaseProvider. There’s no web component equivalent. See Customize loading, error, and empty states.

Reload a component (React SDK only)

Metabase components don’t detect your app’s data changes. To reload an embed after your app’s data changes, change the component’s key prop:

const [dataVersion, setDataVersion] = useState(0);

const saveOrder = async (order) => {
  await api.saveOrder(order); // Your app changes its data...
  setDataVersion((v) => v + 1); // ...then changes the key, reloading the embed.
};

return (
  <>
    <button onClick={() => saveOrder(order)}>Save order</button>
    <InteractiveQuestion key={dataVersion} questionId={yourQuestionId} />
  </>
);

Further reading

• Config reference
• Appearance
• Authentication
• Guest embedding
• Translating embeds
• Custom visualizations in embeds
• Modular embedding components
• Modular embedding SDK