| title | description |
|---|---|
Modular embedding SDK - quickstart |
This guide walks you through how to set up the modular embedding SDK in your application with your Metabase. |
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.
- 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](https://github.com/metabase/metabase-nodejs-react-sdk-embedding-sample/tree/{{page.version | remove: "v0."}}-stable).)
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.
To embed a dashboard in your app using the SDK, you'll need to:
- Enable the SDK in Metabase
- Create an API key in Metabase
- Install the SDK in your app
- Embed SDK components in your app
- View your embedded Metabase dashboard
In Metabase, click the grid icon in the upper right and navigate to Admin > Embedding > Modular and enable the SDK for React.
Still in the Admin console, go to Settings > Authentication and click on the API keys tab. 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).
When installing the npm package, it's critical to use the npm dist-tag that corresponds to the major version of your Metabase. For example, if your Metabase is version 1.56.x, you'd run 56-stable. See SDK versioning.
Via npm:
npm install @metabase/embedding-sdk-react@53-stable
Via Yarn:
yarn add @metabase/embedding-sdk-react@53-stable
In your app, import the SDK components, like so:
{% include_file "{{ dirname }}/snippets/quickstart/example.tsx" %}Run your app and visit the page with the embedded dashboard.
- 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.