Modular embedding

Modular embedding lets you embed and customize Metabase components (like dashboards, the query builder, AI chat, and more) into your own application using web components. You don’t need to write embedding code from scratch—just use the wizard to create a code snippet and paste it into your app.

If you’re using React, check out the React Embedding SDK for a better developer experience with full TypeScript support and advanced features.

When to use modular embedding

Modular embedding is ideal when you want to:

Embed specific components (dashboards, questions, query builder)
Use a non-React framework (Vue, Angular, Svelte, etc.)
Have granular control over each embedded component
Customize appearance and behavior
Support both authenticated (SSO) and guest embeds

For modular embedding without authentication (available on all plans), see Guest Embeds.

Enable modular embedding

Go to Admin settings

In Metabase, navigate to Admin > Embedding

Enable modular embedding

Toggle on Enable modular embedding

Configure CORS (for authenticated embeds)

For authenticated embeds (Pro/Enterprise only):Under Cross-Origin Resource Sharing (CORS), add the URLs of the websites where you want to embed Metabase (such as https://*.example.com). For testing embeds, you can use localhost which is always included in CORS policy.

Handle cross-domain embedding (if needed)

If embedding on a different domain, see the authentication guide for additional configuration.

For guest embeds, you’re done after step 2! Continue to create a new embed or see the Guest embedding guide for detailed setup.

Create a new embed

You can generate a code snippet for embedding a component through the embed wizard:

1. Open the embed wizard

There are three ways to open the wizard:

From the item
Command palette
Admin panel

Visit the item you want to embed (question, dashboard, etc.)
Click the sharing icon
Select Embed

2. Pick authentication method

SSO (Pro/Enterprise)

With SSO, Metabase knows who is viewing the embed and can unlock advanced features like drill-through, query builder, and AI chat.

Guest embeds (All plans)

Simple, secure embedding without individual user accounts. Great for basic dashboards and charts.

For SSO setup, see the authentication guide. For guest embeds, see the guest embedding docs.

3. Customize your embed

The wizard shows customization options based on the entity type and your Metabase plan. You’ll see a live preview with your customizations.

Customization options

OSS/Starter plans
Pro/Enterprise plans

Light or dark theme selection
Show/hide title
Enable/disable downloads

Example theme customization in the generated code:

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    theme: {
      fontFamily: "Lato",
      fontSize: "16px",
      colors: {
        background: "#11123d",
        "text-primary": "#f9f9fc",
        brand: "#50e397",
        filter: "#7172AD",
        summarize: "#88BF4D",
      },
    },
  });
</script>

For more appearance options, see appearance customization.

4. Copy the code snippet

Once you’re done customizing, click Next to get your code snippet.

Add the embedding script to your app

The wizard generates a complete code snippet that includes:

Loading the modular embedding library from your Metabase instance
Global configuration (URL, theme, etc.)
The component(s) to embed with their parameters

Example code snippet

<!-- Load embedding library -->
<script defer src="https://your-metabase-url/app/embed.js"></script>

<!-- Embedding configuration -->
<script>
  function defineMetabaseConfig(config) {
    window.metabaseConfig = config;
  }
</script>

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    theme: {
      colors: {
        background: "#ffffff",
      },
    },
  });
</script>

<!-- Embedded entities -->
<metabase-question question-id="1"></metabase-question>

<metabase-dashboard dashboard-id="2" with-title="false"></metabase-dashboard>

Note the defer attribute on the script tag. Make sure to use the correct URL for your Metabase instance.

If you’re embedding multiple components on a single page, you only need to include the <script> tags once globally.

Available components

Modular embedding supports these web components:

Questions

Embed individual questions (charts):

<metabase-question 
  question-id="1"
  with-downloads="true"
></metabase-question>

Create new questions with the query builder:

<!-- Visual query builder -->
<metabase-question question-id="new"></metabase-question>

<!-- SQL editor -->
<metabase-question question-id="new-native"></metabase-question>

Dashboards

Embed interactive dashboards:

<metabase-dashboard 
  dashboard-id="2"
  with-title="true"
  with-downloads="false"
></metabase-dashboard>

Set initial parameter values:

<metabase-dashboard
  dashboard-id="2"
  initial-parameters="{ 'productId': '42', 'status': 'active' }"
></metabase-dashboard>

Hide specific parameters:

<metabase-dashboard
  dashboard-id="2"
  hidden-parameters="['productId', 'status']"
></metabase-dashboard>

Browser (authenticated embeds only)

The browser component is only available for authenticated modular embeds (SSO). It’s unavailable for guest embeds.

Embed a collection browser:

<metabase-browser
  initial-collection="14"
  read-only="false"
  collection-entity-types="['collection', 'dashboard']"
></metabase-browser>

AI chat (authenticated embeds only)

AI chat is only available for authenticated modular embeds (SSO) on Pro and Enterprise plans.

Embed the AI chat interface:

<metabase-metabot></metabase-metabot>

For detailed component properties, see modular embedding components.

Authentication requirements

Each end user should have their own Metabase account

For authenticated embeds (SSO), each end-user must have their own Metabase account. If you can’t provision accounts for every user, use Guest embeds instead.

The problem with sharing accounts:

All end-users have access to the same session token
They could use the token to access Metabase directly via the API
They could see data they’re not supposed to access

