[auto] adding content to release-x.57.x->release-x.57.x (#794)

github-automation-metabase · Metabase Docs bot · web-flow · commit b96c464affb0 · 2025-11-13T22:23:53.000+02:00
Co-authored-by: Metabase Docs bot &lt;metabase-bot@metabase.com&gt;
diff --git a/_docs/v0.57/embedding/sdk/introduction.md b/_docs/v0.57/embedding/sdk/introduction.md
@@ -135,6 +135,7 @@ The SDK doesn't support:
 - Official collections
 - Subscriptions
 - Alerts
+- Click behavior with custom destinations to other items in the same Metabase (like to other questions or dashboards)
 - Server-side rendering (SSR)
 
 Other limitations:
diff --git a/_docs/v0.57/embedding/sdk/plugins.md b/_docs/v0.57/embedding/sdk/plugins.md
@@ -15,59 +15,57 @@ layout: new-docs
 
 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:
 
 ```typescript
 {% 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:
 
 ```typescript
 {% include_file "{{ dirname }}/snippets/plugins/component-plugins.tsx" snippet="example" %}
 ```
 
-## `handleLink`
+See docs for specific components:
+
+- [Interactive question plugins](./questions#interactive-question-plugins)
+- [Dashboard plugins](./dashboards#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#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#interactive-question-plugins)
diff --git a/_docs/v0.57/embedding/sdk/snippets/plugins/custom-images.tsx b/_docs/v0.57/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/v0.57/embedding/sdk/snippets/plugins/handlelink.tsx b/_docs/v0.57/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>]
+}
diff --git a/_site/docs/v0.57/embedding/sdk/introduction.html b/_site/docs/v0.57/embedding/sdk/introduction.html
@@ -5058,6 +5058,7 @@ <h2 id="sdk-limitations">SDK limitations</h2>
   <li>Official collections</li>
   <li>Subscriptions</li>
   <li>Alerts</li>
+  <li>Click behavior with custom destinations to other items in the same Metabase (like to other questions or dashboards)</li>
   <li>Server-side rendering (SSR)</li>
 </ul>
 
diff --git a/_site/docs/v0.57/embedding/sdk/plugins.html b/_site/docs/v0.57/embedding/sdk/plugins.html
@@ -4931,7 +4931,9 @@ <h1 id="embedded-analytics-sdk---plugins">Embedded analytics SDK - plugins</h1>
 
 <p>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.</p>
 
-<h2 id="global-plugins">Global plugins</h2>
+<h2 id="plugin-scope">Plugin scope</h2>
+
+<h3 id="global-plugins">Global plugins</h3>
 
 <p>To use a plugin globally, add the plugin to the <code class="language-plaintext highlighter-rouge">MetabaseProvider</code>’s <code class="language-plaintext highlighter-rouge">pluginsConfig</code> prop:</p>
 
@@ -4946,7 +4948,7 @@ <h2 id="global-plugins">Global plugins</h2>
 <span class="o">&lt;</span><span class="sr">/MetabaseProvider</span><span class="err">&gt;
 </span></code></pre></div></div>
 
-<h2 id="component-plugins">Component plugins</h2>
+<h3 id="component-plugins">Component plugins</h3>
 
 <p>To use a plugin on a per-component basis, pass the plugin as a prop to the component:</p>
 
@@ -4958,42 +4960,67 @@ <h2 id="component-plugins">Component plugins</h2>
 <span class="sr">/</span><span class="err">&gt;
 </span></code></pre></div></div>
 
-<h2 id="handlelink"><code class="language-plaintext highlighter-rouge">handleLink</code></h2>
+<p>See docs for specific components:</p>
+
+<ul>
+  <li><a href="./questions#interactive-question-plugins">Interactive question plugins</a></li>
+  <li><a href="./dashboards#dashboard-plugins">Dashboard plugins</a></li>
+</ul>
+
+<h2 id="global-plugins-1">Global plugins</h2>
+
+<h3 id="mapquestionclickactions"><code class="language-plaintext highlighter-rouge">mapQuestionClickActions</code></h3>
+
+<p>The plugin <code class="language-plaintext highlighter-rouge">mapQuestionClickActions</code> lets you to customize what happens when people click on a data point on a dashboard or chart. <code class="language-plaintext highlighter-rouge">mapQuestionClickActions</code> can be used globally, or on component level.</p>
+
+<p>See <a href="./questions#mapquestionclickactions"><code class="language-plaintext highlighter-rouge">mapQuestionClickActions</code> plugin</a> for more information and examples.</p>
+
+<h3 id="handlelink"><code class="language-plaintext highlighter-rouge">handleLink</code></h3>
 
 <p>To customize what happens when people click a link in your embedded questions and dashboards, use the global plugin <code class="language-plaintext highlighter-rouge">handleLink</code>:</p>
 
-<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="k">default</span> <span class="kd">function</span> <span class="nf">App</span><span class="p">()</span> <span class="p">{</span>
-  <span class="kd">const</span> <span class="nx">navigate</span> <span class="o">=</span> <span class="nf">useNavigate</span><span class="p">();</span> <span class="c1">// coming from whatever routing lib you're using</span>
-
-  <span class="kd">const</span> <span class="nx">plugins</span> <span class="o">=</span> <span class="p">{</span>
-    <span class="na">handleLink</span><span class="p">:</span> <span class="p">(</span><span class="na">urlString</span><span class="p">:</span> <span class="kr">string</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
-      <span class="kd">const</span> <span class="nx">url</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">URL</span><span class="p">(</span><span class="nx">urlString</span><span class="p">,</span> <span class="nb">window</span><span class="p">.</span><span class="nx">location</span><span class="p">.</span><span class="nx">origin</span><span class="p">);</span>
-      <span class="kd">const</span> <span class="nx">isInternal</span> <span class="o">=</span> <span class="nx">url</span><span class="p">.</span><span class="nx">origin</span> <span class="o">===</span> <span class="nb">window</span><span class="p">.</span><span class="nx">location</span><span class="p">.</span><span class="nx">origin</span><span class="p">;</span>
-      <span class="k">if </span><span class="p">(</span><span class="nx">isInternal</span><span class="p">)</span> <span class="p">{</span>
-        <span class="c1">// client side navigation</span>
-        <span class="nf">navigate</span><span class="p">(</span><span class="nx">url</span><span class="p">.</span><span class="nx">pathname</span> <span class="o">+</span> <span class="nx">url</span><span class="p">.</span><span class="nx">search</span> <span class="o">+</span> <span class="nx">url</span><span class="p">.</span><span class="nx">hash</span><span class="p">);</span>
-
-        <span class="k">return</span> <span class="p">{</span> <span class="na">handled</span><span class="p">:</span> <span class="kc">true</span> <span class="p">};</span> <span class="c1">// prevent default navigation</span>
-      <span class="p">}</span>
-      <span class="k">return</span> <span class="p">{</span> <span class="na">handled</span><span class="p">:</span> <span class="kc">false</span> <span class="p">};</span> <span class="c1">// let the sdk do the default behavior</span>
-    <span class="p">},</span>
-  <span class="p">};</span>
-
-  <span class="k">return </span><span class="p">(</span>
-    <span class="o">&lt;</span><span class="nx">MetabaseProvider</span> <span class="nx">authConfig</span><span class="o">=</span><span class="p">{</span><span class="nx">authConfig</span><span class="p">}</span> <span class="nx">pluginsConfig</span><span class="o">=</span><span class="p">{</span><span class="nx">plugins</span><span class="p">}</span><span class="o">&gt;</span>
-      <span class="o">&lt;</span><span class="nx">nav</span> <span class="nx">style</span><span class="o">=&gt;</span>
-        <span class="o">&lt;</span><span class="nx">Link</span> <span class="nx">to</span><span class="o">=</span><span class="dl">"</span><span class="s2">/</span><span class="dl">"</span><span class="o">&gt;</span><span class="nx">Home</span><span class="o">&lt;</span><span class="sr">/Link</span><span class="err">&gt;
-</span>        <span class="o">&lt;</span><span class="nx">Link</span> <span class="nx">to</span><span class="o">=</span><span class="dl">"</span><span class="s2">/question</span><span class="dl">"</span><span class="o">&gt;</span><span class="nx">Question</span><span class="o">&lt;</span><span class="sr">/Link</span><span class="err">&gt;
-</span>        <span class="o">&lt;</span><span class="nx">Link</span> <span class="nx">to</span><span class="o">=</span><span class="dl">"</span><span class="s2">/about</span><span class="dl">"</span><span class="o">&gt;</span><span class="nx">About</span><span class="o">&lt;</span><span class="sr">/Link</span><span class="err">&gt;
-</span>      <span class="o">&lt;</span><span class="sr">/nav</span><span class="err">&gt;
-</span>      <span class="o">&lt;</span><span class="nx">div</span> <span class="nx">style</span><span class="o">=&gt;</span>
-        <span class="o">&lt;</span><span class="nx">Outlet</span> <span class="o">/&gt;</span>
-      <span class="o">&lt;</span><span class="sr">/div</span><span class="err">&gt;
-</span>    <span class="o">&lt;</span><span class="sr">/MetabaseProvider</span><span class="err">&gt;
-</span>  <span class="p">);</span>
-<span class="p">}</span>
+<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">const</span> <span class="nx">plugins</span> <span class="o">=</span> <span class="p">{</span>
+  <span class="na">handleLink</span><span class="p">:</span> <span class="p">(</span><span class="na">urlString</span><span class="p">:</span> <span class="kr">string</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
+    <span class="kd">const</span> <span class="nx">url</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">URL</span><span class="p">(</span><span class="nx">urlString</span><span class="p">,</span> <span class="nb">window</span><span class="p">.</span><span class="nx">location</span><span class="p">.</span><span class="nx">origin</span><span class="p">);</span>
+    <span class="kd">const</span> <span class="nx">isInternal</span> <span class="o">=</span> <span class="nx">url</span><span class="p">.</span><span class="nx">origin</span> <span class="o">===</span> <span class="nb">window</span><span class="p">.</span><span class="nx">location</span><span class="p">.</span><span class="nx">origin</span><span class="p">;</span>
+    <span class="k">if </span><span class="p">(</span><span class="nx">isInternal</span><span class="p">)</span> <span class="p">{</span>
+      <span class="c1">// Handle internal navigation (e.g., with your router)</span>
+      <span class="nx">console</span><span class="p">.</span><span class="nf">log</span><span class="p">(</span><span class="dl">"</span><span class="s2">Navigate to:</span><span class="dl">"</span><span class="p">,</span> <span class="nx">url</span><span class="p">.</span><span class="nx">pathname</span> <span class="o">+</span> <span class="nx">url</span><span class="p">.</span><span class="nx">search</span> <span class="o">+</span> <span class="nx">url</span><span class="p">.</span><span class="nx">hash</span><span class="p">);</span>
+      <span class="k">return</span> <span class="p">{</span> <span class="na">handled</span><span class="p">:</span> <span class="kc">true</span> <span class="p">};</span> <span class="c1">// prevent default navigation</span>
+    <span class="p">}</span>
+    <span class="k">return</span> <span class="p">{</span> <span class="na">handled</span><span class="p">:</span> <span class="kc">false</span> <span class="p">};</span> <span class="c1">// let the SDK do the default behavior</span>
+  <span class="p">},</span>
+<span class="p">};</span>
+
+<span class="k">return </span><span class="p">(</span>
+  <span class="o">&lt;</span><span class="nx">MetabaseProvider</span> <span class="nx">authConfig</span><span class="o">=</span><span class="p">{</span><span class="nx">authConfig</span><span class="p">}</span> <span class="nx">pluginsConfig</span><span class="o">=</span><span class="p">{</span><span class="nx">plugins</span><span class="p">}</span><span class="o">&gt;</span>
+    <span class="o">&lt;</span><span class="nx">InteractiveDashboard</span> <span class="nx">dashboardId</span><span class="o">=</span><span class="p">{</span><span class="mi">1</span><span class="p">}</span> <span class="sr">/</span><span class="err">&gt;
+</span>  <span class="o">&lt;</span><span class="sr">/MetabaseProvider</span><span class="err">&gt;
+</span><span class="p">);</span>
 </code></pre></div></div>
 
+<p>The plugin <code class="language-plaintext highlighter-rouge">handleLink</code> can only be used <a href="#plugin-scope">globally</a> on provider level.</p>
+
+<h3 id="getnodataillustration-and-getnoobjectillustration"><code class="language-plaintext highlighter-rouge">getNoDataIllustration</code> and <code class="language-plaintext highlighter-rouge">getNoObjectIllustration</code></h3>
+
+<p>By default, Metabase displays a sailboat image when a query returns no results. To use a different image, you can use <code class="language-plaintext highlighter-rouge">getNoDataIllustration</code> and <code class="language-plaintext highlighter-rouge">getNoObjectIllustration</code> plugins which can accept a custom base64-encoded image:</p>
+
+<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">const</span> <span class="nx">img_base64</span> <span class="o">=</span> <span class="dl">"</span><span class="s2">...</span><span class="dl">"</span><span class="p">;</span> <span class="c1">// base64-encoded image</span>
+
+<span class="kd">const</span> <span class="nx">plugins</span> <span class="o">=</span> <span class="p">{</span>
+  <span class="na">getNoDataIllustration</span><span class="p">:</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="nx">img_base64</span><span class="p">,</span>
+  <span class="na">getNoObjectIllustration</span><span class="p">:</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="nx">img_base64</span><span class="p">,</span>
+<span class="p">};</span>
+
+<span class="k">return </span><span class="p">(</span>
+  <span class="o">&lt;</span><span class="nx">MetabaseProvider</span> <span class="nx">authConfig</span><span class="o">=</span><span class="p">{</span><span class="nx">authConfig</span><span class="p">}</span> <span class="nx">pluginsConfig</span><span class="o">=</span><span class="p">{</span><span class="nx">plugins</span><span class="p">}</span><span class="o">&gt;</span>
+    <span class="o">&lt;</span><span class="nx">InteractiveDashboard</span> <span class="nx">dashboardId</span><span class="o">=</span><span class="p">{</span><span class="mi">1</span><span class="p">}</span> <span class="sr">/</span><span class="err">&gt;
+</span>  <span class="o">&lt;</span><span class="sr">/MetabaseProvider</span><span class="err">&gt;
+</span><span class="p">);</span>
+</code></pre></div></div>
+
+<p>The plugins <code class="language-plaintext highlighter-rouge">getNoDataIllustration</code> and <code class="language-plaintext highlighter-rouge">getNoObjectIllustration</code> can only be used <a href="#plugin-scope">globally</a> on provider level.</p>
+
 <h2 id="further-reading">Further reading</h2>
 
 <ul>
diff --git a/_site/docs/v0.57/embedding/sdk/snippets/plugins/custom-images.tsx b/_site/docs/v0.57/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/_site/docs/v0.57/embedding/sdk/snippets/plugins/handlelink.tsx b/_site/docs/v0.57/embedding/sdk/snippets/plugins/handlelink.tsx
