Dashboard component reference
Reference material for embedding a dashboard: the attributes you can set on the <metabase-dashboard> web component, the props you can pass to the SDK’s StaticDashboard, InteractiveDashboard, and EditableDashboard components, and the options for creating dashboards from your app.
For how to set all this up, check out Embed a dashboard.
Web component metabase-dashboard attributes
These attributes apply to the <metabase-dashboard> web component. For the SDK, see StaticDashboard props, InteractiveDashboard props, and EditableDashboard props.
| Property | Type | Description |
|---|---|---|
auto-refresh-interval |
number |
Auto-refresh interval in seconds. For example, 60 refreshes the dashboard every 60 seconds.— Optional Available in Pro/Enterprise and Guest embed. |
custom-context |
string |
Optional custom context string passed through to the guest token endpoint. — Optional Available in Guest embed. |
dashboard-id |
string | number |
The ID of the dashboard to embed. Can be a regular ID or an entity ID. Only for SSO embeds — guest embeds set the ID with token. |
drills |
boolean |
Whether to enable drill-through on the dashboard. — Optional Default: trueAvailable in Pro/Enterprise. |
enable-entity-navigation |
boolean |
Whether to enable internal entity navigation (links to dashboards/questions). Requires drills to be true— Optional Default: falseAvailable in Pro/Enterprise. |
hidden-parameters |
string[] |
List of filter names to hide from the dashboard, e.g. ['productId'].— Optional Available in Pro/Enterprise. |
initial-parameters |
object |
Default values for dashboard filters, e.g. { 'productId': '42' }.— Optional Available in Pro/Enterprise and Guest embed. |
parameters |
object |
Controlled dashboard filters values, e.g. { 'productId': '42' }. Setting this attribute supersedes initial-parameters as the seed and stays in sync with subsequent mutations. Pair with the parameters-change DOM event to track edits.— Optional Available in Pro/Enterprise and Guest embed. |
token |
string |
The token for guest embeds. Set automatically by the guest embed flow. — Optional Available in Guest embed. |
with-downloads |
boolean |
Whether to show the button to download the dashboard as PDF and download question results. — Optional Default: true on OSS/Starter, false on Pro/EnterpriseAvailable in Guest embed. |
with-subscriptions |
boolean |
Whether to let people set up dashboard subscriptions. Subscriptions sent from embedded dashboards exclude links to Metabase items. — Optional Available in Pro/Enterprise. |
with-title |
boolean |
Whether to show the dashboard title in the embed. — Optional Default: trueAvailable in Guest embed. |
Depending on the framework you’re using, you may need to stringify attributes before passing them to the component. And if you surround an attribute’s value with double quotes, use single quotes inside it:
<metabase-dashboard
dashboard-id="1"
initial-parameters="{ 'productId': '42' }"
hidden-parameters="['productId']"
></metabase-dashboard>
These examples use sequential IDs — the number in the item’s URL. On Pro and Enterprise plans, you can use entity IDs instead; they stay the same when you serialize content from one Metabase to another, like from staging to production.
For all modular embeds, you can also set a locale in your page-level configuration to translate embedded content, including content from translation dictionaries.
React SDK StaticDashboard props
Modular embedding SDK is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).
StaticDashboard embeds a view-only dashboard: a lightweight component that displays results without letting people interact with the data.
| Property | Type | Description |
|---|---|---|
autoRefreshInterval? |
number |
The interval between auto refreshes on the dashboard, in seconds. |
className? |
string |
A custom class name to be added to the root element. |
dashboardId? |
SdkDashboardId | null |
The ID of the dashboard. This is either: - the numerical ID when accessing a dashboard link, i.e. http://localhost:3000/dashboard/1-my-dashboard where the ID is 1 - the string ID found in the entity_id key of the dashboard object when using the API directly or using the SDK Collection Browser to return data |
dataPickerProps? |
Pick<SdkQuestionProps, "entityTypes"> |
Additional props to pass to the query builder rendered by InteractiveQuestion when creating a new dashboard question. |
hiddenParameters? |
string[] |
A list of parameters to hide. - Combining initialParameters and hiddenParameters to filter data on the frontend is a security risk. - Combining initialParameters and hiddenParameters to declutter the user interface is fine. |
initialParameters? |
ParameterValues |
Initial values for query parameters, slug-keyed. Applied once on mount; user widget edits afterwards are not reflected back to the host. For each parameter: - set to a value (string for a single option, array of strings for multiple): that value is applied. - set to null: strictly cleared, ignoring the parameter’s default. - omitted (or set to undefined): falls back to the parameter’s default (or null if it has no default). - Combining initialParameters and hiddenParameters to filter data on the frontend is a security risk. - Combining initialParameters and hiddenParameters to declutter the user interface is fine. |
onLoad? |
(dashboard: MetabaseDashboard | null) => void |
Callback that is called when the dashboard is loaded. |
onLoadWithoutCards? |
(dashboard: MetabaseDashboard | null) => void |
Callback that is called when the dashboard is loaded without cards. |
onParametersChange? |
(payload: ParameterChangePayload) => void |
Fires on parameters change. The payload’s source distinguishes the initial state on load ('initial-state'), user edits in the UI ('manual-change'), and auto-updates ('auto-change'). |
onVisualizationChange? |
(visualization: | "object" | "table" | "bar" | "line" | "pie" | "scalar" | "row" | "area" | "combo" | "pivot" | "smartscalar" | "gauge" | "progress" | "funnel" | "map" | "scatter" | "boxplot" | "waterfall" | "sankey" | "treemap" | "list") => void |
A callback function that triggers when a question is opened from a dashboard card or when the user changes the visualization type of a question. |
parameters? |
ParameterValues |
Controlled parameter values, slug-keyed. On every render, this object replaces the dashboard’s parameter values: - a parameter set to a value uses that value. - a parameter set to null is cleared, even if it has a default. - a parameter omitted from the object (or set to undefined) uses its default (or null if it has no default). Pair with onParametersChange to stay in sync with user edits. - Combining parameters and hiddenParameters to filter data on the frontend is a security risk. - Combining parameters and hiddenParameters to declutter the user interface is fine. |
plugins? |
MetabasePluginsConfig |
Additional mapper function to override or add drill-down menu. See the implementing custom actions section for more details. |
style? |
CSSProperties |
A custom style object to be added to the root element. |
token? |
string | null |
A valid JWT token for the guest embed. |
withCardTitle? |
boolean |
Whether the dashboard cards should display a title. |
withDownloads? |
boolean |
Whether to hide the download button. |
withSubscriptions? |
boolean |
Whether to show the subscriptions button. |
withTitle? |
boolean |
Whether the dashboard should display a title. |
React SDK InteractiveDashboard props
Interactive dashboards are only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).
InteractiveDashboard embeds an interactive dashboard, with drill-downs, click behaviors, and the ability to view and click into questions.
| Property | Type | Description |
|---|---|---|
autoRefreshInterval? |
number |
The interval between auto refreshes on the dashboard, in seconds. |
className? |
string |
A custom class name to be added to the root element. |
dashboardId |
string | number |
The ID of the dashboard. This is either: - the numerical ID when accessing a dashboard link, i.e. http://localhost:3000/dashboard/1-my-dashboard where the ID is 1 - the string ID found in the entity_id key of the dashboard object when using the API directly or using the SDK Collection Browser to return data |
dataPickerProps? |
Pick<SdkQuestionProps, "entityTypes"> |
Additional props to pass to the query builder rendered by InteractiveQuestion when creating a new dashboard question. |
drillThroughQuestionHeight? |
Height<string | number> |
Height of a question component when drilled from the dashboard to a question level. |
drillThroughQuestionProps? |
DrillThroughQuestionProps |
Props of a question component when drilled from the dashboard to a question level. |
enableEntityNavigation? |
boolean |
When true, internal click behaviors (links to dashboards/questions) are preserved. When false (default for SDK), these click behaviors are filtered out. |
hiddenParameters? |
string[] |
A list of parameters to hide. - Combining initialParameters and hiddenParameters to filter data on the frontend is a security risk. - Combining initialParameters and hiddenParameters to declutter the user interface is fine. |
initialParameters? |
ParameterValues |
Initial values for query parameters, slug-keyed. Applied once on mount; user widget edits afterwards are not reflected back to the host. For each parameter: - set to a value (string for a single option, array of strings for multiple): that value is applied. - set to null: strictly cleared, ignoring the parameter’s default. - omitted (or set to undefined): falls back to the parameter’s default (or null if it has no default). - Combining initialParameters and hiddenParameters to filter data on the frontend is a security risk. - Combining initialParameters and hiddenParameters to declutter the user interface is fine. |
onLoad? |
(dashboard: MetabaseDashboard | null) => void |
Callback that is called when the dashboard is loaded. |
onLoadWithoutCards? |
(dashboard: MetabaseDashboard | null) => void |
Callback that is called when the dashboard is loaded without cards. |
onParametersChange? |
(payload: ParameterChangePayload) => void |
Fires on parameters change. The payload’s source distinguishes the initial state on load ('initial-state'), user edits in the UI ('manual-change'), and auto-updates ('auto-change'). |
onVisualizationChange? |
(visualization: | "object" | "table" | "bar" | "line" | "pie" | "scalar" | "row" | "area" | "combo" | "pivot" | "smartscalar" | "gauge" | "progress" | "funnel" | "map" | "scatter" | "boxplot" | "waterfall" | "sankey" | "treemap" | "list") => void |
A callback function that triggers when a question is opened from a dashboard card or when the user changes the visualization type of a question. |
parameters? |
ParameterValues |
Controlled parameter values, slug-keyed. On every render, this object replaces the dashboard’s parameter values: - a parameter set to a value uses that value. - a parameter set to null is cleared, even if it has a default. - a parameter omitted from the object (or set to undefined) uses its default (or null if it has no default). Pair with onParametersChange to stay in sync with user edits. - Combining parameters and hiddenParameters to filter data on the frontend is a security risk. - Combining parameters and hiddenParameters to declutter the user interface is fine. |
plugins? |
MetabasePluginsConfig |
Additional mapper function to override or add drill-down menu. See the implementing custom actions section for more details. |
renderDrillThroughQuestion? |
() => ReactNode |
A custom React component to render the question layout. Use namespaced InteractiveQuestion components to build the layout. |
style? |
CSSProperties |
A custom style object to be added to the root element. |
token? |
string | null |
- |
withCardTitle? |
boolean |
Whether the dashboard cards should display a title. |
withDownloads? |
boolean |
Whether to hide the download button. |
withSubscriptions? |
boolean |
Whether to show the subscriptions button. |
withTitle? |
boolean |
Whether the dashboard should display a title. |
React SDK EditableDashboard props
Modular embedding SDK is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).
EditableDashboard does everything InteractiveDashboard does, and also lets people edit the dashboard: add and update questions, layout, and content.
| Property | Type | Description |
|---|---|---|
autoRefreshInterval? |
number |
The interval between auto refreshes on the dashboard, in seconds. |
className? |
string |
A custom class name to be added to the root element. |
dashboardId |
string | number |
The ID of the dashboard. This is either: - the numerical ID when accessing a dashboard link, i.e. http://localhost:3000/dashboard/1-my-dashboard where the ID is 1 - the string ID found in the entity_id key of the dashboard object when using the API directly or using the SDK Collection Browser to return data |
dataPickerProps? |
Pick<SdkQuestionProps, "entityTypes"> |
Additional props to pass to the query builder rendered by InteractiveQuestion when creating a new dashboard question. |
drillThroughQuestionHeight? |
Height<string | number> |
Height of a question component when drilled from the dashboard to a question level. |
drillThroughQuestionProps? |
DrillThroughQuestionProps |
Props of a question component when drilled from the dashboard to a question level. |
enableEntityNavigation? |
boolean |
When true, internal click behaviors (links to dashboards/questions) are preserved. When false (default for SDK), these click behaviors are filtered out. |
hiddenParameters? |
string[] |
A list of parameters to hide. - Combining initialParameters and hiddenParameters to filter data on the frontend is a security risk. - Combining initialParameters and hiddenParameters to declutter the user interface is fine. |
initialParameters? |
ParameterValues |
Initial values for query parameters, slug-keyed. Applied once on mount; user widget edits afterwards are not reflected back to the host. For each parameter: - set to a value (string for a single option, array of strings for multiple): that value is applied. - set to null: strictly cleared, ignoring the parameter’s default. - omitted (or set to undefined): falls back to the parameter’s default (or null if it has no default). - Combining initialParameters and hiddenParameters to filter data on the frontend is a security risk. - Combining initialParameters and hiddenParameters to declutter the user interface is fine. |
onLoad? |
(dashboard: MetabaseDashboard | null) => void |
Callback that is called when the dashboard is loaded. |
onLoadWithoutCards? |
(dashboard: MetabaseDashboard | null) => void |
Callback that is called when the dashboard is loaded without cards. |
onParametersChange? |
(payload: ParameterChangePayload) => void |
Fires on parameters change. The payload’s source distinguishes the initial state on load ('initial-state'), user edits in the UI ('manual-change'), and auto-updates ('auto-change'). |
onVisualizationChange? |
(visualization: | "object" | "table" | "bar" | "line" | "pie" | "scalar" | "row" | "area" | "combo" | "pivot" | "smartscalar" | "gauge" | "progress" | "funnel" | "map" | "scatter" | "boxplot" | "waterfall" | "sankey" | "treemap" | "list") => void |
A callback function that triggers when a question is opened from a dashboard card or when the user changes the visualization type of a question. |
parameters? |
ParameterValues |
Controlled parameter values, slug-keyed. On every render, this object replaces the dashboard’s parameter values: - a parameter set to a value uses that value. - a parameter set to null is cleared, even if it has a default. - a parameter omitted from the object (or set to undefined) uses its default (or null if it has no default). Pair with onParametersChange to stay in sync with user edits. - Combining parameters and hiddenParameters to filter data on the frontend is a security risk. - Combining parameters and hiddenParameters to declutter the user interface is fine. |
plugins? |
MetabasePluginsConfig |
Additional mapper function to override or add drill-down menu. See the implementing custom actions section for more details. |
renderDrillThroughQuestion? |
() => ReactNode |
A custom React component to render the question layout. Use namespaced InteractiveQuestion components to build the layout. |
style? |
CSSProperties |
A custom style object to be added to the root element. |
token? |
string | null |
- |
withCardTitle? |
boolean |
Whether the dashboard cards should display a title. |
withDownloads? |
boolean |
Whether to hide the download button. |
withSubscriptions? |
boolean |
Whether to show the subscriptions button. |
withTitle? |
boolean |
Whether the dashboard should display a title. |
React SDK CreateDashboardModal props
Modular embedding SDK is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).
CreateDashboardModal lets people create a new dashboard from your app.
| Property | Type | Description |
|---|---|---|
initialCollectionId? |
SdkCollectionId |
Initial collection in which to create a dashboard. You can use predefined system values like root or personal. |
isOpen? |
boolean |
Whether the modal is open or not. |
onClose? |
() => void |
Handler to close modal component |
onCreate |
(dashboard: MetabaseDashboard) => void |
Handler to react on dashboard creation. |
targetCollection? |
SdkCollectionId |
The collection to save the dashboard to. This will hide the collection picker from the save modal. |
React SDK useCreateDashboardApi options
Modular embedding SDK is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).
useCreateDashboardApi creates a dashboard without Metabase’s own modal, so you can build your own UI.
| Property | Type | Description |
|---|---|---|
collectionId |
SdkCollectionId |
Collection in which to create a new dashboard. You can use predefined system values like root or personal. |
description |
string | null |
Dashboard description |
name |
string |
Dashboard title |
React SDK dashboardCardMenu plugin
Modular embedding SDK is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).
dashboardCardMenu controls the overflow menu on each dashboard card. It takes either a config object with the keys below, or a function returning a React element.
| Key | What it does |
|---|---|
withDownloads |
Shows or hides the download button. |
withEditLink |
Shows or hides the link to edit the question. |
customItems |
Your own menu items. Each element is either an item object or a function that receives { question } and returns one. |
See Customize the menu on dashboard cards.
Further reading
- Embed a dashboard
- Embed the query builder
- Question component reference
- Modular embedding components
- Modular embedding parameters
- Appearance
Read docs for other versions of Metabase.