Modular embedding SDK - quickstart

This guide walks you through how to set up the Modular embedding SDK in your application with your Metabase using API keys.

This setup:

• Is only for evaluation (so you can see how the SDK works).
• Only works on localhost when developing your app (though your Metabase doesn’t need to be running locally).
• Works with both the Enterprise and Open Source editions of Metabase, both self-hosted and on Metabase Cloud.

If you want to use the SDK in production, however, you’ll also need to set up JWT SSO authentication, which requires a Pro or Enterprise plan. To enable JWT SSO when you’re self-hosting Metabase, you’ll need to run the Enterprise Edition Docker image or JAR, and activate your license.

Prerequisites

• Metabase version 52 or higher (OSS or EE). See Installing Metabase.
• Make sure your React version is compatible. (You could also use the sample React app.)

If you don’t have a Metabase up and running, check out the Quickstart CLI.

If you don’t want to use your own application code, check out our quickstart with a sample app.

Overview

To embed a dashboard in your app using the SDK, you’ll need to:

1. Enable the SDK in Metabase
2. Create an API key in Metabase
3. Install the SDK in your app
4. Embed SDK components in your app
5. View your embedded Metabase dashboard

1. Enable the SDK in Metabase

In Metabase, click the grid icon in the upper right, select Embedding hub, and go to Security. Toggle on Modular embedding React SDK.

2. Create an API key in Metabase

Click the grid icon, select Admin, and go to Settings > Authentication > API keys. Create a new API key.

• Key name: “Modular embedding SDK” (just to make the key easy to identify).
• Group: select “Admin” (since this is only for local testing).

3. Install the SDK in your app

Install the @{major}-stable dist-tag matching your Metabase major, so the package’s types and exported components in your client match your SDK bundle served from your Metabase. For Metabase 60:

Via npm:

npm install @metabase/embedding-sdk-react@60-stable

Via Yarn:

yarn add @metabase/embedding-sdk-react@60-stable

See SDK versions for other install options.

4. Embed SDK components in your app

In your app, import the SDK components, like so:

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

/**
 * This creates an auth config to pass to the `MetabaseProvider` component.
 * You'll need to replace the `metabaseInstanceUrl` and the `apiKey` values.
 */
const authConfig = defineMetabaseAuthConfig({
  metabaseInstanceUrl: "https://metabase.example.com",
  apiKey: "YOUR_API_KEY",
});

/**
 * Now embed your first dashboard. In this case, we're embedding the dashboard with ID 1.
 * On new Metabases, ID 1 will be the example dashboard, but feel free to use a different dashboard ID.
 */
export default function App() {
  return (
    <MetabaseProvider authConfig={authConfig}>
      <InteractiveDashboard dashboardId={1} />
    </MetabaseProvider>
  );
}

5. View your embedded Metabase dashboard

Run your app and visit the page with the embedded dashboard.

Next steps

• Explore theming to change the look and feel.
• Continue by setting up JWT SSO in Metabase and your app to sign people in, manage permissions, and deploy your app in production.