| title | redirect_from | |
|---|---|---|
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.
Parameters can be signed or unsigned.
Signed parameters, such as filter names and values, must be added to your server code.
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
You can use editable parameters to add filter widgets to embedded dashboards or SQL questions.
- Go to your dashboard or SQL question. Make sure you've set up a dashboard filter or SQL variable.
- Click on the sharing icon > Embed this item in an application.
- Under Parameters, you'll find the names of your dashboard filters or SQL variables.
- Select Editable for each parameter that should get a filter widget on your embed.
- Click Publish to save your changes.
- 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).
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.
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
Let's say your embedded dashboard has a filter connected to an editable parameter called "Breakfast". If you want to set the default value for the "Breakfast" filter to "Scrambled eggs":
your_embedding_url?breakfast=Scrambled_eggs
To specify default values for more than one filter, separate the filters with ampersands (&):
your_embedding_url?breakfast=Scrambled_eggs&lunch=Grilled_cheese
You can set multiple default values for a filter by separating the key=value pairs with ampersands (&):
your_embedding_url?breakfast=Scrambled_eggs&breakfast=Bacon
If you have a lot of editable parameters (resulting in a lot of filter widgets), you can hide them 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, 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
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.
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.
- Go to your dashboard or SQL question. Make sure you've set up a dashboard filter or SQL variable.
- Click on the sharing icon > Embed this item in an application.
- Under Parameters, you'll find the names of your dashboard filters or SQL variables.
- Select Locked for each parameter that you want to restrict your data with.
- Optional: select a value under Preview locked parameters to see what the restricted data looks like.
- Click Publish to save your changes.
- 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.
Things to keep in mind if you need to make changes to your locked parameters.
Once you publish a chart or dashboard with a locked parameter, you must include the name of the locked parameter in your server code. If you forget to do this, the logs will remind you with a message like this: You must specify a value for :parameter in the JWT.
If you change the name of a query builder filter that's used as a locked parameter, make sure to update the parameter's name and value(s) in your server code as well. You don't have to do this if your locked parameter is connected to a SQL variable.
The values for the locked parameter in your server code should match your filter's values exactly. The best way to set multiple locked parameters, or pass multiple values to a locked parameter, is to pick a filter value under Preview locked parameters and preview the server code generated by Metabase.
If your locked parameter is linked to a dashboard filter that's in turn linked to a SQL question, you'll only be able to choose a single value for your locked parameter.
For example, let's say you have a dashboard filter called "Breakfast" with the values "Hash browns", "Muffin", and "Waffles". If the "Breakfast" filter is linked to any SQL questions on the dashboard, you'll only be able to choose one of the options for a locked parameter linked to the "Breakfast" filter.
You can change the appearance of an embedded item by adding hash parameters 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.
| Parameter name | Possible values |
|---|---|
bordered |
true, false |
titled |
true, false |
theme |
null, transparent, night |
refresh (dashboard only) |
integer (seconds, e.g., refresh=60) |
font* |
font name |
hide_download_button* (questions only) |
true, false |
* Available on Pro and Enterprise plans.
{% include plans-blockquote.html feature="Downloading results" %}
By default, Metabase will include a Download button on embedded questions. You can remove the download button by setting hide_download_button=true in the embedding URL in the iframe's src attribute, see customizing the appearance of static embeds.
If the download button is missing when you expected it to be available, check that the URL in the src attribute for your iframe has the parameter hide_download_button=false.
Downloading results is available only for questions, not dashboards.
The maximum length of a static embedding URL (including all parameters) is the value of 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.