Modular embedding SDK

The Modular embedding SDK requires a Pro or Enterprise plan and is available for React 18+ applications.

With the modular embedding SDK, you can embed individual Metabase components with React (like standalone charts, dashboards, the query builder, and more). You can manage access and interactivity per component, and you have advanced customization for seamless styling.

Why use the SDK?

The React Embedding SDK provides the most powerful and flexible way to embed Metabase:

Custom layouts

Build your own layouts using individual React components

Advanced theming

Deep customization with theme objects and CSS-in-JS

Plugins

Customize behavior with plugins for click actions and more

Type safety

Full TypeScript support with type definitions

Example apps built with the SDK

To give you an idea of what’s possible with the SDK, we’ve put together example sites at metaba.se/sdk-demo. Navigate between different shop websites and check out their products and analytics sections, as well as the New Question and New Dashboard options.

Pug and Play example app built with modular embedding SDK

Here’s the Shoppy source code on GitHub.

Prerequisites

Before you can use the SDK, make sure you have:

React application

React 18 or React 19 application

Node.js version

Node.js 20.x or higher

Metabase version

Metabase version 1.52 or higher

Metabase plan

Pro or Enterprise plan with valid license token

Quickstart guides

The best way to get started with Modular embedding SDK depends on what you already have:

Have app + Metabase

Main quickstart for existing apps

Have app, no Metabase

Quickstart with Metabase CLI

No app yet

Quickstart with sample React app

Installation

Enable the SDK in Metabase

Go to Admin > Embedding
Toggle on Modular embedding SDK
In Cross-Origin Resource Sharing (CORS), enter the origins for your website or app where you want to allow SDK embedding, separated by a space (localhost is automatically included)

Install the SDK in your React application

Install the modular embedding SDK via npm or yarn. Make sure to use the dist-tag that corresponds to your Metabase version (e.g., 56-stable for Metabase 56):

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

Make sure the SDK version matches your Metabase version. For example, if you’re running Metabase 56, use @metabase/embedding-sdk-react@56-stable.

Resolving @types/react version mismatches

In rare scenarios, the modular embedding SDK and your application may use different major versions of @types/react, causing TypeScript conflicts. To enforce a single @types/react version across all dependencies, add an override to your package.json:

npm
Yarn

package.json

{
  "overrides": {
    "@types/react": "^18.0.0"
  }
}

package.json

{
  "resolutions": {
    "@types/react": "^18.0.0"
  }
}

Architecture

Starting with Metabase 57, the SDK consists of two parts:

SDK Package

The @metabase/embedding-sdk-react npm package is a lightweight bootstrapper library. Its primary purpose is to load and run the main SDK Bundle code.

SDK Bundle

The full SDK code, served directly from your self-hosted Metabase instance or Metabase Cloud. This is part of Metabase itself, ensuring that the SDK code is always compatible with your Metabase instance.

This architecture ensures version compatibility—the SDK bundle is always served from your Metabase instance, so you never have to worry about SDK and Metabase version mismatches.

Basic usage example

Here’s a simple example of embedding a dashboard with the SDK:

App.tsx

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

const config = {
  metabaseInstanceUrl: "https://metabase.example.com",
  authProviderUri: "/api/sso/metabase",
};

export default function App() {
  return (
    <MetabaseProvider config={config}>
      <StaticDashboard dashboardId={1} />
    </MetabaseProvider>
  );
}

Key features

Components

The SDK provides components for all major Metabase entities:

Questions: StaticQuestion and InteractiveQuestion
Dashboards: StaticDashboard, InteractiveDashboard, and EditableDashboard
Collections: Collection browser for navigating content
AI Chat: Natural language query interface (Metabot)

Learn more about SDK components

Authentication

The SDK supports multiple authentication methods:

JWT SSO: For production use with multi-tenant applications
SAML SSO: Enterprise-grade SSO integration
API Keys: For local development and testing only

Learn more about authentication

Theming

Customize the appearance of embedded components with:

Theme objects for colors, fonts, and spacing
CSS-in-JS with emotion
Custom loader and error components
Full control over styling

Learn more about appearance

Plugins

Extend SDK functionality with plugins:

mapQuestionClickActions: Customize click behavior on charts
dashboardCardMenu: Add custom actions to dashboard cards
handleLink: Control navigation behavior

Learn more about plugins

Developing with the SDK

Start with one of the quickstarts, then explore these topics:

Authentication

Set up SSO with JWT or SAML

Components

Explore available React components

Appearance

Customize themes and styling

Plugins

Add custom behavior with plugins

Configuration

Configure the SDK provider

Versioning

Understand SDK versioning

SDK limitations

The SDK doesn’t support:

Verified content
Official collections
Dashboard link cards
Server-side rendering (SSR)

Other limitations:

Multiple interactive dashboards on the same application page. If you need to embed multiple dashboards on the same page, use static dashboards.
If you have Leaflet 1.x as a dependency in your app, you may run into compatibility issues. Try using Leaflet 2.x instead.

Source code and resources

GitHub Repository

View the SDK source code

npm Package

Check out the SDK on npm

Example Apps

See live examples built with the SDK

Shoppy Source

Full example application code

Support and feedback

Bugs: Report on GitHub
Feature requests: Submit on GitHub
Paid customers: Contact success team through usual channels
Open source users: Post on discussion forums

Before creating new issues, please search existing issues to avoid duplicates. You can upvote feature requests with a thumbs up emoji.

Next steps

Choose a quickstart

Pick the quickstart that matches your situation

Set up authentication

Configure JWT or SAML for production use

Embed your first component

Start with a simple dashboard or question

Customize appearance

Apply your brand’s theme and styling

Add interactivity

Use plugins to customize behavior

Getting Started

Questions & Dashboards

Data Modeling

Database Connections

Embedding

Administration

Installation & Operations

AI Features

​Why use the SDK?

Custom layouts

Advanced theming

Plugins

Type safety

​Example apps built with the SDK

​Prerequisites

​Quickstart guides

Have app + Metabase

Have app, no Metabase

No app yet

​Installation

​Resolving @types/react version mismatches

​Architecture

​Basic usage example

​Key features

​Components

​Authentication

​Theming

​Plugins

​Developing with the SDK

Authentication

Components

Appearance

Plugins

Configuration

Versioning

​SDK limitations

​Source code and resources

GitHub Repository

npm Package

Example Apps

Shoppy Source

​Support and feedback

​Next steps

Build docs developers (and LLMs) love

Why use the SDK?

Example apps built with the SDK

Prerequisites

Quickstart guides

Installation

Resolving @types/react version mismatches

Architecture

Basic usage example

Key features

Components

Authentication

Theming

Plugins

Developing with the SDK

SDK limitations

Source code and resources

Support and feedback

Next steps