Customize loading, error, and empty states

While an embedded component is loading, when it fails, or when a query comes back with no rows, the modular embedding SDK renders a screen of its own. You can swap in your own React components and images instead, so all three states match the rest of your app.

These customizations are SDK only. loaderComponent and errorComponent are props on MetabaseProvider, the no-results image comes from a plugin, and there’s no web component equivalent for any of them.

Replace the loading and error components

Pass loaderComponent and errorComponent to MetabaseProvider. Every embedded component inside that provider picks them up.

import {
  MetabaseProvider,
  StaticDashboard,
} from "@metabase/embedding-sdk-react";

<MetabaseProvider
  loaderComponent={() => <div>Analytics is loading...</div>}
  errorComponent={({ type, message, onClose }) => {
    switch (type) {
      case "fixed":
        return (
          <div style={{ position: "fixed", left: 0, right: 0, bottom: 0 }}>
            There was an error: {message}. <span onClick={onClose}>X</span>
          </div>
        );
      case "relative":
      default:
        return <div>There was an error: {message}</div>;
    }
  }}
>
  <StaticDashboard dashboardId={1} />
</MetabaseProvider>

loaderComponent receives an optional label prop with the loading message, which you can render or ignore. errorComponent receives the error details, so you can decide how much of the error to show, and where to put it.

Error component props

These are the props Metabase passes to your errorComponent. The type prop tells you how Metabase intended to display the error: relative errors sit in the flow of the component, while fixed errors are meant to overlay the page, like a toast.

Replace the no-results illustration

By default, Metabase displays a sailboat image when a query returns no results. To use a different image, set the getNoDataIllustration and getNoObjectIllustration plugins.

Unlike loaderComponent and errorComponent, these are plugins, so they go in pluginsConfig rather than being props of their own. And instead of a React component, each one returns a base64-encoded image:

const img_base64 = "..."; // base64-encoded image

const plugins = {
  getNoDataIllustration: () => img_base64,
  getNoObjectIllustration: () => img_base64,
};

return (
  <MetabaseProvider authConfig={authConfig} pluginsConfig={plugins}>
    <InteractiveDashboard dashboardId={1} />
  </MetabaseProvider>
);

getNoDataIllustration covers a query that came back with no rows. getNoObjectIllustration covers a search that turned up nothing, like a search page or an entity picker with no matches. Both can only be set globally, on the provider.

Further reading

• Modular embedding SDK plugins
• Appearance
• Modular embedding SDK config
• Modular embedding components