With individual accounts:

Configure proper permissions in Metabase
Everyone only sees data they should have access to
Fair usage of modular embedding

Page-level configuration

The defineMetabaseConfig() function sets configuration for all embeds on the page:

defineMetabaseConfig({
  // Required: Your Metabase instance URL
  instanceUrl: "https://your-metabase-url",

  // Optional: Theme customization
  theme: {
    fontFamily: "Inter",
    fontSize: "14px",
    colors: {
      brand: "#0066FF",
      background: "#FFFFFF",
      "text-primary": "#2E3338",
    },
  },

  // Optional: For local development only
  useExistingUserSession: true,  // Chrome only
  apiKey: "mb_YourAPIKey",        // Alternative for local dev

  // Optional: Custom JWT authentication
  fetchRequestToken: () => Promise<{ jwt: string }>,

  // Optional: Plugins for custom behavior
  pluginsConfig: {
    handleLink: (url) => {
      // Custom link handling
      console.log("Navigating to:", url);
      // Return false to prevent default behavior
    },
  },
});

Configuration options

instanceUrl

string

required

The URL of your Metabase instance (e.g., https://metabase.example.com)

theme

object

Appearance customization. See appearance docs for details.

useExistingUserSession

boolean

Development only. Preview embeds locally using your Metabase admin session. Only works in Chrome.

apiKey

string

Development only. Alternative way to preview embeds locally using an API key.

fetchRequestToken

function

Customize how the SDK fetches JWT tokens. See authentication docs.

pluginsConfig

object

Configure plugins like handleLink to customize behavior. See plugins docs.

Customization options for authenticated embeds

These options are available on Pro and Enterprise plans for authenticated embeds. For guest embed options, see guest embedding.

When creating authenticated embeds via Admin > Embedding > Setup guide, you’ll see these options:

Allow drill-through on data points

Determines whether people can interact with charts—drilling down to individual records, filtering on click, zooming in, etc.Disabling drill-through for an embedded question also disables adding filters and summaries.

Allow downloads

Determines whether people can download question results and save dashboards as PDFs.

Allow saving new questions

If you embed the query builder but disable this option, people can explore data but can’t save their work.

Parameters

For dashboard filters, SQL variables, and time grouping:

Set default values (overrides dashboard/question defaults)
Choose whether to hide the parameter from view

Show title

Display or hide the question/dashboard title.

Allow editing dashboards and questions

Lets people create and edit dashboards or questions in the current collection, including visual and SQL questions.When disabled, they can still filter, summarize, and drill-through, but can’t save results.

Allow alerts

Lets people set up email alerts on embedded questions.Requires email setup. Only for authenticated question embeds.

Authentication setup

For production use with authenticated embeds, you’ll need to set up authentication:

JWT SSO

Most common SSO method for embedded analytics

SAML SSO

Enterprise SSO with your identity provider

API keys

For local development only

Cross-domain

Configure CORS for different domains

See the authentication guide for complete setup instructions.

Dashboard auto-resizing

The <metabase-dashboard> web component automatically resizes to fit its content. No additional configuration is needed.

Best practices

Use the embed wizard

The wizard generates correct code snippets and helps you avoid common mistakes.

Test in your target environment

Always test embeds in the actual environment where they’ll be used, including testing CORS and authentication.

Configure proper permissions

Remember that hiding UI elements doesn’t replace proper Metabase permissions—configure data permissions correctly.

Use guest embeds when appropriate

If you don’t need drill-through or advanced features, guest embeds are simpler and work on all plans.

Consider the React SDK for React apps

If you’re using React, the React SDK provides better developer experience and more features.

Next steps

Component reference

Detailed documentation for all components

Authentication

Set up JWT or SAML SSO

Appearance

Customize themes and styling

Guest embeds

Simple embedding without SSO

Getting Started

Questions & Dashboards

Data Modeling

Database Connections

Embedding

Administration

Installation & Operations

AI Features

​When to use modular embedding

​Enable modular embedding

​Create a new embed

​1. Open the embed wizard

​2. Pick authentication method

SSO (Pro/Enterprise)

Guest embeds (All plans)

​3. Customize your embed

​Customization options

​4. Copy the code snippet

​Add the embedding script to your app

​Example code snippet

​Available components

​Questions

​Dashboards

​Browser (authenticated embeds only)

​AI chat (authenticated embeds only)

​Authentication requirements

​Each end user should have their own Metabase account

​Page-level configuration

​Configuration options

​Customization options for authenticated embeds

​Authentication setup

JWT SSO

SAML SSO

API keys

Cross-domain

​Dashboard auto-resizing

​Best practices

​Next steps

Component reference

Authentication

Appearance

Guest embeds

Build docs developers (and LLMs) love

When to use modular embedding

Enable modular embedding

Create a new embed

1. Open the embed wizard

2. Pick authentication method

3. Customize your embed

Customization options

4. Copy the code snippet

Add the embedding script to your app

Example code snippet

Available components

Questions

Dashboards

Browser (authenticated embeds only)

AI chat (authenticated embeds only)

Authentication requirements

Each end user should have their own Metabase account

Page-level configuration

Configuration options

Customization options for authenticated embeds

Authentication setup

Dashboard auto-resizing

Best practices

Next steps