Skip to content

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

docs: new sdk click and link behavior (#65627)

Alex Yaroshff2b3d80ff55
diff --git a/docs/data-modeling/model-persistence.md b/docs/data-modeling/model-persistence.md
index 55c5678f8e8..971a7408b37 100644
--- a/docs/data-modeling/model-persistence.md
+++ b/docs/data-modeling/model-persistence.md
@@ -10,7 +10,7 @@ Metabase will store model results in tables in a bespoke schema in your data war
> Model persistence doesn't work with [row and column security](../permissions/row-and-column-security.md) or [impersonation](../permissions/impersonation.md).
-## Database that support model persistence
+## Databases that support model persistence
Currently, model persistence is only available for the following databases:
diff --git a/docs/embedding/sdk/dashboards.md b/docs/embedding/sdk/dashboards.md
index 5c950f48ac0..3f3c33d417d 100644
--- a/docs/embedding/sdk/dashboards.md
+++ b/docs/embedding/sdk/dashboards.md
@@ -129,6 +129,10 @@ If you want to replace the existing menu with your own component, you can do so
{% include_file "{{ dirname }}/snippets/dashboards/plugins.tsx" snippet="example-custom-actions-menu" %}
```
+### `mapQuestionClickActions`
+
+You can customize what happens when people click on a data point on a dashboard with the `mapQuestionClickActions` plugin. See [mapQuestionClickActions](./questions.md#mapquestionclickactions).
+
## Creating dashboards
Creating a dashboard could be done with `useCreateDashboardApi` hook or `CreateDashboardModal` component.
diff --git a/docs/embedding/sdk/plugins.md b/docs/embedding/sdk/plugins.md
index 32fe71f02a7..903d80990f4 100644
--- a/docs/embedding/sdk/plugins.md
+++ b/docs/embedding/sdk/plugins.md
@@ -24,6 +24,43 @@ 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`
+
+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>
+ );
+}
+```
+
## Further reading
- [Interactive question plugins](./questions.md#interactive-question-plugins)
diff --git a/docs/embedding/sdk/questions.md b/docs/embedding/sdk/questions.md
index 876fc8efafa..405f3896025 100644
--- a/docs/embedding/sdk/questions.md
+++ b/docs/embedding/sdk/questions.md
@@ -124,8 +124,27 @@ You can use [plugins](./plugins.md) to add custom functionality to your question
### `mapQuestionClickActions`
-This plugin allows you to add custom actions to the click-through menu of an interactive question. You can add and
-customize the appearance and behavior of the custom actions.
+When people click on a data point in the embedded interactive chart, Metabase shows them a menu of actions by default. The plugin `mapQuestionClickActions` allows you to customize this behavior. You can choose to:
+
+- Open the default Metabase menu.
+- Add custom actions to that click-through menu.
+- Perform immediate action without opening a menu.
+
+Use `mapQuestionClickActions` globally at the provider level, or on individual `InteractiveQuestion` or `InteractiveDashboard` components. For more on provider scope, see [Plugins](./plugins.md)
+
+The example below shows all the options for click action behavior. This example will:
+
+- Open a menu with custom actions when "Last Name" column is clicked.
+- Perform an immediate action (show an alert) when the "Plan" column is clicked.
+- Shows the default menu (available as `clickActions`) in all other cases.
+
+The behavior is determined by what `mapQuestionClickActions` returns: array of actions to open a menu, or a single action to trigger an immediate action.
+
+```typescript
+{% include_file "{{ dirname }}/snippets/questions/interactive-question-click-actions.tsx" snippet="example" %}
+```
+
+You can also customize the appearance of custom actions in the click menu. The example below shows an example of a click menu with default actions, a custom action, and a custom action with customized appearance:
```typescript
{% include_file "{{ dirname }}/snippets/questions/interactive-question-plugins.tsx" snippet="example" %}
diff --git a/docs/embedding/sdk/snippets/questions/interactive-question-click-actions.tsx b/docs/embedding/sdk/snippets/questions/interactive-question-click-actions.tsx
new file mode 100644
index 00000000000..5dbf82636a1
--- /dev/null
+++ b/docs/embedding/sdk/snippets/questions/interactive-question-click-actions.tsx
@@ -0,0 +1,46 @@
+import {
+ defineMetabaseAuthConfig,
+ InteractiveQuestion,
+ MetabaseProvider,
+} from "@metabase/embedding-sdk-react";
+
+const authConfig = defineMetabaseAuthConfig({
+ metabaseInstanceUrl: "http://localhost:3000",
+});
+
+const Example = () => {
+ return (
+ // [<snippet example>]
+ <MetabaseProvider
+ authConfig={authConfig}
+ pluginsConfig={{
+ mapQuestionClickActions: (clickActions, clicked) => {
+ if (clicked?.column?.display_name === "Last Name") {
+ // This adds a custom action to the menu when clicked on on "Last Name" column
+ return [
+ ...clickActions,
+ {
+ buttonType: "horizontal",
+ name: "custom",
+ title: "This is the Last Name column",
+ onClick: () => alert("You clicked the Last Name column!"),
+ },
+ ];
+ }
+
+ if (clicked?.column?.display_name === "Plan") {
+ // This performs an immediate action on "Plan" column instead of opening the menu
+ return {
+ onClick: () => alert("You clicked the Plan column!"),
+ };
+ }
+ // default behavior (open Metabase's default click menu) on other columns
+ return clickActions;
+ },
+ }}
+ >
+ <InteractiveQuestion questionId={1} />
+ </MetabaseProvider>
+ );
+ // [<endsnippet example>]
+};