Skip to content

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

docs: more new plugins + typechecked snippet for links (#65767)

Alex Yaroshc040219c6219
diff --git a/docs/embedding/sdk/plugins.md b/docs/embedding/sdk/plugins.md
index 903d80990f4..d3835ceb744 100644
--- a/docs/embedding/sdk/plugins.md
+++ b/docs/embedding/sdk/plugins.md
@@ -8,7 +8,9 @@ title: Embedded analytics SDK - plugins
The Metabase Embedded analytics SDK supports plugins to customize the behavior of components. These plugins can be used in a global context or on a per-component basis.
-## Global plugins
+## Plugin scope
+
+### Global plugins
To use a plugin globally, add the plugin to the `MetabaseProvider`'s `pluginsConfig` prop:
@@ -16,7 +18,7 @@ To use a plugin globally, add the plugin to the `MetabaseProvider`'s `pluginsCon
{% include_file "{{ dirname }}/snippets/plugins/global-plugins.tsx" snippet="example" %}
```
-## Component plugins
+### Component plugins
To use a plugin on a per-component basis, pass the plugin as a prop to the component:
@@ -24,43 +26,39 @@ To use a plugin on a per-component basis, pass the plugin as a prop to the compo
{% include_file "{{ dirname }}/snippets/plugins/component-plugins.tsx" snippet="example" %}
```
-## `handleLink`
+See docs for specific components:
+
+- [Interactive question plugins](./questions.md#interactive-question-plugins)
+- [Dashboard plugins](./dashboards.md#dashboard-plugins)
+
+## Global plugins
+
+### `mapQuestionClickActions`
+
+The plugin `mapQuestionClickActions` lets you to customize what happens when people click on a data point on a dashboard or chart. `mapQuestionClickActions` can be used globally, or on component level.
+
+See [`mapQuestionClickActions` plugin](./questions.md#mapquestionclickactions) for more information and examples.
+
+### `handleLink`
To customize what happens when people click a link in your embedded questions and dashboards, use the global plugin `handleLink`:
```typescript
-export default function App() {
- const navigate = useNavigate(); // coming from whatever routing lib you're using
-
- const plugins = {
- handleLink: (urlString: string) => {
- const url = new URL(urlString, window.location.origin);
- const isInternal = url.origin === window.location.origin;
- if (isInternal) {
- // client side navigation
- navigate(url.pathname + url.search + url.hash);
-
- return { handled: true }; // prevent default navigation
- }
- return { handled: false }; // let the sdk do the default behavior
- },
- };
-
- return (
- <MetabaseProvider authConfig={authConfig} pluginsConfig={plugins}>
- <nav style={{ display: "flex", gap: 12, padding: 12 }}>
- <Link to="/">Home</Link>
- <Link to="/question">Question</Link>
- <Link to="/about">About</Link>
- </nav>
- <div style={{ padding: 12 }}>
- <Outlet />
- </div>
- </MetabaseProvider>
- );
-}
+{% include_file "{{ dirname }}/snippets/plugins/handlelink.tsx" snippet="example" %}
```
+The plugin `handleLink` can only be used [globally](#plugin-scope) on provider level.
+
+### `getNoDataIllustration` and `getNoObjectIllustration`
+
+By default, Metabase displays a sailboat image when a query returns no results. To use a different image, you can use `getNoDataIllustration` and `getNoObjectIllustration` plugins which can accept a custom base64-encoded image:
+
+```typescript
+{% include_file "{{ dirname }}/snippets/plugins/custom-images.tsx" snippet="example" %}
+```
+
+The plugins `getNoDataIllustration` and `getNoObjectIllustration` can only be used [globally](#plugin-scope) on provider level.
+
## Further reading
- [Interactive question plugins](./questions.md#interactive-question-plugins)
diff --git a/docs/embedding/sdk/snippets/plugins/custom-images.tsx b/docs/embedding/sdk/snippets/plugins/custom-images.tsx
new file mode 100644
index 00000000000..06a0e2a3c7b
--- /dev/null
+++ b/docs/embedding/sdk/snippets/plugins/custom-images.tsx
@@ -0,0 +1,25 @@
+import {
+ InteractiveDashboard,
+ type MetabaseAuthConfig,
+ MetabaseProvider,
+} from "@metabase/embedding-sdk-react";
+
+const authConfig = {} as MetabaseAuthConfig;
+
+export default function App() {
+ // [<snippet example>]
+
+ const img_base64 = "..."; // base64-encoded image
+
+ const plugins = {
+ getNoDataIllustration: () => img_base64,
+ getNoObjectIllustration: () => img_base64,
+ };
+
+ return (
+ <MetabaseProvider authConfig={authConfig} pluginsConfig={plugins}>
+ <InteractiveDashboard dashboardId={1} />
+ </MetabaseProvider>
+ );
+ // [<endsnippet example>]
+}
diff --git a/docs/embedding/sdk/snippets/plugins/handleLink.tsx b/docs/embedding/sdk/snippets/plugins/handleLink.tsx
new file mode 100644
index 00000000000..70af41a499f
--- /dev/null
+++ b/docs/embedding/sdk/snippets/plugins/handleLink.tsx
@@ -0,0 +1,30 @@
+import {
+ InteractiveDashboard,
+ type MetabaseAuthConfig,
+ MetabaseProvider,
+} from "@metabase/embedding-sdk-react";
+
+const authConfig = {} as MetabaseAuthConfig;
+
+export default function App() {
+ // [<snippet example>]
+ const plugins = {
+ handleLink: (urlString: string) => {
+ const url = new URL(urlString, window.location.origin);
+ const isInternal = url.origin === window.location.origin;
+ if (isInternal) {
+ // Handle internal navigation (e.g., with your router)
+ console.log("Navigate to:", url.pathname + url.search + url.hash);
+ return { handled: true }; // prevent default navigation
+ }
+ return { handled: false }; // let the SDK do the default behavior
+ },
+ };
+
+ return (
+ <MetabaseProvider authConfig={authConfig} pluginsConfig={plugins}>
+ <InteractiveDashboard dashboardId={1} />
+ </MetabaseProvider>
+ );
+ // [<endsnippet example>]
+}