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 - config
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.
Passing a configuration object to MetabaseProvider
To use the SDK in your app, you need to import the MetabaseProvider
component and provide it with an authConfig
object.
MetabaseProvider
A component that configures the SDK and provides the Metabase SDK’s context and theme.
API Reference
Example
import React from "react";
import {
MetabaseProvider,
defineMetabaseAuthConfig,
defineMetabaseTheme,
} from "@metabase/embedding-sdk-react";
// Configure authentication
const authConfig = defineMetabaseAuthConfig({
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 = defineMetabaseTheme({
// 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
authConfig={authConfig}
theme={theme}
className="optional-class"
>
Hello World!
</MetabaseProvider>
);
}
Props
Property | Type | Description |
---|---|---|
allowConsoleLog? |
boolean |
Whether to allow logging to the DevTools console. Defaults to true. |
authConfig |
MetabaseAuthConfig |
Defines how to authenticate with Metabase. |
children |
ReactNode |
The children of the MetabaseProvider component. |
className? |
string |
A custom class name to be added to the root element. |
errorComponent? |
SdkErrorComponent |
A custom error component to display when the SDK encounters an error. |
eventHandlers? |
SdkEventHandlersConfig |
See Global event handlers. |
loaderComponent? |
() => Element |
A custom loader component to display while the SDK is loading. |
locale? |
string |
Defines the display language. Accepts an ISO language code such as en or de . Defaults to the instance locale. |
pluginsConfig? |
MetabasePluginsConfig |
See Plugins. |
theme? |
MetabaseTheme |
See Appearance. |
Global event handlers
You can listen for events by defining the eventHandlers
prop for MetabaseProvider
.
SdkEventHandlersConfig
Accepts an object where each key is an event type and the corresponding value is the event handler function.
API Reference
Example
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 authConfig={authConfig} eventHandlers={eventHandlers}>
{children}
</MetabaseProvider>
);
Props
Property | Type | Description |
---|---|---|
onDashboardLoad? |
SdkDashboardLoadEvent |
Triggers when a dashboard loads with all visible cards and their content |
onDashboardLoadWithoutCards? |
SdkDashboardLoadEvent |
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. |
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.