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.51.
Embedded analytics SDK - config
⚠️ This feature is in beta. Feel free to play around with it, but be aware that things might change (and may not work as expected).
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.
To use the SDK in your app, you need to import the MetabaseProvider component and provide it with a config object, like so:
const config = defineEmbeddingSdkConfig({
metabaseInstanceUrl: "https://metabase.example.com", // Required: Your Metabase instance URL
authProviderUri: "https://app.example.com/sso/metabase", // Required: An endpoint in your app that signs the user in and returns a session
});
export default function App() {
return (
<MetabaseProvider config={config} theme={theme} className="optional-class">
Hello World!
</MetabaseProvider>
);
}
You can also pass additional objects to MetabaseProvider:
config(Required). Includes information about your Metabase.theme(Optional) See Appearance.pluginsConfig(Optional). See Plugins.eventHandlers(Optional). See Global event handlers.
Example config object passed to MetabaseProvider
import React from "react";
import {
MetabaseProvider,
defineEmbeddingSdkConfig,
defineEmbeddingSdkTheme,
} from "@metabase/embedding-sdk-react";
// Configuration
const config = defineEmbeddingSdkConfig({
metabaseInstanceUrl: "https://metabase.example.com", // Required: Your Metabase instance URL
authProviderUri: "https://app.example.com/sso/metabase", // Required: An endpoint in your app that signs the user in and returns a session
});
// See the "Customizing appearance" section for more information
const theme = defineEmbeddingSdkTheme({
// Optional: Specify a font to use from the set of fonts supported by Metabase
fontFamily: "Lato",
// Optional: Match your application's color scheme
colors: {
brand: "#9B5966",
"text-primary": "#4C5773",
"text-secondary": "#696E7B",
"text-tertiary": "#949AAB",
},
});
export default function App() {
return (
<MetabaseProvider config={config} theme={theme} className="optional-class">
Hello World!
</MetabaseProvider>
);
}
Global event handlers
MetabaseProvider also supports eventHandlers.
Currently, we support:
onDashboardLoad?: (dashboard: Dashboard | null) => void;. Triggers when a dashboard loads with all visible cards and their contentonDashboardLoadWithoutCards?: (dashboard: Dashboard | null) => void;. Triggers after a dashboard loads, but without its cards (at this stage only the dashboard title, tabs, and cards grid are rendered, but the contents of the cards have yet to load.
const handleDashboardLoad: SdkDashboardLoadEvent = dashboard => {
/* do whatever you need to do - e.g. send analytics events, show notifications */
};
const eventHandlers = {
onDashboardLoad: handleDashboardLoad,
onDashboardLoadWithoutCards: handleDashboardLoad,
};
return (
<MetabaseProvider config={config} eventHandlers={eventHandlers}>
{children}
</MetabaseProvider>
);
Reloading Metabase components
In case you need to reload a Metabase component, for example, your users modify your application data and that data is used to render a question in Metabase. If you embed this question and want to force Metabase to reload the question to show the latest data, you can do so by using the key prop to force a component to reload.
// Inside your application component
const [data, setData] = useState({});
// This is used to force reloading Metabase components
const [counter, setCounter] = useState(0);
// This ensures we only change the `data` reference when it's actually changed
const handleDataChange = newData => {
setData(prevData => {
if (isEqual(prevData, newData)) {
return prevData;
}
return newData;
});
};
useEffect(() => {
/**
* When you set `data` as the `useEffect` hook's dependency, it will trigger the effect
* and increment the counter which is used in a Metabase component's `key` prop, forcing it to reload.
*/
if (data) {
setCounter(counter => counter + 1);
}
}, [data]);
return <InteractiveQuestion key={counter} questionId={yourQuestionId} />;
Read docs for other versions of Metabase.