This repo contains example applications for common web frameworks that show how to embed Metabase dashboards in your application with guest embeds.
With a guest embed, your server signs a token, and your page passes the token to a Metabase component like <metabase-dashboard>. People who view the embed don't need a Metabase account.
If your customers need to explore data themselves, with drill-through, the query builder, or AI chat, check out modular embedding with SSO or full app embedding, and these resources:
- Modular embedding demo
- Modular embedding with SDK reference app
- Full app embedding quickstart
- Full app embedding demo
- Full app embedding reference app
If you're unsure which way to embed is best for you, check out our live demos and the embedding introduction.
This README walks you through getting Metabase up and running, as well as a simple web app, to show you a live example of an embedded dashboard.
Here's a Metabase dashboard embedded in the Node app:
Each app does the same thing in a different framework: it shows one dashboard as a guest embed, with a token that the app signs on the server. For comparison, each app's home page also shows a public embed.
| App | Where the embedding code is |
|---|---|
| Node | index.js |
| Django | user_stats/views.py |
| Rails | app/controllers/analytics_controller.rb |
| Laravel | app/Http/Controllers/AnalyticsController.php |
If you're not sure which one to try, check out the Node app.
There are also minimal, single-file examples, without a login:
- Django and Shiny: a guest embed of the same dashboard.
- HTML: a public embed, which is a public link in an iframe, with no token.
Guest embeds are available on every Metabase plan. On the Open Source and Starter plans, guest embeds show a "Powered by Metabase" banner.
To remove the banner, upgrade to a Pro or Enterprise plan. On those plans, you can also customize the colors and fonts of your embeds and hide the download buttons. On the Open Source and Starter plans, you can pick a light or dark theme.
- Java, to run the Metabase JAR. See Running the Metabase JAR file for the version that Metabase needs.
We'll first need to set up a running instance of Metabase to serve the embedded dashboards. The metabase directory of this repo has an application database with the dashboards that the apps embed.
- Shut down Metabase if you already have it running on your machine.
- Download the JAR file for Metabase OSS. The application database was last saved with Metabase 65, so use that version or a later one.
- Open up a terminal and clone this repo to your machine.
- Move the
metabase.jarfile from your downloads to thestatic-embedding-reference-apps/metabasedirectory. cdintostatic-embedding-reference-apps/metabase.- Run the JAR file:
java -jar metabase.jar - Run any example depending on the programming language you choose.
Once you've got Metabase running (on port 3000 by default):
- Go to
localhost:3000in your browser. - Log into Metabase.
- User: plucky@admin.com
- Password: Metabase123
- Click the grid icon in the upper right and select Embedding hub.
- Go to Security and check that Enable embedding is on. On Pro and Enterprise plans, the toggle is called Modular embedding.
- Customer overview (dashboard 3): the dashboard that the apps embed. It's published as a guest embed, and shows data from the Sample Database's Invoices and Analytic Events tables.
- A Public Dashboard (dashboard 1) and Number of Orders (question 1): items with public links. The apps' home pages show both as public embeds, and the HTML example embeds the question.
To see how a guest embed is set up, open the Customer overview dashboard, click the Share icon, and select Embed.
To see an embedded Metabase dashboard in action, set up Metabase, and follow the instructions in the README for one of the apps.
There are different ways to embed Metabase charts or dashboards in web applications.
The public embedding method is to simply use the public URLs inside of an iframe, or really anywhere you can insert HTML. A public link only opens that one question or dashboard, so people can't use it to get to anything else in your Metabase. But public embeds don't involve any authentication, so anyone with the URL can view the data, and anyone can change the filters in the URL. Don't use public embeds to restrict data.
With guest embeds, embedded questions and dashboards are signed using a secret key that your server shares with your Metabase. Metabase only loads the embed if the token is valid. This allows you to build dynamic dashboards with a parameter that can be locked down. You should sign the tokens on your server, which allows you to embed dashboards accessible to specific organizations, accounts, or users.
The web applications go into more detail about embedding, and provide examples. Start up the Node app and explore the app.
Static embedding puts the same signed token in an iframe URL, like /embed/dashboard/YOUR_JWT_TOKEN. Existing static embeds keep working, but use guest embeds for new work. The apps in this repo used static embedding before, and now use guest embeds.
On Pro and Enterprise plans, your customers' users can sign in to Metabase with SSO. Metabase then knows who's viewing, so permissions restrict the data, and you can offer drill-through, the query builder, and more. To keep each customer's data separate, see tenants. These kinds of embedding aren't covered in this repo.
- Embedding introduction
- Guest embeds
- Embedding parameters
- Securing embedded Metabase
- Tenants
- Public links and embeds
Check out the Metabase discussion forum and search for your issue. If you don't find any answers, please create an issue for this repository.
