MetabaseProvider

The MetabaseProvider component wraps your application and provides context for all Metabase SDK components

The MetabaseProvider component is the root component for the Metabase Embedding SDK. It provides authentication, theming, and configuration context to all child components.

Basic usage

import { MetabaseProvider } from '@metabase/embedding-sdk-react';

const authConfig = {
  metabaseInstanceUrl: 'https://metabase.example.com',
  jwtProviderUri: 'https://your-api.example.com/sso/metabase',
};

function App() {
  return (
    <MetabaseProvider authConfig={authConfig}>
      {/* Your app components */}
    </MetabaseProvider>
  );
}

Usage with theme

import { MetabaseProvider, defineMetabaseTheme } from '@metabase/embedding-sdk-react';

const theme = defineMetabaseTheme({
  colors: {
    brand: '#9333EA',
    'text-primary': '#1F2937',
  },
  fontFamily: 'Inter, sans-serif',
});

function App() {
  return (
    <MetabaseProvider authConfig={authConfig} theme={theme}>
      {/* Your app components */}
    </MetabaseProvider>
  );
}

Usage with event handlers

import { MetabaseProvider } from '@metabase/embedding-sdk-react';

const eventHandlers = {
  onDashboardLoad: (dashboard) => {
    console.log('Dashboard loaded:', dashboard.name);
    // Track analytics, update UI, etc.
  },
};

function App() {
  return (
    <MetabaseProvider authConfig={authConfig} eventHandlers={eventHandlers}>
      {/* Your app components */}
    </MetabaseProvider>
  );
}

Usage with plugins

import { MetabaseProvider } from '@metabase/embedding-sdk-react';

const pluginsConfig = {
  mapQuestionClickActions: (clickActions, clickedDataPoint) => {
    // Add a custom click action
    return [
      ...clickActions,
      {
        name: 'view-details',
        onClick: () => {
          console.log('Clicked data:', clickedDataPoint);
        },
      },
    ];
  },
  handleLink: (url) => {
    // Custom link handling (e.g., React Router navigation)
    if (url.startsWith('/dashboard/')) {
      navigate(url);
      return { handled: true };
    }
    return { handled: false };
  },
};

function App() {
  return (
    <MetabaseProvider authConfig={authConfig} pluginsConfig={pluginsConfig}>
      {/* Your app components */}
    </MetabaseProvider>
  );
}

Complete example with all options

import { MetabaseProvider, defineMetabaseTheme } from '@metabase/embedding-sdk-react';

const authConfig = {
  metabaseInstanceUrl: 'https://metabase.example.com',
  jwtProviderUri: 'https://your-api.example.com/sso/metabase',
};

const theme = defineMetabaseTheme({
  colors: {
    brand: '#9333EA',
  },
});

const pluginsConfig = {
  handleLink: (url) => {
    navigate(url);
    return { handled: true };
  },
};

const eventHandlers = {
  onDashboardLoad: (dashboard) => {
    console.log('Dashboard loaded:', dashboard);
  },
};

const CustomLoader = ({ label }) => (
  <div className="loading">
    <Spinner />
    {label && <span>{label}</span>}
  </div>
);

const CustomError = ({ message }) => (
  <div className="error">
    <h2>Error</h2>
    <p>{message}</p>
  </div>
);

function App() {
  return (
    <MetabaseProvider
      authConfig={authConfig}
      theme={theme}
      pluginsConfig={pluginsConfig}
      eventHandlers={eventHandlers}
      locale="en"
      loaderComponent={CustomLoader}
      errorComponent={CustomError}
      allowConsoleLog={true}
    >
      {/* Your app components */}
    </MetabaseProvider>
  );
}

Props

authConfig · MetabaseAuthConfig · required

Configuration for authenticating with your Metabase instance.

Show authConfig properties

metabaseInstanceUrl · string · required

The URL of your Metabase instance (e.g., https://metabase.example.com).

jwtProviderUri · string

URI of the JWT provider. If provided, the SDK will use JWT authentication.

fetchRequestToken · MetabaseFetchRequestTokenFn

Custom function to fetch the JWT refresh token.

preferredAuthMethod · 'jwt' | 'saml'

Preferred authentication method when both JWT and SAML are enabled.

apiKey · string

API key for authentication. For development only.

isGuest · boolean

Whether to work in Guest Embed mode.

theme · MetabaseEmbeddingTheme

Theme configuration to customize the appearance of embedded components. See theming for details.

pluginsConfig · MetabaseGlobalPluginsConfig

Plugin configuration for customizing behavior.

Show pluginsConfig properties

mapQuestionClickActions · (clickActions, clickedDataPoint) => MetabaseClickAction[] | { onClick: () => void }

Function to filter or modify click actions on question visualizations.

dashboard.dashboardCardMenu · DashboardCardMenu

Custom dashboard card menu configuration.

handleLink · (url: string) => { handled: boolean }

Function to handle link clicks within embedded components.

getNoDataIllustration · () => string | null

Function returning a base64-encoded image string for the no-data state.

getNoObjectIllustration · () => string | null

Function returning a base64-encoded image string for the no-object state.

eventHandlers · SdkEventHandlersConfig

Global event handlers.

Show eventHandlers properties

onDashboardLoad · (dashboard: MetabaseDashboard | null) => void

Triggered when a dashboard loads with all visible cards and their content.

onDashboardLoadWithoutCards · (dashboard: MetabaseDashboard | null) => void

Triggered after a dashboard loads, but without its cards (only the dashboard title, tabs, and cards grid are rendered).

locale · string

Display language as an ISO language code (e.g., en, de, fr). Defaults to the instance locale.

loaderComponent · React.ComponentType<{ label?: string }>

Custom loader component to display while the SDK is loading. The component receives an optional label prop.

errorComponent · SdkErrorComponent

Custom error component to display when the SDK encounters an error.

allowConsoleLog · boolean · default: "true"

Whether to allow logging to the DevTools console.

children · ReactNode · required

Your application components that will have access to the Metabase SDK context.

Important notes

Ensure only one instance of MetabaseProvider is rendered at a time. Multiple instances may cause unexpected behavior.

The MetabaseProvider must be an ancestor of all Metabase SDK components in your component tree.

TypeScript types

import type {
  MetabaseProviderProps,
  MetabaseAuthConfig,
  MetabaseAuthConfigWithJwt,
  MetabaseAuthConfigWithSaml,
  MetabaseAuthConfigWithApiKey,
  MetabaseIsGuestAuthConfig,
} from '@metabase/embedding-sdk-react';

Related

• Configuration - Detailed configuration guide
• Theming - Theme customization
• Event handlers - Working with events