Parameters for static embeds

Also known as: parameters for signed embeds, or standalone embeds.

Parameters are pieces of information that are passed between Metabase and your website via the embedding URL. You can use parameters to specify how Metabase items should look and behave inside the iframe on your website.

Embed a real dashboard in just 30 minutes.

Join our next Embedding Workshop

Types of parameters

Parameters can be signed or unsigned.

Signed parameters

Signed parameters, such as filter names and values, must be added to your server code.

• Editable parameters
• Locked parameters

Unsigned parameters

Unsigned parameters, such as appearance settings, should be added directly to your iframe’s src attribute.

• Default values for editable parameters
• Visibility settings for editable parameters
• Appearance settings

Adding a filter widget to a static embed

You can use editable parameters to add filter widgets to embedded dashboards or SQL questions.

1. Go to your dashboard or SQL question. Make sure you’ve set up a dashboard filter or SQL variable.
2. Click on the sharing icon > Embed this item in an application.
3. Under Parameters, you’ll find the names of your dashboard filters or SQL variables.
4. Select Editable for each parameter that should get a filter widget on your embed.
5. Click Publish to save your changes.
6. Add or update the code on your server to match the code generated by Metabase.

Editable parameters are responsible for passing filter values from the embedded filter widget (displayed on the iframe) through to the filters on your original dashboard or SQL question (in your Metabase).

You can’t disable parameters when the original question or dashboard requires a value

If the filter on a dashboard or question is set to Always require a value, you won’t be able to disable the parameter when embedding.

Populating an embedded filter widget with a default value

If you want to set a default value for your editable filter widget, you can pass that default value to the corresponding parameter name in your iframe’s src attribute:

your_embedding_url?parameter_name=value

For example, if your embedded dashboard has a filter connected to an editable parameter called “Breakfast”, and you want to set the default value to “Hash browns”:

your_embedding_url?breakfast=Hash_browns

To specify default values for multiple filters, separate them with ampersands (&):

your_embedding_url?breakfast=Hash_browns&lunch=Sandwich

You can set multiple default values for a single filter by separating the values with ampersands (&):

your_embedding_url?breakfast=Hash_browns&breakfast=Pancakes

Hiding filter widgets from a static embed

If you have multiple editable parameters (resulting in multiple filter widgets), you can hide specific ones from your static embed by adding #hide_parameters to the end of the URL in your iframe’s src attribute:

your_embedding_url#hide_parameters=parameter_name

For example, to hide a filter called “Breakfast” from your embedded dashboard:

your_embedding_url#hide_parameters=breakfast

You can hide multiple filter widgets by separating the parameter names with commas:

your_embedding_url#hide_parameters=breakfast,lunch

You can also simultaneously assign a parameter a default value and hide its filter widget:

your_embedding_url?breakfast=Hash_browns#hide_parameters=breakfast

Unsigned parameter syntax

Whenever you’re adding a parameter to the embedding URL in your iframe’s src attribute, note that:

• Parameter names are lowercase.
• Parameter values are case-sensitive (the values must match your data).
• Spaces should be replaced by underscores.

Restricting data in a static embed with locked parameters

If you want to restrict the data that’s displayed in an embedded dashboard or SQL question, you can set up a locked parameter. A locked parameter filters the data in a dashboard or SQL question before the results are displayed to people in a static embed.

1. Go to your dashboard or SQL question. Make sure you’ve set up a dashboard filter or SQL variable.
2. Click on the sharing icon > Embed this item in an application.
3. Under Parameters, you’ll find the names of your dashboard filters or SQL variables.
4. Select Locked for each parameter that you want to restrict your data with.
5. Optional: select a value under Preview locked parameters to see what the restricted data looks like.
6. Click Publish to save your changes.
7. Add or update the code on your server to match the code generated by Metabase.

You can use locked parameters to display filtered data based on attributes captured by your web server, such as a username or a tenant ID. For more examples, see the reference apps repo.

Locked parameters will apply the selected filter values to your original dashboard or SQL question, but they won’t be displayed as filter widgets on your embed. Locked parameters may also limit the values that are shown in your editable filter widgets.

If you just want to require a value for the parameter, you could set the filter as editable and configure the underlying question or dashboard to always require a value.

For more on how locked parameters work, check out guest embedding. The rules for locked parameters are the same for static embeds.

Customizing the appearance of a static embed

You can change the appearance of an embedded item by adding hash parameters (e.g., #theme=night) to the end of the URL in your iframe’s src attribute.

For example, the following embedding URL will display an embedded item in dark mode, without a border, and with its original title:

your_embedding_url#theme=night&bordered=false&titled=true

You can preview appearance settings from your question or dashboard’s embedded appearance settings.

* Available on Pro and Enterprise plans

** Disabling downloads is available on Pro and Enterprise plans.

For global appearance settings, such as the colors and fonts used across your entire Metabase instance, see Customizing Metabase’s appearance.

Setting the language for a static embed

To change the UI language for a static embed, you can set its locale. For example, to set a public link’s language to Korean, append #locale=ko:

https://metabase.example.com/public/dashboard/7b6e347b-6928-4aff-a56f-6cfa5b718c6b?category=&city=&state=#locale=ko

If you have multiple parameters, separate them with an ampersand (&):

category=Gadget&state=Vermont#theme=night&locale=ko

The locale parameter changes the language for Metabase UI elements, like the label of “Export to PDF” button. To change the content’s language in a static embed (like names of questions and dashboards), you’ll need to upload a translation dictionary.

Transparent backgrounds for embeds

Making an embed transparent depends on the type of embed:

• Dashboards: set background=false. The background parameter can be combined with the theme parameter (e.g., background=false&theme=night).
• Questions: set theme=transparent (deprecated, but still supported).

Disable downloads for an embedded question or dashboard

By default, Metabase will include a Download button on embedded questions, and an Export to PDF option on embedded dashboards.

You can configure these options with the downloads parameter in the embedding URL in the iframe’s src attribute, see customizing the appearance of static embeds.

downloads accepts the following values:

• true (default): include both the Download and Export to PDF options.
• false: hide both the Download and Export to PDF options.
• results: show the Download option.
• pdf: show the Export to PDF option (dashboards only).

You can combine the explicit options: downloads=results,pdf is the same as downloads=true.

The downloads parameter replaces the legacy hide_download_button parameter.

Maximum request size

The maximum length of a static embedding URL (including all parameters) is determined by your MB_JETTY_REQUEST_HEADER_SIZE environment variable. The default is 8192 bytes.

If your static embedding URL exceeds the maximum header size, you’ll see a log message like URI too long. You can update the environment variable to accept larger headers. If you’re using a proxy server, you may need to set a corresponding property on the server as well.

Further reading

• Static embedding documentation.
• Strategies for delivering customer-facing analytics.
• Publishing data visualizations to the web.