Menu Close Get Metabase

Learn Metabase

Embedding charts and dashboards

This article covers the different ways you can embed charts and dashboards - all using the free, Open Source Edition of Metabase. If you’re looking for info on how to embed the entire Metabase app in your own application with the Enterprise Edition, check out this article.

We’ll go over:

  • Public links
  • Public embeds
  • Embedding questions and dashboards in your application (AKA signed embeds).

For quick sharing of questions and dashboards, you can simply send a public link, or drop an iframe in your website (or in anything that renders HTML). This is a great way for sharing charts and dashboards on the fly.

Enable public sharing

In order to share links to questions and dashboards, an admin must enable public sharing for your Metabase. Until sharing is enabled, Metabase won’t give us the public URL or iframe HTML.

To enable sharing, we’ll click on the gears icon in the main navigation bar, then select Admin. Once in the Admin panel, under the Settings tab’s left sidebar, we’ll select Public Sharing, and toggle on Enable public sharing.

<em>Fig. 1</em>. To share or embed dashboards, an admin will need to <strong>enable public sharing</strong>
Fig. 1. To share or embed dashboards, an admin will need to enable public sharing

All of our shared dashboards and questions will be listed here (once we start sharing them), and we’ll be able to disable the link as well.

Sharing options

Let’s say we want to share a dashboard, like the one in figure X. We’ll click on the sharing icon (the arrow pointing up and to the right), and select the Sharing and embedding option.

<em>Fig. 2</em>. An example dashboard using the Sample Dataset included with Metabase. To access the sharing options, click on the arrow in the upper right and select <strong>Sharing and embedding</strong>.
Fig. 2. An example dashboard using the Sample Dataset included with Metabase. To access the sharing options, click on the arrow in the upper right and select Sharing and embedding.

This will bring up our Sharing options:

<em>Fig. 3</em>. Sharing options include: <strong>Public link</strong>, <strong>Public embed</strong>, and <strong>Embed this dashboard in an Application</strong> (a signed embed).
Fig. 3. Sharing options include: Public link, Public embed, and Embed this dashboard in an Application (a signed embed).

A public link is the easiest way to share a dashboard. Public links aren’t even embeds; they’re just links to a single question or dashboard, though these public items are a little different than their original versions.

<em>Fig. 4</em>. An example of using a public link to share a dashboard, with the <strong>Powered by Metabase</strong> footer.
Fig. 4. An example of using a public link to share a dashboard, with the Powered by Metabase footer.

These public links will include a Powered by Metabase footer, which you can remove with Enterprise embedding. The charts will also have their action menus disabled, and we won’t be able to customize click behavior on a dashboard.

If we have a default filter value set, Metabase will apply that filter to the question or dashboard. People will be able to change the filter, so we can’t rely on filters to restrict which data people can see. To lock (or hide) a filter, we’ll need to use a signed embed.

We can also format the URL to assign a value to a filter, or hide the filter altogether - though keep in mind that the recipient can simply edit the URL. See our documentation to learn more about assigning values to filters or hiding them via the URL.

While these public links are hard to guess, anyone with that link could view our dashboard, so it’s not the best solution for sharing sensitive data. Still, we can quickly share a public link to a dashboard (with a customer, for example), then disable it once they’ve seen it. If we share the dashboard again, Metabase will generate a new link (so we don’t need to worry about access to the old link). If you accidentally share a link, you can disable it at any time; just toggle the sharing to off. Admins can view and disable all public links from the Admin panel.

Public embeds

We can embed a question or dashboard in our website using an iframe (an inline frame). It’s as simple as copying and pasting code from your Metabase and dropping it into the source code of a webpage. We can even use it with no-code website builders - anywhere we can drop in HTML. For example, you can embed a dashboard in a blog to help tell a story with data, or simply fill the whole page with a dashboard.

Here’s an iframe to display a dashboard:

<iframe
    src="http://your-website.com/public/dashboard/f54f5ae5-39a4-4662-85d5-a02e78165279"
    frameborder="0"
    width="800"
    height="600"
    allowtransparency
></iframe>

