48.5k Log in Get started
Analytics
Embedding
Administration
Other resources

Question component reference

Reference material for embedding a chart or a query editor: the attributes you can set on the <metabase-question> web component, the props you can pass to the SDK’s StaticQuestion and InteractiveQuestion components, and the namespaced components you can use to build your own layout.

For how to set all this up, check out Embed a chart and Embed the query builder.

metabase-question web component attributes

These attributes apply to the <metabase-question> web component. For the SDK, see StaticQuestion props and InteractiveQuestion props.

Property Type Description
custom-context string Optional custom context string passed through to the guest token endpoint.
—
Optional
Available in Guest embed.
drills boolean Whether to enable drill-through on the question.
—
Optional
Default: true
Available in Pro/Enterprise.
entity-types string[] Which entity types to show in the question’s data picker, e.g. ["model", "table"].
—
Optional
Possible values: "model", "table"
Available in Pro/Enterprise and Guest embed.
hidden-parameters string[] List of parameter names to hide from the question.
—
Optional
Available in Pro/Enterprise.
initial-sql-parameters object Default values for SQL parameters, only applicable to native SQL questions, e.g. { "productId": "42" }.
—
Optional
Available in Pro/Enterprise and Guest embed.
is-save-enabled boolean Whether the save button is enabled.
—
Optional
Default: false
Available in Pro/Enterprise.
question-id string | number The ID of the question to embed. Can be a regular ID or an entity ID. Use "new" to embed the query builder, or "new-native" to embed the SQL editor. Only for SSO embeds — guest embeds use token.
sql-parameters object Controlled SQL parameter values, e.g. { "productId": "42" }. Setting this attribute supersedes initial-sql-parameters as the seed and stays in sync with subsequent mutations. Pair with the sql-parameters-change DOM event to track edits.
—
Optional
Available in Pro/Enterprise and Guest embed.
target-collection string | number The collection to save a question to. Values: regular ID, entity ID, "personal", "root".
—
Optional
Available in Pro/Enterprise.
token string The token for guest embeds. Set automatically by the guest embed flow.
—
Optional
Available in Guest embed.
with-alerts boolean Whether to show the alerts button.
—
Optional
Default: false
Available in Pro/Enterprise.
with-downloads boolean Whether to show download buttons for question results.
—
Optional
Default: true on OSS/Starter, false on Pro/Enterprise
Available in Guest embed.
with-title boolean Whether to show the question title in the embed.
—
Optional
Default: true
Available in Guest embed.

StaticQuestion props

Modular embedding SDK is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).

StaticQuestion embeds a view-only chart.

Property Type Description
className? string A custom class name to be added to the root element.
height? Height<string | number> A number or string specifying a CSS size value that specifies the height of the component
hiddenParameters? string[] A list of parameters to hide.
initialSqlParameters? SqlParameterValues Initial values for SQL 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: 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).
onSqlParametersChange? (payload: SqlParameterChangePayload) => void Fires on SQL 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').
query? undefined -
questionId? SdkQuestionId | null The ID of the question.
This is either:
- the numerical ID when accessing a question link, i.e. http://localhost:3000/question/1-my-question where the ID is 1
- the string ID found in the entity_id key of the question object when using the API directly or using the SDK Collection Browser to return data
- new to show the notebook editor for creating new questions
- new-native to show the SQL editor for creating new native questions
sqlParameters? SqlParameterValues Controlled SQL parameter values, slug-keyed. On every render, this object replaces the question’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 onSqlParametersChange to stay in sync with user edits.
style? CSSProperties A custom style object to be added to the root element.
title? SdkQuestionTitleProps Determines whether the question title is displayed, and allows a custom title to be displayed instead of the default question title. Shown by default.
token? string | null A valid JWT token for the guest embed.
width? Width<string | number> A number or string specifying a CSS size value that specifies the width of the component
withAlerts? boolean Enables the ability to set up alerts on the question.
withChartTypeSelector? boolean Determines whether the chart type selector and corresponding settings button are shown. Only relevant when using the default layout.
withDownloads? boolean Enables the ability to download results in the question.

InteractiveQuestion props

Interactive charts are only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).

InteractiveQuestion embeds an interactive chart or a query editor.

