Embedding introduction

You can embed Metabase tables, charts, dashboards, AI chat—even Metabase’s query builder—in your website or application.

There are two ways to embed Metabase.

• Modular embedding: embed individual Metabase components, like questions, dashboards, and AI chat, so they seamlessly integrate with your app.
• Full app embedding: embed the full Metabase app in an iframe, styled like your branding.

Most people go with modular embedding, so you can integrate Metabase components into your app.

Whichever way you embed, you’ll also pick how Metabase authenticates the people looking at it. Authentication is a setting on what you embed, not a different kind of embedding.

If you just want to share a chart or dashboard with anyone who has the link, and you don’t need any authentication, take a look at public links and embeds.

Modular embedding

With modular embedding, you can embed individual Metabase components in your web app: dashboards, questions, the query builder, AI chat, and a collection browser.

When you setting up an embed, you need to pick an authentication method:

• Metabase account (SSO), for components with SSO authentication
• Guest, for components with guest authentication

The authentication method you choose determines what people can do (see the comparison below).

You can only use one authentication method per page of your app. A single page can’t mix a question that uses SSO with a question that uses guest authentication.

Comparison between SSO and guest authentication

All SSO options require a Pro or Enterprise plan.

* Each authentication method allows data downloads by default, but only Pro and Enterprise plans can disable data downloads.

** Requires a Pro and Enterprise plan with either authentication method.

*** Components that use SSO don’t need locked filters. Since Metabase knows who’s viewing, you can segregate data with permissions instead. There’s a little more set up, but much less long-term overhead.

Components with SSO authentication

With SSO, Metabase can know who’s viewing what, which unlocks a lot of stuff. You can automatically apply data permissions, which means you can give people access to all the cool tools Metabase provides, and everyone will only ever see the data they’re allowed to.

When to use SSO: You want to offer multi-tenant, self-service analytics, or you want to include the query builder, AI chat, drill-through, or a collection browser.

SSO requires a Pro or Enterprise plan, and everyone viewing the embedded component needs their own Metabase account. To set up JWT or SAML, check out modular embedding authentication.

If you’re building a SaaS product with embedded analytics for multiple customers, you can keep customer data isolated with Tenants.

Accounts for these embedded people in your Metabase count toward the accounts billed in your Metabase plan. But by letting your customers self-serve their data, you save time on developing bespoke charts. And you can charge more for a premium analytics experience. If you plan on giving a lot of your customers self-service access to their data, you should consider an enterprise plan, with custom pricing that scales with your business.

Components with guest authentication

With guest authentication, Metabase doesn’t create a session for the person viewing the component, so you don’t have to create a Metabase account for everyone who sees your charts and dashboards. Guest authentication works on all Metabase plans, including OSS and Starter.

Guest doesn’t mean unsecured. Metabase only loads the component if the request carries a JWT signed with a secret shared between your app and your Metabase. What Metabase doesn’t have is an identity: with no account to check permissions against, Metabase can’t tell whether a new query is one that person should be allowed to run. That’s why components with guest authentication are view-only.

When to use guest: embedding charts and dashboards where you don’t want to offer ad-hoc querying or chart drill-through. To filter data down to what’s relevant to the person viewing, use locked parameters, where your app sets the filter value in the signed token.

Set up modular embeds with web components or React

Whichever way you authenticate, you can set up modular embeds two ways.

• Web components: a script tag plus HTML elements like <metabase-question>. Web components have no build step and no framework requirement, so they work in plain HTML, Vue, Svelte, Rails, React, or any framework you like. Metabase’s in-app wizard writes the code for you.
• React SDK: React components that you import and compose yourself. The SDK gives you more control: you can build custom layouts and customize behavior with plugins.

If your app runs on React and you want that extra control, go with the SDK. Otherwise start with web components. You can always move to the SDK later.

Full app embedding

Full app embedding allows you to embed the entire Metabase app in an iframe, and integrate Metabase SSO with your app’s authentication.

Public links and embeds

If you’d like to share your data with the good people of the internet, admins can create a public link or embed a question or dashboard directly in your website. A public link is a URL you can hand to anyone. A public embed is an iframe snippet you drop into one of your pages. Neither one is really an embedding setup — there’s no authentication, and anyone with the link can see the data.

When to use public links and embeds: one-off charts and dashboards. Admins can use public links when you just need to show someone a chart or dashboard without giving people access to your Metabase. And you don’t care who sees the data; you want to make the item available to everyone.

Resources for AI agents

If you’re using an AI agent to help you embed Metabase in your app, check out AI agent resources.

Tracking embed usage

Usage Analytics tracks embed usage, including embedding context, authentication methods, hostname, and other metadata. Check out the Embedding usage dashboard.

For information about the anonymous usage data Metabase collects from embedded components, see Embedding telemetry.

Embedding limitations

• Currently, you can’t embed documents (though you can create public documents).
• Only the Modular embedding SDK renders custom visualizations, and only ones you allowlist with the allowedCustomVisualizations prop. In other embedding types, any card that uses a custom visualization falls back to the default visualization for the query’s results.

Further reading

• Strategies for delivering customer-facing analytics.
• Publishing data visualizations to the web.
• Multi-tenant self-service analytics.
• Customizing Metabase’s appearance.
• Securing embedded Metabase.