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.