Parameters for signed embeds

Also known as: parameters for 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.

Parameters are added to the end of your embedding URL, like this:

your_embedding_url?parameter_name=value

Adding a filter widget to a signed 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).

Note that locked parameters may limit the values that show up in an embedded filter widget.

Populating an embedded filter widget with a default value

If you want to set a default value for your embedded filter widget, you can pass that default value to the corresponding parameter name in the embedding URL. Note that:

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

For example, if your embedded dashboard has a filter called “Breakfast”, and you want to set the default value to “Scrambled eggs”:

your_embedding_url?breakfast=Scrambled_eggs

To specify default values for more than one filter, separate them with ampersands (&):

your_embedding_url?breakfast=Scrambled_eggs&lunch=Grilled_cheese

If the original dashboard’s filter widget accepts multiple values (i.e., it’s a dropdown filter, not a text box filter), you can set multiple default values:

your_embedding_url?breakfast=Scrambled_eggs&breakfast=Bacon

Restricting data in a signed embed

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 the end user in a signed embed.

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.

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. Add a value for the filter under Preview locked parameters.
6. Click Publish to save your changes.
7. Add or update the code on your server to match the code generated by Metabase.

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 embedded filter widgets.

Adding multiple values to a locked parameter

If your locked parameter is linked to a:

• dashboard filter, change the filter type to a dropdown filter.
• SQL question, change the SQL variable type.

For example, let’s say you have a text box filter on your original dashboard called “Breakfast” with the values “Scrambled eggs”, “Bacon”, and “Waffles”. With this setup, you’ll be able to choose one of “Scrambled eggs”, “Bacon”, or “Waffles” for a locked parameter linked to the “Breakfast” filter. If you want to provide the values “Scrambled eggs” and “Bacon to the locked parameter, change the original “Breakfast” filter on your dashboard to a dropdown filter.

Hiding filter widgets from a signed embed

If you have a lot of Editable parameters (resulting in a lot of filter widgets), you can hide them from your signed embed by adding hide_parameters to your embedding URL.

For example, if you want 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=Scrambled_eggs#hide_parameters=breakfast

Customizing the appearance of a signed embed

You can change the appearance of an embedded item by adding parameters with the following values:

* Available on paid plans.

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

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

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

Further reading

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