An iframe creates another, nested browser window inside the current browser window. The iframe window points to its own URL, and presents the response from that address - in this case, the chart or dashboard we want to present. Like the public link, the chart will feature the Powered by Metabase footer.

We can adjust the width and height to suit our chart or dashboard. If we’re embedding a dashboard and the iframe isn’t wide enough to accommodate the dashboards layout, Metabase will stack the questions in the order they appear, from left to right, on the dashboard.

Enable embedding in other applications

Here’s where we start to get serious. If we want to restrict who can see our chart or dashboard, or lock a filter, we’ll need to use a signed embed. This feature is separate from the public sharing options, and accessible only to admins. We’ll also have to enable the Embedding in other Applications setting before it’ll work. In the Admin panel -> Settings tab, along the left sidebar, we’ll click on Embedding in other Applications, and toggle Enabled.

Let’s return to the dashboard we want to share. With embedding enabled, we’ll get a secret key.

<em>Fig. 5</em>. With embedding enabled, you'll get a secret key used to sign JSON Web Tokens for requests to <code>/api/embed</code> endpoints.
Fig. 5. With embedding enabled, you'll get a secret key used to sign JSON Web Tokens for requests to /api/embed endpoints.

To set up a signed embed, we’ll need to insert some code on our server to sign JSON Web Tokens (JWT) for our users. Metabase will generate code for some languages: Clojure, Python, Ruby, and Javascript (Node.js), but you should be able to translate that code for servers written in other languages as well.

<em>Fig. 6</em>. Metabase will supply the code you'll need to include to sign your JSON web tokens.
Fig. 6. Metabase will supply the code you'll need to include to sign your JSON web tokens.

Before we hit Publish, let’s review some of our options.

Hide or lock parameters to restrict what data is shown

If our question or dashboard has a filter, we can disable the filter, or lock parameters to set a fixed filter value.

Let’s say we want to show someone a dashboard, but we only want to let them see orders in the Gadget category.

<em>Fig. 7</em>. Locking a filter with the value Gadget.
Fig. 7. Locking a filter with the value Gadget.

In our example, the parameters set the filter on the dashboard. Here we set the Category filter to Gadget.

Here’s some example code for a server written in Clojure:

(require '[buddy.sign.jwt :as jwt])

(def metabase-site-url   "MY-DOMAIN-HERE")
(def metabase-secret-key "SECRET-KEY-HERE")

(def payload
  {:resource {:dashboard 3}
   :params   {"category" ["Gadget"]}
   :exp      (+ (int (/ (System/currentTimeMillis) 1000)) (* 60 10))}) ; 10 minute expiration

(def token (jwt/sign payload metabase-secret-key))

(def iframe-url (str metabase-site-url "/embed/dashboard/" token "#bordered=true&titled=true"))

This code will use the secret key that Metabase gives us to sign the JSON Web Token (JWT) (our users will not - and should not - see the secret key).

Here’s how it will go down.

  1. In Metabase, we Publish the dashboard we want to embed in our application.
  2. We insert the iframe into a page of our application.
  3. We place the code to sign JSON web tokens in our server.
  4. Our user logs into our application.
  5. The user requests a page in our application with the embedded dashboard.
  6. When the server handles the request for that page, it will sign the user’s token and insert that token as the iframe’s source URL.
  7. When the page loads, the page requests the dashboard from our Metabase instance using the signed token.
  8. The dashboard loads in an iframe in our application with the paramaters and expiration set by our application server.

If the token is not signed, or if it’s altered in any way, the dashboard won’t load.

In the payload map, we can specify when the signed JWT will expire (in the code above, the token expires after 10 minutes).

The :params field is where we can lock a parameter to set a default, fixed filter on your dashboard or question. For example, we could create a dashboard with a filter for a user ID, then - on our server - programmatically insert a user’s ID as parameter. The signed token will lock the filter to that ID, so any user who sees that dashboard will only see data that’s been filtered by their ID.

Full app embedding

If you want to unlock the full potential of Metabase when embedding, which would allow people to drill through the data, or send them to custom destinations (like other dashboards, or external URLS), you’ll need full app embedding. To learn more, see Deliver analytics to your customers and Embed Metabase in your app to deliver multi-tenant, self-serving analytics.

Further reading