Skip to content

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

docs - notes on custom viz (#76703)

Jeff Bruemmer7a7e1d4ae32e
diff --git a/docs/developers-guide/custom-visualizations.md b/docs/developers-guide/custom-visualizations.md
index 9f95d23ad34..342e9599f59 100644
--- a/docs/developers-guide/custom-visualizations.md
+++ b/docs/developers-guide/custom-visualizations.md
@@ -404,7 +404,9 @@ The Custom Visualizations SDK works with Metabase 1.62 and newer. Declare the ve
If you upload a bundle to a Metabase outside the plugin's declared range, Metabase rejects the upload.
-## Sandbox restrictions
+## Custom visualization limitations
+
+### Sandbox restrictions
Metabase runs plugin code in an isolated sandbox, so a visualization works only from the `series` and `settings` it's given. The sandbox blocks:
@@ -415,9 +417,13 @@ 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 only render in the live app
+### Custom visualizations don't render in embeds or public links
+
+[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).
+
+### Custom visualizations don't render in exports and subscriptions
-Custom visualizations only render in the live, interactive app. Static renders, like dashboard subscriptions sent by [email](../dashboards/subscriptions.md), Slack, or webhook, fall back to a table for any card that uses a custom visualization. The same goes for [embedded](../embedding/introduction.md) questions and dashboards: a card that uses a custom visualization falls back to a table.
+Static renders—like charts in alerts or dashboard subscriptions—fall back to a table for any card that uses a custom visualization.
## Example plugins
diff --git a/docs/embedding/introduction.md b/docs/embedding/introduction.md
index b8be9f5b89d..ba5f93a9e6a 100644
--- a/docs/embedding/introduction.md
+++ b/docs/embedding/introduction.md
@@ -34,8 +34,6 @@ Here's a basic breakdown of what each auth type enables:
| Browser to navigate collections | ✅ | ❌ |
| Metabot AI chat | ✅ | ❌ |
-Currently, you can't embed [documents](../documents/introduction.md).
-
### SSO embeds
With SSO, Metabase can know who's viewing what, which unlocks a lot of power. You can automatically apply [data permissions](../permissions/embedding.md), which means you can give people access to all the cool tools Metabase provides, and everyone will only ever see the data they're allowed to.
@@ -102,6 +100,11 @@ If you're using an AI agent to help you embed Metabase in your app, check out [A
For information about the anonymous usage data Metabase collects from embedded components, see [Embedding telemetry](../installation-and-operation/information-collection.md#embedding-telemetry).
+## 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).
+
## Further reading
- [Strategies for delivering customer-facing analytics](https://www.metabase.com/learn/metabase-basics/embedding/overview).
diff --git a/docs/questions/visualizations/custom.md b/docs/questions/visualizations/custom.md
index 4a99a0c4712..c29012556f5 100644
--- a/docs/questions/visualizations/custom.md
+++ b/docs/questions/visualizations/custom.md
@@ -55,6 +55,10 @@ Custom visualizations behave like built-in charts in most places:
- **Dark mode.** Plugins 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 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).
+
## Managing custom visualizations
_Admin > Settings > Custom visualizations > Manage visualizations_