Modular embedding SDK - config

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.

To pass a theme, use defineMetabaseTheme. See Reuse a saved theme in the SDK.

API Reference

• Component
• Props

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
});

// 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

Custom visualizations

The SDK can render custom visualizations. To allow custom visualizations in the embed, pass an allowlist of the custom visualizations to the allowedCustomVisualizations prop on MetabaseProvider:

<MetabaseProvider
  authConfig={authConfig}
  // Allowlist the custom visualizations to load, by their names,
  // each prefixed with `custom:`.
  allowedCustomVisualizations={["custom:Calendar Heatmap", "custom:Thumbs"]}
>
  {children}
</MetabaseProvider>

Only the custom visualizations you list will load. Each entry is the visualization’s name (the manifest name, which you can find under Admin > Settings > Custom visualizations > Manage visualizations), prefixed with custom:. For example, a custom visualization named Calendar Heatmap becomes "custom:Calendar Heatmap". Names are case-sensitive, so "custom:calendar heatmap" won’t match a visualization named Calendar Heatmap.

Omitting the prop, or passing an empty array, turns off custom visualizations. Cards that use a custom visualization will fall back to the default visualization for the query’s results. If you allowlist a name that doesn’t match an installed custom visualization, the SDK logs a warning to the console and falls back to the default visualization.

For security, the SDK runs each custom visualization’s code in an isolated sandbox, so a visualization can’t reach your app or make network requests. The sandbox doesn’t block passive image loads, though. A visualization can still trigger outbound requests through <img> tags or CSS url(). To limit where custom visualizations can load images from, set a Content Security Policy with an img-src allowlist in your app (the core Metabase app does this with Restrict image domains). Only add visualizations you trust.

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

• Type

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

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} />;