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 - custom viz sdk (#77974)
Jeff Bruemmereb8d806ffe17
diff --git a/docs/developers-guide/custom-visualizations.md b/docs/developers-guide/custom-visualizations.mdindex 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 pluginsdiff --git a/docs/embedding/introduction.md b/docs/embedding/introduction.mdindex 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 readingdiff --git a/docs/embedding/sdk/config.md b/docs/embedding/sdk/config.mdindex 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 handlersYou 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.tsxnew file mode 100644index 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.mdindex 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-visua3. 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 *-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