The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
docs - embed themes (#73409)
Jeff Bruemmer5558e1c152d8
diff --git a/docs/embedding/appearance.md b/docs/embedding/appearance.mdindex 17e1ddc9b18..d776ec4c957 100644--- a/docs/embedding/appearance.md+++ b/docs/embedding/appearance.md@@ -2,7 +2,7 @@title: "Customizing the appearance of modular embeds"summary: "Style your embedded Metabase components using themes to customize colors, backgrounds, and more."redirect_from:- - /docs/latest/embedding/sdk/appearance+- /docs/latest/embedding/sdk/appearance---# Customizing the appearance of modular embeds@@ -11,8 +11,12 @@ You can style your embedded [Metabase components](./components.md) with a **them-Guest embeds on OSS and Starter plans come with two theme presets - light and dark. On Metabase Pro and Enterprise plans, you can also customize individual colors, backgrounds, fonts and more. See [Advanced theming](#advanced-theming).+On OSS and Starter plans, embeds come with two theme presets: [light and dark](#dark-mode-and-light-mode).+On Pro and Enterprise plans, you can:++- [Save reusable themes](#embedding-themes), then pick one in the embed wizard.+- Customize individual colors, backgrounds, fonts, and more in your embedding code. See [Advanced theming](#advanced-theming).## Dark mode and light mode@@ -28,16 +32,84 @@ defineMetabaseConfig({});```+## Embedding themes++++{% include plans-blockquote.html feature="Saved embedding themes" is_plural=true %}++A theme is a named set of colors and fonts that the embed wizard can copy into each new embed's config. The embed doesn't reference the theme, the embed carries its own inlined copy of the values. Changing or deleting the theme won't affect existing embeds.++### Manage themes++Go to **Admin settings > Embedding > Themes**.++Metabase ships with light and dark themes that pick up any appearance settings you've set on your Metabase (though you can tinker with these default themes as well, including removing theme like you can any other custom theme).++From the Themes tab, 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. Changes show up in the live preview.+- **Choose what the preview renders.** Pick the dashboard or question used to preview the theme.+- **Duplicate a theme.** Handy if you want to vary an existing theme.+- **Delete a theme.** This deletion is eternal.++++### Apply a saved theme to a new embed++When you create a new embed using the [embed wizard](./modular-embedding.md#3-customize-your-embed), the last customization step lets you pick:++- **A saved theme** from your list of themes.+- **Instance theme** to use Metabase's instance defaults.+- **Custom** to set colors directly on this embed without saving them as a theme.++++The theme you pick is inlined into the generated `defineMetabaseConfig({ theme: ... })` snippet. Because each embed carries its _own_ copy of the values, editing or deleting the theme in Metabase won't change the themes in embeds that have already been generated. Those embeds keep the colors and fonts they were created with. To pick up theme changes in an existing embed, regenerate the snippet from the wizard, or edit the `theme` block in your code by hand.++### Reuse a saved theme in the SDK++If you're using the [SDK](./sdk/introduction.md), pass a theme to `MetabaseProvider` with `defineMetabaseTheme`, which accepts the same theme shape that you configure in the Themes admin UI. You can copy a saved theme's values into your code:++```tsx+import {+ MetabaseProvider,+ defineMetabaseTheme,+} from "@metabase/embedding-sdk-react";++const theme = defineMetabaseTheme({+ fontFamily: "Lato",+ colors: {+ brand: "#50e397",+ background: "#11123d",+ "text-primary": "#f9f9fc",+ },+});++export function App() {+ return (+ <MetabaseProvider authConfig={authConfig} theme={theme}>+ {/* your app */}+ </MetabaseProvider>+ );+}+```++For the full set of available colors and component overrides, see [Theme options](#theme-options).+## Advanced theming{% include plans-blockquote.html feature="Advanced theming modular embeds" is_plural=true %}-On Pro/Enterprise plan, you can configure granular appearance options, like background colors, font sizes etc. See the [list of all theming options]().+On Pro/Enterprise plan, you can configure granular appearance options, like background colors, font sizes etc. See the [list of all theming options](#theme-options).### Add an advanced theme to your embed+If you have a [saved theme](#embedding-themes), you can pick it directly in the embed wizard. The rest of this section covers further customization on top of (or instead of) a saved theme.+Some appearance options like brand, text, and background color are configurable in the [embed wizard](./modular-embedding.md#create-a-new-embed).For other appearance settings, use the `theme` parameter with `preset` in the `defineMetabaseConfig()` function in your [embedding code snippet](./modular-embedding.md#add-the-embedding-script-to-your-app). For example:diff --git a/docs/embedding/images/embed-wizard-appearance.png b/docs/embedding/images/embed-wizard-appearance.pngnew file mode 100644index 00000000000..412779cce5cBinary files /dev/null and b/docs/embedding/images/embed-wizard-appearance.png differdiff --git a/docs/embedding/images/theme-editor.png b/docs/embedding/images/theme-editor.pngnew file mode 100644index 00000000000..5dda4d4292bBinary files /dev/null and b/docs/embedding/images/theme-editor.png differdiff --git a/docs/embedding/images/themes.png b/docs/embedding/images/themes.pngnew file mode 100644index 00000000000..e193a4442deBinary files /dev/null and b/docs/embedding/images/themes.png differdiff --git a/docs/embedding/modular-embedding.md b/docs/embedding/modular-embedding.mdindex 72f188eb951..04a17f24462 100644--- a/docs/embedding/modular-embedding.md+++ b/docs/embedding/modular-embedding.md@@ -63,7 +63,13 @@ The exact customization options you see will depend on what type of entity you'r-If you are on Metabase OSS/Starter plans, you'll be able to select light or dark themes for your components. On Metabase Pro/Enterprise, you'll also be able to pick specific colors for brand, text, and background in the embed wizard, and add more customization options through [appearance settings](./appearance.md) later.+If you're on Metabase OSS/Starter plans, you can select light or dark themes for your components.++On Metabase Pro/Enterprise, you can also:++- Pick a [saved theme](./appearance.md#embedding-themes) you've created in **Admin settings > Embedding > Themes**.+- Pick specific colors for brand, text, and background in the embed wizard.+- Add more [advanced theme options](./appearance.md#advanced-theming) by editing the generated snippet later.All the customization options you select in this wizard will be reflected in the code snippet that the embed wizard will generate for you, and you'll be able to add more options later.diff --git a/docs/embedding/sdk/config.md b/docs/embedding/sdk/config.mdindex 02b416258f2..c8e27182e01 100644--- a/docs/embedding/sdk/config.md+++ b/docs/embedding/sdk/config.md@@ -15,6 +15,8 @@ To use the SDK in your app, you need to import the `MetabaseProvider` componentA 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](../appearance.md#reuse-a-saved-theme-in-the-sdk).+#### API Reference- [Component](./api/MetabaseProvider.html)diff --git a/frontend/src/metabase/admin/embedding/components/ThemeListing/EmbeddingThemeListingApp.tsx b/frontend/src/metabase/admin/embedding/components/ThemeListing/EmbeddingThemeListingApp.tsxindex 4032eb6e6d4..b9f730bf465 100644--- a/frontend/src/metabase/admin/embedding/components/ThemeListing/EmbeddingThemeListingApp.tsx+++ b/frontend/src/metabase/admin/embedding/components/ThemeListing/EmbeddingThemeListingApp.tsx@@ -58,7 +58,7 @@ function EmbeddingThemeListingAppInner() {<Stack gap="xs"><Title order={1}>{t`Themes`}</Title><Text c="text-secondary">- {t`Configure themes for Embedded Analytics JS and SDK for React`}+ {t`Create and edit themes to reuse across multiple embeds.`}</Text></Stack>