Customize the appearance of your embeds

Style modular embeds with a theme. Pick light or dark mode, save reusable themes in Metabase, and set colors, fonts, and component options for web components or the React SDK.

A theme is an object that sets colors, fonts, and component options. Every embed configuration has one theme, and the theme applies to every embed that uses that configuration. The theme object is the same for web components and the React SDK, so every example on this page works with both.

There are three ways to set a theme:

  • Use a preset: Set preset to "light" or "dark". Available on all plans.
  • Save a theme: Save a theme in Embedding hub > Appearance, then select it in the embed wizard. The wizard copies your theme into the embed’s code. Available on Pro and Enterprise plans only.
  • Set options in code: Add options directly to your embed configuration. These values override the preset or saved theme. Available on Pro and Enterprise plans only.

For every option in the theme object, see Appearance reference.

Add a theme to your embeds

Set the theme in your shared embed configuration:

  • Web components: Add theme to defineMetabaseConfig().
  • React SDK: Create the theme with defineMetabaseTheme() and pass it to MetabaseProvider.

Web component theme

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase.example.com",
    theme: {
      colors: {
        brand: "#509EE3",
      },
    },
  });
</script>

React SDK theme

const theme = defineMetabaseTheme({
  colors: {
    brand: "#509EE3",
  },
});

return (
  <MetabaseProvider authConfig={authConfig} theme={theme}>
    {children}
  </MetabaseProvider>
);

The examples below show only the theme object.

Pick a light or dark theme

Embeds use the light theme by default. To switch to dark, set preset to "dark":

{
  preset: "dark", // or "light"
}

Presets are available on all plans. Any colors you set alongside a preset override that preset’s colors.

Save a theme in Metabase

Embedding hub > Appearance

Saved embedding themes are only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).

Embedding themes

A saved theme is a named set of colors and fonts that you set in Embedding hub > Appearance. When you select a saved theme in the embed wizard, the wizard copies it into the embed’s code.

Metabase includes a light and a dark theme that use the appearance settings of your Metabase. In the Themes section, you can:

  • Create a theme: Click New theme, then set a name, colors, and font.
  • Edit a theme: Click a theme card to open the editor. View your changes in the live preview.
  • Choose what the preview renders: Pick the dashboard or question the preview shows.
  • Duplicate a theme: Useful for varying an existing theme.
  • Delete a theme: Deleting is permanent.

Theme editor

Use Branding elements to set the loading message and the illustrations for empty results. These settings apply to your whole Metabase, not just embeds. Change them in the Embedding hub or in Admin > Settings > Appearance.

Apply a saved theme to a new embed

In the last step of the embed wizard, you can pick:

  • A saved theme from your list.
  • Instance theme to use your Metabase’s defaults.
  • Custom to set colors on this embed only, without saving a theme.

Embed wizard appearance

The wizard copies the theme’s values into the generated theme object. The generated code is a copy, not a reference to the saved theme. Editing or deleting the saved theme doesn’t change embeds you already generated. To apply changes, create a new embed in the wizard or edit the theme object in your code.

Apply a saved theme to an existing embed

To apply a saved theme to an embed you already generated, copy the theme’s values into your theme object. A saved theme has the same structure as the theme object:

{
  fontFamily: "Lato",
  colors: {
    brand: "#50E397",
    background: "#11123D",
    "text-primary": "#F9F9FC",
  },
}

Set colors and fonts

Custom themes are only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).

The theme editor sets colors and fonts. This section and the ones that follow describe the full theme object you set in code. The theme object includes more options than the editor, like chart colors, styles for individual components, and the z-index of overlays. It works without the wizard.

To change the colors and font of your embeds, set colors and fontFamily:

{
  fontFamily: "Inter",
  colors: {
    brand: "#9B5966",
    "text-primary": "#4C5773",
    background: "#FFFFFF",
    "background-hover": "#F9FBFC",
    border: "#EEECEC",
  },
}

Each color in colors accepts any CSS color string, but not a CSS variable. For fontFamily, use any font that Metabase supports, or "Custom" to use your instance’s custom font.

For the full list of colors, see Colors.

Set chart colors

Custom themes are only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).

To change the series colors in charts, set colors.charts. You can set up to eight colors. Each one is either a color string or an object with a base color, where tint and shade are optional lighter and darker variations:

{
  colors: {
    charts: [
      "#9B59B6",
      { base: "#E74C3C", tint: "#EE6B56", shade: "#CB4436" },
    ],
  },
}

If you set a custom series color in a chart’s visualization settings, that color overrides the theme.

Style individual components

Custom themes are only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).

To style specific components, like dashboard cards or data tables, set options under components:

{
  components: {
    dashboard: {
      backgroundColor: "#2F3640",
      card: {
        backgroundColor: "#2D2D30",
        border: "1px solid #EEECEC",
      },
    },
    table: {
      cell: {
        fontSize: "12.5px",
      },
    },
  },
}

For the full list of component options, see Component options.

Fix overlays hidden behind your app’s modals

Custom themes are only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).

Metabase overlays, like click-action menus and save dialogs, have a z-index of 200. If your app renders its own modal, drawer, or backdrop with a higher z-index, it hides the Metabase overlay.

To raise the Metabase overlay above your app’s overlay, set components.popover.zIndex:

{
  components: {
    popover: {
      zIndex: 1001, // one above your app's modal
    },
  },
}

Other appearance settings

The theme controls colors, fonts, and component styling. Other parts of an embed’s appearance are set elsewhere.

Further reading

Read docs for other versions of Metabase.