Property Type Description
className? string A custom class name to be added to the root element.
dataPicker? EmbeddingDataPicker Controls the menu for selecting data sources in questions. You can opt for the full data picker by setting dataPicker = "staged".
entityTypes? EmbeddingEntityType[] An array that specifies which entity types are available in the data picker
height? Height<string | number> A number or string specifying a CSS size value that specifies the height of the component
hiddenParameters? string[] A list of parameters to hide.
initialCollection? SdkCollectionId The collection to preselect in the save modal’s collection picker. Unlike targetCollection, the picker remains visible and the user can choose a different collection. Ignored when targetCollection is set.
initialSqlParameters? SqlParameterValues Initial values for SQL 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: 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).
isSaveEnabled? boolean Whether to show the save button.
onBeforeSave? (question: MetabaseQuestion | undefined, context: { isNewQuestion: boolean; }) => Promise<void> A callback function that triggers before saving. Only relevant when isSaveEnabled = true
onNavigateBack? () => void A callback function that triggers when a user clicks the back button.
onRun? (question: MetabaseQuestion | undefined) => void A callback function that triggers when a question is updated, including when a user clicks the Visualize button in the question editor
onSave? (question: MetabaseQuestion, context: { dashboardTabId?: number; isNewQuestion: boolean; }) => void A callback function that triggers when a user saves the question. Only relevant when isSaveEnabled = true
onSqlParametersChange? (payload: SqlParameterChangePayload) => void Fires on SQL 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? (display: | "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 the visualization type changes.
plugins? MetabasePluginsConfig -
query? undefined -
questionId? SdkQuestionId | null The ID of the question.
This is either:
- the numerical ID when accessing a question link, i.e. http://localhost:3000/question/1-my-question where the ID is 1
- the string ID found in the entity_id key of the question object when using the API directly or using the SDK Collection Browser to return data
- new to show the notebook editor for creating new questions
- new-native to show the SQL editor for creating new native questions
sqlParameters? SqlParameterValues Controlled SQL parameter values, slug-keyed. On every render, this object replaces the question’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 onSqlParametersChange to stay in sync with user edits.
style? CSSProperties A custom style object to be added to the root element.
targetCollection? SdkCollectionId The collection to save the question to. This will hide the collection picker from the save modal. Only applicable to interactive questions.
title? SdkQuestionTitleProps Determines whether the question title is displayed, and allows a custom title to be displayed instead of the default question title. Shown by default.
token? string | null A valid JWT token for the guest embed.
width? Width<string | number> A number or string specifying a CSS size value that specifies the width of the component
withAlerts? boolean Enables the ability to set up alerts on the question.
withChartTypeSelector? boolean Determines whether the chart type selector and corresponding settings button are shown. Only relevant when using the default layout.
withDownloads? boolean Enables the ability to download results in the question.
withEditorButton? boolean Determines whether the editor button is shown. Only relevant when using the default layout.

Customize the layout of an interactive chart

By default, InteractiveQuestion comes with a layout that lets people view the question, apply filters and aggregations, and use the query builder:

<InteractiveQuestion questionId={95} />

To build your own layout, use namespaced components inside InteractiveQuestion (like <InteractiveQuestion.Filter />):

<div
  className="App"
  style={{
    width: "100%",
    maxWidth: "1600px",
    height: "800px",
    margin: "0 auto",
  }}
>
  <MetabaseProvider authConfig={authConfig} theme={theme}>
    <InteractiveQuestion questionId={95}>
      <div
        style={{
          display: "flex",
          flexDirection: "column",
          alignItems: "center",
          justifyContent: "center",
          width: "100%",
        }}
      >
        <div style={{ display: "grid", placeItems: "center", width: "100%" }}>
          <InteractiveQuestion.Title />
          <InteractiveQuestion.ResetButton />
        </div>
        <div
          style={{
            display: "flex",
            alignItems: "center",
            justifyContent: "flex-start",
            overflow: "hidden",
            width: "100%",
          }}
        >
          <div style={{ width: "100%" }}>
            <InteractiveQuestion.QuestionVisualization />
          </div>
          <div style={{ display: "flex", flex: 1, overflow: "scroll" }}>
            <InteractiveQuestion.Summarize />
          </div>
        </div>
        <div
          style={{ display: "flex", flexDirection: "column", width: "100%" }}
        >
          <InteractiveQuestion.Filter />
        </div>
      </div>
    </InteractiveQuestion>
  </MetabaseProvider>
</div>

InteractiveQuestion components

These components are available via the InteractiveQuestion namespace (like <InteractiveQuestion.Filter />). Use them to customize the layout of an interactive question.

InteractiveQuestion.BackButton is deprecated. Use InteractiveQuestion.NavigationBackButton instead.

Further reading

Read docs for other versions of Metabase.

Was this helpful?

Thanks for your feedback!
Want to improve these docs? Propose a change.