Embedding parameters reference

Reference material for parameters in embedded dashboards and charts. For how to use all this, check out Embedding parameters.

For each attribute’s or prop’s type and description, see:

• Dashboard component reference
• Question component reference

Which props to use

What you want	On	Web component	React SDK
Starting values	Dashboard	initial-parameters	initialParameters
	SQL question	initial-sql-parameters	initialSqlParameters
Controlled values	Dashboard	parameters	parameters
	SQL question	sql-parameters	sqlParameters
Change notification	Dashboard	parameters-change event	onParametersChange
	SQL question	sql-parameters-change event	onSqlParametersChange
Hide widgets	Both	hidden-parameters	hiddenParameters

Web component attribute parsing

The parameter attributes take JSON: an object keyed by slug, or for hidden-parameters, an array of slugs.

Attribute values are parsed as JSON5, so single quotes, unquoted keys, and trailing commas all work. Only values that start with { or [ are parsed as JSON. Other values stay strings, except true, false, and bare numbers, which become booleans and numbers. So wrap even a single slug in hidden-parameters in []. Without the brackets, a dashboard embed won’t render at all, and the console shows a TypeError rather than a message about the attribute. A question embed still renders, but it hides every parameter whose slug appears anywhere in the string. A value that starts with { or [, but that doesn’t parse, stays a string, and Metabase logs an error.

Changing initial-parameters, initial-sql-parameters, or hidden-parameters after the embed has loaded re-renders the embed from scratch with the new values. Changing parameters or sql-parameters applies the new values and re-runs the queries, without re-rendering the embed from scratch.

Value formats by parameter type

These formats apply wherever you pass a value: web component attributes, SDK props, and the params object in a signed token.

Parameter type	Accepts	Examples
Text, category, ID	A string, or an array of strings for multi-select filters.	"Gizmo", ["Gizmo", "Gadget"]
Number	A number, a numeric string, or an array of either. Two-element arrays for between filters.	50, "50", [10, 20]
Boolean	true or false, or the strings "true" and "false".	true
Date	A string in one of the formats below.	"past30days", "2024-01-01~2024-03-31"
Time grouping	A unit name.	"month", "week", "quarter"

To clear a filter, pass null for its slug. To reset it to its default, leave the slug out.

The change callback hands values back as arrays: push 4 and you get [4]. Date and time grouping values are the exception and stay strings.

A Between number filter takes a two-element array with the lower and upper bounds, like [10, 20]. This works when the dashboard filter is connected to a column in a query builder question, or to a field filter in a SQL question. It also works for a field filter on an embedded SQL question, if the field filter’s widget type is Between.

A Between filter doesn’t work with a plain SQL variable: Metabase only lets you connect a plain number variable to a filter that uses Equal to, so a Between filter can’t be connected to one at all. To filter a plain variable by a range, use two variables in the SQL, like WHERE total BETWEEN {{min_total}} AND {{max_total}}, and connect each one to its own Equal to filter. Both variables need a value, or the query won’t run. To let either end stay open, put each comparison in its own optional clause, like WHERE TRUE [[AND total >= {{min_total}}]] [[AND total <= {{max_total}}]].

In the params of a signed token, [10, null] and [null, 20] give a between filter an open end. Through attributes and props, pass a closed range: the embed drops the null and applies the remaining number as a lower bound. So [null, 20] doesn’t mean up to 20; it’s applied as 20 and up. Pass [0, 20] instead.

Date formats

The quickest way to get these values is to set the filter in Metabase and copy it from the address bar.

Format	Meaning
2024-01-02	A single day. Add a time with 2024-01-02T10:20:00.
2024-04	A whole month.
Q2-2024	A whole quarter.
2024-01-02~2024-05-10	A range, inclusive. Both ends can carry a time.
~2024-01-02	Before that day.
2024-01-02~	After that day.
today, yesterday	That day.
thisday, thisweek, thismonth, thisquarter, thisyear	The current unit.
lastday, lastweek, lastmonth, lastquarter, lastyear	The previous unit.
past30days, past3months, past1years	The last N units, not counting the current one. Units: minutes, hours, days, weeks, months, quarters, years.
past30days~	Same, but including the current unit.
next7days, next7days~	The next N units, with or without the current one.
past30days-from-2years	The last 30 days, starting 2 years ago. Same for next…-from-….
exclude-hours-0-23	Exclude hours of the day, 0 through 23. List each hour, separated by hyphens.
exclude-days-Mon-Sun	Exclude days of the week, using Mon through Sun.
exclude-months-Jan-Dec	Exclude months, using Jan through Dec.
exclude-quarters-1-4	Exclude quarters, 1 through 4.

A plain SQL date variable takes a single date, like 2024-01-02, with an optional time. Every other format in this table needs a dashboard filter connected to a column, or a field filter.

In an embed, the filter widget shows no label for the last… values, but the filter still applies.

Change payload

onParametersChange (SDK) and the parameters-change event (web component, as event.detail) both deliver the same object, a ParameterChangePayload. parameters, defaultParameters, and lastUsedParameters are each keyed by parameter slug and list every parameter on the item, with null where there’s no value.

Field	What it holds
parameters	The values currently applied to the embed.
defaultParameters	Each parameter’s default value.
lastUsedParameters	The values this person last applied on this dashboard. Dashboards only.
source	Why the callback fired. See When the callback fires.

SQL questions deliver a SqlParameterChangePayload through onSqlParametersChange or sql-parameters-change. It’s the same object without lastUsedParameters.

When the callback fires

The source field says which of these happened:

source	Fires when
initial-state	The embed finishes loading. Once per load.
manual-change	Someone applies a value with one of Metabase’s filter widgets. On a dashboard with auto-apply turned off, editing a widget doesn’t count; clicking Apply does.
auto-change	You pushed values and Metabase applied something different. The payload carries what was actually applied.

Metabase normalizes values before applying them, so auto-change usually means one of two things:

• You pushed a bare value, and Metabase stored it as an array. Pushing [4] fires nothing.
• You left a slug out. A push replaces every value, so each slug you didn’t include resolves to its default, or null if it has none, and auto-change reports it.

Params in a signed token

On guest embeds, your server passes parameter values in the params object of the JWT it signs. What Metabase does with them depends on the visibility you chose for each parameter in the embed wizard. The error messages below are for a parameter with the slug category.

Wizard setting	Token sets it	Page sets it (initial-parameters, widget, or URL)	Widget shows
Disabled	Rejected: You're not allowed to specify a value for category.	Rejected, same error.	No
Editable	Allowed. The widget disappears for that token.	Allowed, unless the token also sets it: You can't specify a value for category if it's already set in the JWT.	Yes
Locked	Required: You must specify a value for :category in the JWT.	Rejected: You can only specify a value for category in the JWT.	No

Metabase checks these rules when a card runs its query, not when the dashboard loads. A token that breaks one of these rules still renders the dashboard’s frame and widgets, and each card shows the error in place of its chart. A token that Metabase can’t accept at all, like one without params, with a bad signature, or that has expired, stops the whole embed from loading.

Other rules:

• Always include params (even just as {}). A token without params is rejected with Token is missing value for keypath [:params].
• A slug that isn’t in the embed’s published settings is rejected with Unknown parameter category. That includes a filter you added to the item after you last published the embed, so publish again after you add one.
• Pass values as arrays, one element per value: { category: ["Gadget", "Gizmo"] }. A bare value like { category: "Gadget" } works too, but arrays behave consistently everywhere, including in the dropdown values of editable widgets.
• For a locked filter connected to a plain variable in a SQL question, Metabase substitutes the values as a comma-separated list. That works inside IN ({{variable}}), but after = it’s a SQL error from your database, not a Metabase error. So, unless the query is written for a list, pass one element. To deal with several values, connect the filter to a field filter instead, which expands to IN (...) on its own, and wrap the tag in [[ ]] so [] turns the clause off.
• An empty array, [], means “no value” and turns the filter off for that token.
• A blank string, "", or null counts as no value at all. On a locked parameter that’s the same as leaving the parameter out, so the token is rejected.
• Metabase substitutes token values into text cards on the server, so a text card variable that’s connected to the filter shows the value even though the browser never receives it.

For a walkthrough, check out Restrict data on guest embeds. For how to sign and refresh the token, check out Guest embeds.

Further reading

• Embedding parameters
• Dashboard component reference
• Question component reference
• Guest embeds
• Modular embedding components