Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs - custom viz sdk (#77974)

Jeff Bruemmereb8d806ffe17
diff --git a/docs/developers-guide/custom-visualizations.md b/docs/developers-guide/custom-visualizations.md
index 342e9599f59..3923473967d 100644
--- a/docs/developers-guide/custom-visualizations.md
+++ b/docs/developers-guide/custom-visualizations.md
@@ -268,7 +268,7 @@ settings: {
| `group` | Sub-heading within a section for grouping related settings. |
| `index` | Display order within a group. |
| `inline` | When `true`, renders the widget on the same line as `title` (handy for `"toggle"`). |
-| `widget` | A [built-in widget](#built-in-widgets) name, or a [custom React component](#custom-widgets). |
+| `widget` | A [built-in widget](#built-in-widgets) name, or a [custom React component](#custom-widgets). |
| `getDefault(series, settings)` | Computes the default value when none is stored. |
| `getValue(series, settings)` | Always-computed value — overrides the stored value on every render. |
| `getProps(series, settings)` | Returns widget-specific props. |
@@ -417,13 +417,15 @@ Metabase runs plugin code in an isolated sandbox, so a visualization works only
- **Navigation and the rest of the app**: history changes, the host page's URL and referrer, and any DOM outside the plugin's own container.
- **Unsafe DOM and timing APIs**: `document.write`, `execCommand`, constructable stylesheets, raw HTML parsers (`DOMParser`, `setHTMLUnsafe`, `XSLTProcessor`), and resource-timing APIs that expose other requests the page has made.
-### Custom visualizations don't render in embeds or public links
+### When embedding, custom visualizations are only available in the SDK
-[Embeds](../embedding/introduction.md) and [public links](../embedding/public-links.md) (to questions, dashboards, and documents) don't render custom visualizations. Any card that uses one falls back to the default visualization (a table).
+The [Modular embedding SDK](../embedding/sdk/introduction.md) renders custom visualizations when you allowlist them with the [`allowedCustomVisualizations` prop](../embedding/sdk/config.md#custom-visualizations) on `MetabaseProvider`.
+
+Other embedding types don't render custom visualizations. In [modular embedding](../embedding/modular-embedding.md) with web components and [public links](../embedding/public-links.md), any card that uses a custom visualization falls back to the default visualization for the query's results.
### Custom visualizations don't render in exports and subscriptions
-Static renders—like charts in alerts or dashboard subscriptions—fall back to a table for any card that uses a custom visualization.
+Static renders—like charts in alerts or dashboard subscriptions—fall back to a default visualization for the card's data shape.
## Example plugins
diff --git a/docs/embedding/introduction.md b/docs/embedding/introduction.md
index ba5f93a9e6a..17205caaba4 100644
--- a/docs/embedding/introduction.md
+++ b/docs/embedding/introduction.md
@@ -60,23 +60,24 @@ If you'd like to share your data with the good people of the internet, admins ca
## Comparison of embedding types
-| Action | [Modular SDK](./sdk/introduction.md) | [Modular SSO](./modular-embedding.md) | [Modular Guest](./guest-embedding.md) | [Full app](./full-app-embedding.md) | [Public](../embedding/public-links.md) |
-| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------- | ------------------------------------- | ----------------------------------- | -------------------------------------- |
-| Charts and dashboards | ✅ | ✅ | ✅ | ✅ | ✅ |
-| [Filter widgets](https://www.metabase.com/glossary/filter-widget) | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Export results\* | ✅ | ✅ | ✅ | ✅ | ✅ |
-| [Locked filters](./static-embedding-parameters.md#restricting-data-in-a-static-embed-with-locked-parameters) | ❌ | ❌ | ✅ | ❌ | ❌ |
-| [Data segregation](../permissions/embedding.md) | ✅ | ✅ | ❌ | ✅ | ❌ |
-| [Drill-through menu](../questions/visualizations/drill-through.md) | ✅ | ✅ | ❌ | ✅ | ❌ |
-| [Query builder](../questions/query-builder/editor.md) | ✅ | ✅ | ❌ | ✅ | ❌ |
-| [Basic appearance customization](../configuring-metabase/appearance.md)\*\* | ✅ | ✅ | ✅ | ✅ | ✅ |
-| [Advanced theming](./appearance.md) | ✅ | ✅ | ❌ | ❌ | ❌ |
-| [Usage analytics](../usage-and-performance-tools/usage-analytics.md) | ✅ | ✅ | ❌ | ✅ | ❌ |
-| Embed individual Metabase components | ✅ | ✅ | ❌ | ❌ | ❌ |
-| Manage access and interactivity per component | ✅ | ✅ | ❌ | ❌ | ❌ |
-| Custom layouts | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Customize behavior with [plugins](./sdk/plugins.md) | ✅ | ❌ | ❌ | ❌ | ❌ |
-| AI chat | ✅ | ✅ | ❌ | ✅ | ❌ |
+| Action | [Modular SDK](./sdk/introduction.md) | [Modular SSO](./modular-embedding.md) | [Modular Guest](./guest-embedding.md) | [Full app](./full-app-embedding.md) | [Public](../embedding/public-links.md) |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------------- | ------------------------------------- | ----------------------------------- | -------------------------------------- |
+| Charts and dashboards | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [Filter widgets](https://www.metabase.com/glossary/filter-widget) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Export results\* | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [Locked filters](./static-embedding-parameters.md#restricting-data-in-a-static-embed-with-locked-parameters) | ❌ | ❌ | ✅ | ❌ | ❌ |
+| [Data segregation](../permissions/embedding.md) | ✅ | ✅ | ❌ | ✅ | ❌ |
+| [Drill-through menu](../questions/visualizations/drill-through.md) | ✅ | ✅ | ❌ | ✅ | ❌ |
+| [Query builder](../questions/query-builder/editor.md) | ✅ | ✅ | ❌ | ✅ | ❌ |
+| [Basic appearance customization](../configuring-metabase/appearance.md)\*\* | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [Advanced theming](./appearance.md) | ✅ | ✅ | ❌ | ❌ | ❌ |
+| [Usage analytics](../usage-and-performance-tools/usage-analytics.md) | ✅ | ✅ | ❌ | ✅ | ❌ |
+| Embed individual Metabase components | ✅ | ✅ | ❌ | ❌ | ❌ |
+| Manage access and interactivity per component | ✅ | ✅ | ❌ | ❌ | ❌ |
+| Custom layouts | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Customize behavior with [plugins](./sdk/plugins.md) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| [Custom visualizations](../questions/visualizations/custom.md) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| AI chat | ✅ | ✅ | ❌ | ✅ | ❌ |
\* Each embedding type allows data downloads by default, but only [Pro and Enterprise](https://www.metabase.com/pricing/) plans can disable data downloads.
@@ -103,7 +104,7 @@ For information about the anonymous usage data Metabase collects from embedded c
## Embedding limitations
- Currently, you can't embed [documents](../documents/introduction.md) (though you can create [public documents](./public-links.md)).
-- Embeds don't render [custom visualizations](../questions/visualizations/custom.md): any card that uses one falls back to the default visualization (a table).
+- Only the [Modular embedding SDK](./sdk/introduction.md) renders [custom visualizations](../questions/visualizations/custom.md), and only ones you allowlist with the [`allowedCustomVisualizations` prop](./sdk/config.md#custom-visualizations). In other embedding types, any card that uses a custom visualization falls back to the default visualization for the query's results.
## Further reading
diff --git a/docs/embedding/sdk/config.md b/docs/embedding/sdk/config.md
index c8e27182e01..4921769216e 100644
--- a/docs/embedding/sdk/config.md
+++ b/docs/embedding/sdk/config.md
@@ -32,6 +32,21 @@ To pass a theme, use `defineMetabaseTheme`. See [Reuse a saved theme in the SDK]
{% include_file "{{ dirname }}/api/snippets/MetabaseProviderProps.md" snippet="properties" %}
+## Custom visualizations
+
+The SDK can render [custom visualizations](../../questions/visualizations/custom.md). To allow custom visualizations in the embed, pass an allowlist of the custom visualizations to the `allowedCustomVisualizations` prop on `MetabaseProvider`:
+
+```typescript
+{% include_file "{{ dirname }}/snippets/config/config-with-custom-visualizations.tsx" snippet="example" %}
+```
+
+Only the custom visualizations you list will load. Each entry is the visualization's name (the manifest `name`, which you can find under **Admin** > **Settings** > **Custom visualizations** > **Manage visualizations**), prefixed with `custom:`. For example, a custom visualization named `Calendar Heatmap` becomes `"custom:Calendar Heatmap"`. Names are case-sensitive, so `"custom:calendar heatmap"` won't match a visualization named `Calendar Heatmap`.
+
+Omitting the prop, or passing an empty array, turns off custom visualizations. Cards that use a custom visualization will fall back to the default visualization for the query's results. If you allowlist a name that doesn't match an installed custom visualization, the SDK logs a warning to the console and falls back to the default visualization.
+
+
+For security, the SDK runs each custom visualization's code in an isolated sandbox, so a visualization can't reach your app or make network requests. The sandbox doesn't block passive image loads, though. A visualization can still trigger outbound requests through `<img>` tags or CSS `url()`. To limit where custom visualizations can load images from, set a Content Security Policy with an `img-src` allowlist in your app (the core Metabase app does this with [Restrict image domains](../../configuring-metabase/settings.md#restrict-image-domains)). [Only add visualizations you trust](../../questions/visualizations/custom.md#only-add-visualizations-you-trust).
+
## Global event handlers
You can listen for events by defining the `eventHandlers` prop for `MetabaseProvider`.
diff --git a/docs/embedding/sdk/snippets/config/config-with-custom-visualizations.tsx b/docs/embedding/sdk/snippets/config/config-with-custom-visualizations.tsx
new file mode 100644
index 00000000000..eda95fe2444
--- /dev/null
+++ b/docs/embedding/sdk/snippets/config/config-with-custom-visualizations.tsx
@@ -0,0 +1,20 @@
+import type { PropsWithChildren } from "react";
+import {
+ type MetabaseAuthConfig,
+ MetabaseProvider,
+} from "@metabase/embedding-sdk-react";
+
+const authConfig = {} as MetabaseAuthConfig;
+
+const Example = ({ children }: PropsWithChildren) => (
+ // [<snippet example>]
+ <MetabaseProvider
+ authConfig={authConfig}
+ // Allowlist the custom visualizations to load, by their names,
+ // each prefixed with `custom:`.
+ allowedCustomVisualizations={["custom:Calendar Heatmap", "custom:Thumbs"]}
+ >
+ {children}
+ </MetabaseProvider>
+ // [<endsnippet example>]
+);
diff --git a/docs/questions/visualizations/custom.md b/docs/questions/visualizations/custom.md
index c29012556f5..cb1b5a593c6 100644
--- a/docs/questions/visualizations/custom.md
+++ b/docs/questions/visualizations/custom.md
@@ -1,6 +1,6 @@
---
title: Custom visualizations
-summary: Add your own chart types to Metabase by uploading visualization plugins built with the Custom Visualizations SDK.
+summary: Add your own chart types to Metabase by uploading custom visualizations built with the Custom Visualizations SDK.
---
# Custom visualizations
@@ -19,7 +19,7 @@ This page covers how to add a custom visualization to your Metabase. To _create_
### Restrict image domains first
-Before you can turn on custom visualizations, you need to enable [Restrict image domains](../../configuring-metabase/settings.md#restrict-image-domains). A custom visualization runs third-party JavaScript in your Metabase. By restricting image (and font) domains, you limit where that code can load assets from, which narrows the ways a plugin could leak data through outbound asset requests. See [Only add plugins you trust](#only-add-plugins-you-trust).
+Before you can turn on custom visualizations, you need to enable [Restrict image domains](../../configuring-metabase/settings.md#restrict-image-domains). A custom visualization runs third-party JavaScript in your Metabase. By restricting image (and font) domains, you limit where that code can load assets from, which narrows the ways a custom visualization could leak data through outbound asset requests. See [Only add visualizations you trust](#only-add-visualizations-you-trust).
While custom visualizations are enabled, you can't turn **Restrict image domains** back off. You'll need to first disable custom visualizations.
@@ -38,8 +38,8 @@ Once you've [built the custom visualization](../../developers-guide/custom-visua
3. Click **Add visualization**.
- Bundles must be smaller than 5 MiB.
-- Each plugin lists the Metabase versions it supports (for example, "Requires Metabase >=1.62"). If your Metabase version isn't in that range, Metabase rejects the upload and tells you which version the plugin needs.
-- The **Manage visualizations** page shows each plugin's icon, name, the first eight characters of the bundle's hash, and its required Metabase version range, so you can tell which version is installed.
+- Each custom visualization lists the Metabase versions it supports (for example, "Requires Metabase >=1.62"). If your Metabase version isn't in that range, Metabase rejects the upload and tells you which version the visualization needs.
+- The **Manage visualizations** page shows each custom visualization's icon, name, the first eight characters of the bundle's hash, and its required Metabase version range, so you can tell which version is installed.
## Using a custom visualization
@@ -47,42 +47,44 @@ On a question, dashboard or document card, open the visualization sidebar (the *
![Gondola line chart](../images/gondola-line-chart.png)
-If a custom visualization can't render the current query results (for example, if the query is missing a column the visualization needs), Metabase shows the error message from the plugin so you can adjust the query or pick a different chart.
+If a custom visualization can't render the current query results (for example, if the query is missing a column the visualization needs), Metabase shows the error message from the custom visualization so you can adjust the query or pick a different chart.
Custom visualizations behave like built-in charts in most places:
-- **Settings.** Click the **gear** icon in the visualization sidebar to change the visualization's settings. A plugin defines its own setting tabs: each setting names the section it belongs to.
-- **Dark mode.** Plugins that use Metabase's colors adapt to [dark mode](../../people-and-groups/account-settings.md#theme) automatically.
+- **Settings.** Click the **gear** icon in the visualization sidebar to change the visualization's settings. A custom visualization defines its own setting tabs: each setting names the section it belongs to.
+- **Dark mode.** Custom visualizations that use Metabase's colors adapt to [dark mode](../../people-and-groups/account-settings.md#theme) automatically.
- **Icons.** A custom visualization shows its own icon in the visualization picker, and questions that use it show that icon in collections and bookmarks.
-### Custom visualizations don't render in embeds
+### Custom visualizations in embeds only work when using the SDK
-Custom visualizations only render in your Metabase. In [embeds](../../embedding/start.md) and [public links](../../embedding/public-links.md) (public questions, dashboards, and documents), any card that uses a custom visualization falls back to the default visualization (a table).
+The [Modular embedding SDK](../../embedding/sdk/introduction.md) can render custom visualizations. You allowlist the custom visualizations you want to load with the [`allowedCustomVisualizations` prop](../../embedding/sdk/config.md#custom-visualizations) on `MetabaseProvider`.
+
+Other embedding types don't render custom visualizations. In [modular embedding](../../embedding/modular-embedding.md) with web components, [guest and static embeds](../../embedding/introduction.md), and [public links](../../embedding/public-links.md), any card that uses a custom visualization falls back to the default visualization for the query's results.
## Managing custom visualizations
_Admin > Settings > Custom visualizations > Manage visualizations_
-- **Disable a visualization.** Any question, dashboard card, or document card that used the visualization falls back to the default visualization for that query's results. If you re-enable the plugin, those cards will go back to using the custom visualization.
-- **Replace a bundle.** Upload a new `.tgz` to ship an updated version of a plugin. The new bundle's manifest `name` _must_ match the existing plugin's identifier, so questions that already use the visualization keep working.
+- **Disable a visualization.** Any question, dashboard card, or document card that used the visualization falls back to the default visualization for that query's results. If you re-enable the visualization, those cards will go back to using the custom visualization.
+- **Replace a bundle.** Upload a new `.tgz` to ship an updated version of a custom visualization. The new bundle's manifest `name` _must_ match the existing visualization's identifier, so questions that already use the visualization keep working.
- **Remove a visualization.** Cards that used the custom viz fall back to the default visualization.
## Exports
- **Dashboard subscriptions and alerts don't use custom visualizations**. Cards that use custom visualizations will fall back to a default visualization for the card's data shape.
- **PDF exports of dashboards include custom visualizations**.
-- **Custom visualizations can support PNG export**, but only if its developer turned on PNG export for that plugin. PNG export is off by default.
+- **Custom visualizations can support PNG export**, but only if its developer turned on PNG export for that visualization. PNG export is off by default.
-## Only add plugins you trust
+## Only add visualizations you trust
-A custom visualization plugin runs JavaScript in your Metabase. Only upload plugins from sources you trust (like plugins you've built yourself, or have vetted).
+A custom visualization runs JavaScript in your Metabase. Only upload custom visualizations from sources you trust (like ones you've built yourself, or have vetted).
-Metabase runs custom visualizations in a sandbox to limit what a plugin can do:
+Metabase runs custom visualizations in a sandbox to limit what a custom visualization can do:
-- A plugin renders inside an isolated container and can't reach the rest of the Metabase app.
-- A plugin can't call Metabase's APIs or make network requests.
+- A custom visualization renders inside an isolated container and can't reach the rest of the Metabase app.
+- A custom visualization can't call Metabase's APIs or make network requests.
-While this sandboxing limits the damage a plugin can do, you still need to review the code.
+While this sandboxing limits the damage a custom visualization can do, you still need to review the code.
## Further reading