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
presetto"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
themetodefineMetabaseConfig(). - React SDK: Create the theme with
defineMetabaseTheme()and pass it toMetabaseProvider.
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).

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.

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.

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.
- Titles, download buttons, and card menus: Set these on each component. See Customize dashboard appearance and Customize chart appearance.
- Query builder layout (React SDK): Build your own layout from the
InteractiveQuestionnamespaced components. See Customize the query builder’s layout. - Loading and error screens (React SDK): Replace them with your own components. See Customize loading and error states.
- Custom visualizations: Render your own chart types in embeds. See Custom visualizations in embeds.
- Logo, favicon, and custom font: Set these for your whole Metabase in Admin > Settings > Appearance. See Appearance settings.
Further reading
Read docs for other versions of Metabase.