These are the docs for the Metabase master branch. Some features documented here may not yet be available in the latest release. Check out the docs for the latest version, Metabase v0.54.
Embedded analytics SDK - dashboards
Embedded analytics SDK is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud). You can, however, play around with the SDK on your local machine without a license by using API keys to authenticate your embeds.
You can embed an interactive, editable, or static dashboard.
Please keep in mind - embedding multiple instances of dashboards on the same page is not yet supported.
Embedding a dashboard
You can embed a dashboard using the one of the dashboard components:
StaticDashboard
A lightweight dashboard component. Use this component when you want to display results without letting people interact with the data.
API Reference
Props
Property | Type | Description |
---|---|---|
className? |
string |
A custom class name to be added to the root element. |
dashboardId |
SdkDashboardId |
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 |
hiddenParameters? |
string [] |
A list of parameters to hide. Remarks - 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? |
DefaultQuery <string > |
Query parameters for the dashboard. For a single option, use a string value, and use a list of strings for multiple options. Remarks - 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 : null | MetabaseDashboard ) => void |
Callback that is called when the dashboard is loaded. |
onLoadWithoutCards? |
(dashboard : null | MetabaseDashboard ) => void |
Callback that is called when the dashboard is loaded without cards. |
style? |
CSSProperties |
A custom style object to be added to the root element. |
withCardTitle? |
boolean |
Whether the dashboard cards should display a title. |
withDownloads? |
boolean |
Whether to hide the download button. |
withFooter? |
boolean |
Whether to display the footer. |
withTitle? |
boolean |
Whether the dashboard should display a title. |
InteractiveDashboard
A dashboard component with drill downs, click behaviors, and the ability to view and click into questions. Use this component when you want to allow people to explore their data.
API Reference
Props
Property | Type | Description |
---|---|---|
className? |
string |
A custom class name to be added to the root element. |
dashboardId |
SdkDashboardId |
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 |
drillThroughQuestionHeight? |
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. |
hiddenParameters? |
string [] |
A list of parameters to hide. Remarks - 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? |
DefaultQuery <string > |
Query parameters for the dashboard. For a single option, use a string value, and use a list of strings for multiple options. Remarks - 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 : null | MetabaseDashboard ) => void |
Callback that is called when the dashboard is loaded. |
onLoadWithoutCards? |
(dashboard : null | MetabaseDashboard ) => void |
Callback that is called when the dashboard is loaded without cards. |
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. |
withCardTitle? |
boolean |
Whether the dashboard cards should display a title. |
withDownloads? |
boolean |
Whether to hide the download button. |
withFooter? |
boolean |
Whether to display the footer. |
withTitle? |
boolean |
Whether the dashboard should display a title. |
EditableDashboard
A dashboard component with the features available in the InteractiveDashboard
component, as well as the ability to add and update questions, layout, and content within your dashboard. Use this component when you want to give people the ability to modify your dashboards, for example in an admin panel in your app.
API Reference
Props
Property | Type | Description |
---|---|---|
className? |
string |
A custom class name to be added to the root element. |
dashboardId |
SdkDashboardId |
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 |
drillThroughQuestionHeight? |
number |
Height of a question component when drilled from the dashboard to a question level. |
drillThroughQuestionProps? |
DrillThroughQuestionProps |
Props for the drill-through question |
initialParameters? |
DefaultQuery <string > |
Query parameters for the dashboard. For a single option, use a string value, and use a list of strings for multiple options. Remarks - 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 : null | MetabaseDashboard ) => void |
Callback that is called when the dashboard is loaded. |
onLoadWithoutCards? |
(dashboard : null | MetabaseDashboard ) => void |
Callback that is called when the dashboard is loaded without cards. |
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. |
withCardTitle? |
boolean |
Whether the dashboard cards should display a title. |
withDownloads? |
boolean |
Whether to hide the download button. |
withFooter? |
boolean |
Whether to display the footer. |
Example embedded dashboard with InteractiveDashboard
component
import React from "react";
import {
InteractiveDashboard,
MetabaseProvider,
defineMetabaseAuthConfig,
} from "@metabase/embedding-sdk-react";
const authConfig = defineMetabaseAuthConfig({
metabaseInstanceUrl: "https://your-metabase.example.com",
authProviderUri: "https://your-app.example.com/sso/metabase",
});
export default function App() {
const dashboardId = 1; // This is the dashboard ID you want to embed
const initialParameters = {}; // Define your query parameters here
// choose parameter names that are in your dashboard
const hiddenParameters = ["location", "city"];
return (
<MetabaseProvider authConfig={authConfig}>
<InteractiveDashboard
dashboardId={dashboardId}
initialParameters={initialParameters}
withTitle={false}
withDownloads={false}
hiddenParameters={hiddenParameters}
/>
</MetabaseProvider>
);
}
Customizing dashboard height
By default, dashboard components take full page height (100vh). You can override this with custom styles passed via style
or className
props.
<EditableDashboard
style={{
height: 800,
minHeight: "auto",
}}
dashboardId={dashboardId}
/>
Customizing drill-through question layout
When drilling through or clicking on a question card in the dashboard, you will be taken to the question view. By default, the question is shown in the default layout for interactive questions.
To customize the question layout, pass a renderDrillThroughQuestion
prop to the InteractiveDashboard
component, with the custom view as the child component.
<InteractiveDashboard
dashboardId={95}
renderDrillThroughQuestion={QuestionView}
/>
// You can use namespaced components to build the question's layout.
const QuestionView = () => <InteractiveQuestion.Title />;
The questionView prop accepts a React component that will be rendered in the question view, which you can build with namespaced components within the InteractiveQuestion
component. See customizing interactive questions for an example layout.
Dashboard plugins
dashboardCardMenu
This plugin allows you to add, remove, and modify the custom actions on the overflow menu of dashboard cards. The plugin appears as a dropdown menu on the top right corner of the card.
The plugin’s default configuration looks like this:
const plugins = {
dashboard: {
dashboardCardMenu: {
withDownloads: true,
withEditLink: true,
customItems: [],
},
},
};
dashboardCardMenu
: can be used in the InteractiveDashboard like this:
<InteractiveDashboard
dashboardId={1}
plugins={{
dashboard: {
dashboardCardMenu: () => null,
},
}}
/>
Enabling/disabling default actions
To remove the download button from the dashcard menu, set withDownloads
to false
. To remove the edit link from the dashcard menu, set withEditLink
to false
.
const plugins = {
dashboard: {
dashboardCardMenu: {
withDownloads: false,
withEditLink: false,
customItems: [],
},
},
};
Adding custom actions to the existing menu:
You can add custom actions to the dashcard menu by adding an object to the customItems
array. Each element can either be an object or a function that takes in the dashcard’s question, and outputs a list of custom items in the form of:
type DashCardMenuItem = {
iconName: string;
label: string;
onClick: () => void;
disabled?: boolean;
};
Here’s an example:
const plugins: MetabasePluginsConfig = {
dashboard: {
dashboardCardMenu: {
customItems: [
{
iconName: "chevronright",
label: "Custom action",
onClick: () => {
alert(`Custom action clicked`);
},
},
({ question }) => {
return {
iconName: "chevronright",
label: "Custom action",
onClick: () => {
alert(`Custom action clicked ${question?.name}`);
},
};
},
],
},
},
};
Replacing the existing menu with your own component
If you want to replace the existing menu with your own component, you can do so by providing a function that returns a React component. This function also can receive the question as an argument.
const plugins: MetabasePluginsConfig = {
dashboard: {
dashboardCardMenu: ({ question }) => (
<button onClick={() => console.log(question.name)}>Click me</button>
),
},
};
Creating dashboards
Creating a dashboard could be done with useCreateDashboardApi
hook or CreateDashboardModal
component.
useCreateDashboardApi
Use this hook if you’d like to have total control over the UI and settings.
API Reference
Example
const { createDashboard } = useCreateDashboardApi();
const handleDashboardCreate = async () => {
const dashboard = await createDashboard(options);
// do something with created empty dashboard, e.g., use the dashboard in EditableDashboard component
};
return <button onClick={handleDashboardCreate}>Create new dashboard</button>;
Options
Property | Type | Description |
---|---|---|
collectionId |
SdkCollectionId |
Collection in which to create a new dashboard. You can use predefined system values like root or personal . |
description |
null | string |
Dashboard description |
name |
string |
Dashboard title |
CreateDashboardModal
API Refernce
Example
const [dashboard, setDashboard] = useState<MetabaseDashboard | null>(null);
if (dashboard) {
return <EditableDashboard dashboardId={dashboard.id} />;
}
return <CreateDashboardModal onClose={handleClose} onCreate={setDashboard} />;
Props
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. |
Read docs for other versions of Metabase.