Skip to content

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

docs: customization - config (#83030)

Michael Eby6f4dad4d7a1d
diff --git a/docs/embedding/components.md b/docs/embedding/components.md
index ddf651227ee..249f5af2a14 100644
--- a/docs/embedding/components.md
+++ b/docs/embedding/components.md
@@ -53,7 +53,8 @@ Web components cover the components above. A few features are React-only, becaus
## Further reading
- [Appearance](./appearance.md)
-- [Modular embedding SDK config](./sdk/config.md), for the `MetabaseProvider` props
+- [Configure your embeds](./config.md)
+- [Config reference](./config-reference.md), for `defineMetabaseConfig()` settings and `MetabaseProvider` props
- [Modular embedding parameters](./parameters.md)
- [Custom visualizations in embeds](./custom-visualizations.md)
- [Translating embeds](./translations.md)
diff --git a/docs/embedding/config-reference.md b/docs/embedding/config-reference.md
new file mode 100644
index 00000000000..35ea90ea8c1
--- /dev/null
+++ b/docs/embedding/config-reference.md
@@ -0,0 +1,45 @@
+---
+title: Config reference
+summary: "Reference for the page-level config settings for web components, and the props you can pass to the React SDK's MetabaseProvider."
+---
+
+# Config reference
+
+Reference material for the config that every modular embed on a page shares: the `defineMetabaseConfig()` settings for web components, and the `MetabaseProvider` props for the React SDK.
+
+For how to set all this up, check out [Configure your embeds](./config.md).
+
+## Web component `defineMetabaseConfig()` settings
+
+Every web component on the page uses these settings. For the SDK, see [`MetabaseProvider` props](#react-sdk-metabaseprovider-props).
+
+{% include_file "{{ dirname }}/eajs/snippets/MetabaseConfig.md" snippet="properties" %}
+
+## React SDK `MetabaseProvider` props
+
+{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %}
+
+`MetabaseProvider` provides the [configuration](./config.md#configure-the-react-sdk) that every Metabase component inside it uses.
+
+- [Component](./sdk/api/MetabaseProvider.html)
+- [Props](./sdk/api/MetabaseProviderProps.html)
+
+{% include_file "{{ dirname }}/sdk/api/snippets/MetabaseProviderProps.md" snippet="properties" %}
+
+## React SDK `eventHandlers`
+
+{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %}
+
+The `eventHandlers` prop on `MetabaseProvider` maps event types to handler functions. See [Handle embed events](./config.md#handle-embed-events-react-sdk-only).
+
+- [Type](./sdk/api/SdkEventHandlersConfig.html)
+
+{% include_file "{{ dirname }}/sdk/api/snippets/SdkEventHandlersConfig.md" snippet="properties" %}
+
+## Further reading
+
+- [Configure your embeds](./config.md)
+- [Appearance](./appearance.md)
+- [Authentication](./authentication.md)
+- [Guest embedding](./guest-embedding.md)
+- [Modular embedding components](./components.md)
diff --git a/docs/embedding/config.md b/docs/embedding/config.md
new file mode 100644
index 00000000000..5b28acbe308
--- /dev/null
+++ b/docs/embedding/config.md
@@ -0,0 +1,247 @@
+---
+title: Configure your embeds
+summary: "Set the configuration that all modular embeds on a page share, including your Metabase URL, language, and authentication mode, with web components or the React SDK."
+redirect_from:
+ - /docs/latest/embedding/sdk/config
+---
+
+# Configure your embeds
+
+Every modular embed on a page shares one configuration. How you configure your embeds depends on which embedding method you use:
+
+- **[Web components](#configure-web-components)**: call `defineMetabaseConfig()` once per page. All Metabase components on the page use that config.
+- **[React SDK](#configure-the-react-sdk)**: pass your config as props to `MetabaseProvider`. All Metabase components inside the provider use that config.
+
+Settings for one embed, like a dashboard's ID, go on the component. Settings for every embed, like your Metabase URL or theme, go in the shared configuration.
+
+## Configure web components
+
+To configure web components, add a script tag to your page that loads `embed.js` from your Metabase, then call `defineMetabaseConfig()`:
+
+```html
+<!-- embed.js defines <metabase-dashboard> and other elements -->
+<script defer src="https://your-metabase.example.com/app/embed.js"></script>
+<script>
+ function defineMetabaseConfig(config) {
+ window.metabaseConfig = config;
+ }
+</script>
+
+<script>
+ defineMetabaseConfig({
+ instanceUrl: "https://your-metabase.example.com",
+ });
+</script>
+
+<metabase-dashboard dashboard-id="1"></metabase-dashboard>
+```
+
+`instanceUrl`, the URL of your Metabase, is the only required setting.
+
+For the full list of settings, see [web component settings](./config-reference.md#web-component-definemetabaseconfig-settings).
+
+## Configure the React SDK
+
+{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %}
+
+To configure the [React SDK](./sdk/introduction.md), pass your config as props to `MetabaseProvider`. The only required prop is `authConfig`, which you create with `defineMetabaseAuthConfig()`:
+
+```tsx
+{% include_file "{{ dirname }}/sdk/snippets/config/config-base.tsx" %}
+```
+
+For the full list of props, see [`MetabaseProvider` props](./config-reference.md#react-sdk-metabaseprovider-props).
+
+## Set how your embeds authenticate
+
+Your config determines how every embed on the page authenticates:
+
+- **[Guest embeds](./introduction.md#components-with-guest-authentication)**: view-only. Your server signs a token for each embed, so people don't need Metabase accounts. See [Configure a guest embed](#configure-a-guest-embed).
+- **[SSO embeds](./introduction.md#components-with-sso-authentication)**: the default. Your app signs each person in to their own Metabase account, so their permissions apply. See [Configure an SSO embed](#configure-an-sso-embed).
+
+You can only use one type of authentication per page. To pick one, check out [SSO or guest embeds](./introduction.md#comparison-between-sso-and-guest-authentication).
+
+### Configure a guest embed
+
+To configure guest embeds, set `isGuest: true`, which tells the components to authenticate with a signed JWT instead of a Metabase session. Where the setting goes depends on how you're embedding.
+
+With web components, add `isGuest` to the page-level config. You can also add `guestEmbedProviderUri`, which points to the endpoint in your app that signs the tokens:
+
+```html
+<script>
+ defineMetabaseConfig({
+ instanceUrl: "https://your-metabase.example.com",
+ isGuest: true,
+ guestEmbedProviderUri: "/api/metabase-guest-token",
+ });
+</script>
+```
+
+The embed calls the endpoint for a token on load, and again when the current token expires. Without `guestEmbedProviderUri`, your server must generate a token for each component and set the token in that component's `token` attribute when building the page.
+
+With the SDK, add `isGuest` to your auth config, and pass each component a token that your server signs. The SDK doesn't support `guestEmbedProviderUri`.
+
+```tsx
+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-guest-auth.tsx" snippet="example" %}
+```
+
+Either way, you'll need to publish each item you want to embed. For publishing and the server-side code, see [guest embedding](./guest-embedding.md).
+
+### Configure an SSO embed
+
+Embeds use SSO unless you set `isGuest`, so there's no setting to turn SSO on. You'll need to [set up SSO in your Metabase and your app](./authentication.md).
+
+To customize how embeds fetch the JWT, set `fetchRequestToken` in `defineMetabaseConfig()` (web components) or `defineMetabaseAuthConfig()` (SDK). See [customizing JWT authentication](./authentication.md#customizing-jwt-authentication).
+
+### Preview embeds during development
+
+To preview embeds without setting up authentication, use your own Metabase session or an API key. Both are for development only.
+
+- **Use your existing session (web components only)**: in `defineMetabaseConfig()`, set `useExistingUserSession: true`. The embed renders using your Metabase session. Only supported in Google Chrome.
+- **Use an API key**: set `apiKey` in `defineMetabaseConfig()` (web components) or `defineMetabaseAuthConfig()` (SDK). Only works on localhost. See [authenticating locally with API keys](./authentication.md#authenticating-locally-with-api-keys).
+
+## Set the language
+
+To set the display language for every embed, add a `locale` with an ISO language code. The locale defaults to your Metabase instance's locale.
+
+Setting a locale translates Metabase's UI, like menus and filter widgets. It doesn't translate content you create, like dashboard names and filter labels. To translate your content, upload a [translation dictionary](./translations.md).
+
+- [Web component](#web-component-locale)
+- [React SDK](#react-sdk-locale)
+
+### Web component locale
+
+Add `locale` to the page-level config:
+
+```html
+<script>
+ defineMetabaseConfig({
+ instanceUrl: "https://your-metabase.example.com",
+ locale: "de",
+ });
+</script>
+```
+
+### React SDK locale
+
+Pass `locale` to `MetabaseProvider`:
+
+```tsx
+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-locale.tsx" snippet="example" %}
+```
+
+## Set a theme
+
+To customize colors and fonts for every embed, add a `theme` object. The theme object is the same for web components and the SDK. For all the theme options, see [Appearance](./appearance.md).
+
+- [Web component](#web-component-theme)
+- [React SDK](#react-sdk-theme)
+
+### Web component theme
+
+Add `theme` to the page-level config:
+
+```html
+<script>
+ defineMetabaseConfig({
+ instanceUrl: "https://your-metabase.example.com",
+ theme: {
+ colors: {
+ brand: "#509EE3",
+ },
+ },
+ });
+</script>
+```
+
+### React SDK theme
+
+Create a theme with `defineMetabaseTheme()` and pass it to `MetabaseProvider`:
+
+```tsx
+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-theme.tsx" snippet="example" %}
+```
+
+## Configure plugins
+
+To customize the behavior of embedded components, add plugins with `pluginsConfig`. Plugins you set in the shared config apply to every embed.
+
+- [Web component](#web-component-plugins)
+- [React SDK](#react-sdk-plugins)
+
+### Web component plugins
+
+Web components support one plugin, [`handleLink`](./sdk/plugins.md#handlelink), which customizes what happens when people click a link in an embed. Add `pluginsConfig` to the page-level config:
+
+```html
+<script>
+ defineMetabaseConfig({
+ instanceUrl: "https://your-metabase.example.com",
+ pluginsConfig: {
+ handleLink: (urlString) => {
+ const url = new URL(urlString, window.location.origin);
+ if (url.origin === window.location.origin) {
+ // Handle the link yourself, like with your app's router
+ return { handled: true };
+ }
+ return { handled: false }; // Open the link in a new tab
+ },
+ },
+ });
+</script>
+```
+
+### React SDK plugins
+
+Pass `pluginsConfig` to `MetabaseProvider`:
+
+```tsx
+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-plugins.tsx" snippet="example" %}
+```
+
+SDK components also take their own `plugins` prop, which overrides the global config.
+
+For available plugins and their APIs, see [plugins](./sdk/plugins.md).
+
+## Allow custom visualizations
+
+To render [custom visualizations](../questions/visualizations/custom.md) in your embeds, add the `allowedCustomVisualizations` allowlist to `defineMetabaseConfig()` (web components) or pass it to `MetabaseProvider` (SDK).
+
+Custom visualizations require SSO. Guest embeds ignore the allowlist and show the default visualization instead.
+
+For examples and the naming rules, see [custom visualizations in embeds](./custom-visualizations.md).
+
+## Handle embed events (React SDK only)
+
+To run your own code when embeds load, like sending analytics events, pass an `eventHandlers` object to `MetabaseProvider`. There's no web component equivalent.
+
+```tsx
+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-event-handlers.tsx" snippet="example" %}
+```
+
+`onDashboardLoad` fires when a dashboard loads with all visible cards and their content.
+
+For the full list of handlers, see [`eventHandlers`](./config-reference.md#react-sdk-eventhandlers).
+
+## Customize loading and error states (React SDK only)
+
+To replace the SDK's default loading and error screens, pass `loaderComponent` and `errorComponent` to `MetabaseProvider`. There's no web component equivalent. See [Customize loading, error, and empty states](./sdk/loading-and-errors.md).
+
+## Reload a component (React SDK only)
+
+Metabase components don't detect your app's data changes. To reload an embed after your app's data changes, change the component's `key` prop:
+
+```tsx
+{% include_file "{{ dirname }}/sdk/snippets/config/reload-metabase-provider.tsx" snippet="example" %}
+```
+
+## Further reading
+
+- [Config reference](./config-reference.md)
+- [Appearance](./appearance.md)
+- [Authentication](./authentication.md)
+- [Guest embedding](./guest-embedding.md)
+- [Translating embeds](./translations.md)
+- [Custom visualizations in embeds](./custom-visualizations.md)
+- [Modular embedding components](./components.md)
+- [Modular embedding SDK](./sdk/introduction.md)
diff --git a/docs/embedding/custom-visualizations.md b/docs/embedding/custom-visualizations.md
index f8d64eb64a1..451d7a01427 100644
--- a/docs/embedding/custom-visualizations.md
+++ b/docs/embedding/custom-visualizations.md
@@ -35,7 +35,7 @@ Where the allowlist goes depends on how you're embedding:
### Web components allowlist for custom visualizations
-`allowedCustomVisualizations` is a [page-level config](./modular-embedding.md#page-level-config), not an attribute on `<metabase-dashboard>` or `<metabase-question>`. The allowlist applies to every component on the page.
+`allowedCustomVisualizations` is a [page-level config](./config.md#configure-web-components), not an attribute on `<metabase-dashboard>` or `<metabase-question>`. The allowlist applies to every component on the page.
Add `allowedCustomVisualizations` to `defineMetabaseConfig()`:
diff --git a/docs/embedding/eajs/snippets/MetabaseConfig.md b/docs/embedding/eajs/snippets/MetabaseConfig.md
new file mode 100644
index 00000000000..110d1aa76a4
--- /dev/null
+++ b/docs/embedding/eajs/snippets/MetabaseConfig.md
@@ -0,0 +1,25 @@
+Settings for `defineMetabaseConfig()`.
+
+Page-level configuration shared by every web component on the page.
+
+## Properties
+
+<!-- [<snippet properties>] -->
+
+| Property | Type | Description |
+| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="allowedcustomvisualizations"></a> `allowedCustomVisualizations` | `` `custom:${string}` ``[] | The custom visualizations that components on the page can load, each prefixed with `custom:`, like `["custom:Calendar Heatmap"]`. Not available in guest embeds. See [Custom visualizations in embeds](https://www.metabase.com/docs/latest/embedding/custom-visualizations).<br>---<br>Optional |
+| <a id="apikey"></a> `apiKey` | `string` | Development only. An API key from your Metabase, which embeds use to render on localhost. See [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config#preview-embeds-during-development).<br>---<br>Optional |
+| <a id="fetchrequesttoken"></a> `fetchRequestToken` | () => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<\{ `jwt`: `string`; \}\> | SSO embeds with JWT only. A function that fetches the JWT for embeds. See [Customizing JWT authentication](https://www.metabase.com/docs/latest/embedding/authentication#customizing-jwt-authentication).<br>---<br>Optional |
+| <a id="guestembedprovideruri"></a> `guestEmbedProviderUri` | `string` | Guest embeds only. Your app's endpoint that signs guest tokens. The embed calls this endpoint for a token on load, and again when the current token expires. The endpoint should return `{ jwt: string }`. See [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config#configure-a-guest-embed).<br>---<br>Optional |
+| <a id="instanceurl"></a> `instanceUrl` | `string` | The URL of your Metabase, like `https://youlooknicetoday.metabaseapp.com`. |
+| <a id="isguest"></a> `isGuest` | `boolean` | Whether the components authenticate as guest embeds, with a signed JWT instead of a Metabase session. See [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config#configure-a-guest-embed).<br>---<br>Optional<br>Default: `false` |
+| <a id="jwtprovideruri"></a> `jwtProviderUri` | `string` | SSO embeds with JWT only. The URL of your JWT provider. When set, embeds use JWT and skip the request that discovers the SSO method.<br>---<br>Optional |
+| <a id="locale"></a> `locale` | `string` | The display language for every embed, as an ISO language code like `en` or `de`. Defaults to your Metabase instance's locale. See [Set the language](https://www.metabase.com/docs/latest/embedding/config#set-the-language).<br>---<br>Optional |
+| <a id="pluginsconfig"></a> `pluginsConfig` | \{ `handleLink`: (`url`: `string`) => \{ `handled`: `boolean`; \}; \} | Plugins that customize component behavior. Web components support `handleLink`, for customizing what happens when people click a link. See [Web component plugins](https://www.metabase.com/docs/latest/embedding/config#web-component-plugins).<br>---<br>Optional |
+| `pluginsConfig.handleLink` | (`url`: `string`) => \{ `handled`: `boolean`; \} | Called when people click a link in an embed. Return `{ handled: true }` to handle the link yourself, or `{ handled: false }` to open the link in a new tab.<br>---<br>Optional |
+| <a id="preferredauthmethod"></a> `preferredAuthMethod` | `string` | SSO embeds only. Which SSO method to use. If you've set up both SAML and JWT, embeds default to SAML. See [Authentication](https://www.metabase.com/docs/latest/embedding/authentication#if-both-saml-and-jwt-are-enabled-modular-embedding-will-default-to-saml).<br>---<br>Optional<br>Possible values: `"jwt"`, `"saml"` |
+| <a id="theme"></a> `theme` | `object` | Colors, fonts, and per-component appearance overrides. See [Appearance](https://www.metabase.com/docs/latest/embedding/appearance).<br>---<br>Optional |
+| <a id="useexistingusersession"></a> `useExistingUserSession` | `boolean` | Development only. Whether to render embeds with your own Metabase session. Only supported in Google Chrome. See [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config#preview-embeds-during-development).<br>---<br>Optional<br>Default: `false` |
+
+<!-- [<endsnippet properties>] -->
diff --git a/docs/embedding/eajs/snippets/index.md b/docs/embedding/eajs/snippets/index.md
index e39147cb73e..cc0e2f9a8f8 100644
--- a/docs/embedding/eajs/snippets/index.md
+++ b/docs/embedding/eajs/snippets/index.md
@@ -7,6 +7,7 @@ This is the source of truth for all attributes accepted by modular embedding com
| Interface | Description |
| :------------------------------------------------------------ | :------------------------------------------------------- |
| [MetabaseBrowserAttributes](MetabaseBrowserAttributes.md) | Attributes for the `<metabase-browser>` web component. |
+| [MetabaseConfig](MetabaseConfig.md) | Settings for `defineMetabaseConfig()`. |
| [MetabaseDashboardAttributes](MetabaseDashboardAttributes.md) | Attributes for the `<metabase-dashboard>` web component. |
| [MetabaseMetabotAttributes](MetabaseMetabotAttributes.md) | Attributes for the `<metabase-metabot>` web component. |
| [MetabaseQuestionAttributes](MetabaseQuestionAttributes.md) | Attributes for the `<metabase-question>` web component. |
diff --git a/docs/embedding/modular-embedding.md b/docs/embedding/modular-embedding.md
index 83aba0ab060..15d9ddc399b 100644
--- a/docs/embedding/modular-embedding.md
+++ b/docs/embedding/modular-embedding.md
@@ -184,21 +184,7 @@ See [Modular embedding parameters](./parameters.md#pass-parameter-values-to-embe
## Page-level config
-To define the configuration that applies to every embed on the page, use the `defineMetabaseConfig()` function. Its parameters include:
-
-- `instanceUrl: "https://your-metabase-url"` (required): the URL of your Metabase instance, like `https://youlooknicetoday.metabaseapp.com`
-
-- `theme: {...}` (optional): [appearance options for the embeds](./appearance.md).
-
-- `useExistingUserSession: true|false` (optional, for development only) - lets you preview the embed locally using your Metabase admin account session. Only supported in Google Chrome.
-
-- `apiKey: mb_YourAPIKey` (optional, for development only) - another way to preview embeds locally using an API key.
-
-- `fetchRequestToken: () => Promise<{ jwt: string }>` (optional) - you can customize how the SDK fetches the refresh token for JWT authentication by specifying the `fetchRequestToken` function. See [customizing JWT authentication](./authentication.md#customizing-jwt-authentication).
-
-- `pluginsConfig` : plugins to customize the behavior of embedded components. Use the `handleLink` function to customize what happens when people click a link in your embedded questions and dashboards. For details on the `handleLink` API, including code examples, see [`handleLink` plugin](./sdk/plugins.md#handlelink).
-
-- `allowedCustomVisualizations: ["custom:Calendar Heatmap"]` (optional): the [custom visualizations](./custom-visualizations.md) that the components on the page are allowed to load. Not available in guest embeds.
+To define the configuration that applies to every embed on the page, like the URL of your Metabase, the authentication mode, and the theme, use the `defineMetabaseConfig()` function. See [Configure your embeds](./config.md). For the full list of settings, see the [config reference](./config-reference.md#web-component-definemetabaseconfig-settings).
## Authentication
diff --git a/docs/embedding/sdk/api/MetabaseProvider.html b/docs/embedding/sdk/api/MetabaseProvider.html
index ed528a9f341..0486e237ced 100644
--- a/docs/embedding/sdk/api/MetabaseProvider.html
+++ b/docs/embedding/sdk/api/MetabaseProvider.html
@@ -17,7 +17,7 @@ listed plugins are loaded. Omit or pass <code>[]</code> to disable.</p>
</div></li><li class="tsd-parameter"><h5 id="classname"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">className</span><span class="tsd-signature-symbol">?: </span><span class="tsd-signature-type">string</span></h5><div class="tsd-comment tsd-typography"><p>A custom class name to be added to the root element.</p>
</div><div class="tsd-comment tsd-typography"><div class="tsd-tag-deprecated"><h4 class="tsd-anchor-link" id="deprecated">Deprecated<a href="#deprecated" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>This prop is not used anymore.</p>
</div></div></li><li class="tsd-parameter"><h5 id="errorcomponent"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">errorComponent</span><span class="tsd-signature-symbol">?: </span><a href="SdkErrorComponent.html" class="tsd-signature-type tsd-kind-type-alias">SdkErrorComponent</a></h5><div class="tsd-comment tsd-typography"><p>A custom error component to display when the SDK encounters an error.</p>
-</div></li><li class="tsd-parameter"><h5 id="eventhandlers"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">eventHandlers</span><span class="tsd-signature-symbol">?: </span><a href="SdkEventHandlersConfig.html" class="tsd-signature-type tsd-kind-type-alias">SdkEventHandlersConfig</a></h5><div class="tsd-comment tsd-typography"><p>See <a href="https://www.metabase.com/docs/latest/embedding/sdk/config#global-event-handlers">Global event handlers</a>.</p>
+</div></li><li class="tsd-parameter"><h5 id="eventhandlers"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">eventHandlers</span><span class="tsd-signature-symbol">?: </span><a href="SdkEventHandlersConfig.html" class="tsd-signature-type tsd-kind-type-alias">SdkEventHandlersConfig</a></h5><div class="tsd-comment tsd-typography"><p>See <a href="https://www.metabase.com/docs/latest/embedding/config#handle-embed-events-react-sdk-only">Handle embed events</a>.</p>
</div></li><li class="tsd-parameter"><h5 id="loadercomponent"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">loaderComponent</span><span class="tsd-signature-symbol">?: </span><a href="https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L104" class="tsd-signature-type external" target="_blank">ComponentType</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-symbol">{</span> <span class="tsd-kind-property">label</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">&gt;</span></h5><div class="tsd-comment tsd-typography"><p>A custom loader component to display while the SDK is loading.</p>
<p>The component receives an optional <code>label</code> prop that can be used to display a loading message.</p>
</div></li><li class="tsd-parameter"><h5 id="locale"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">locale</span><span class="tsd-signature-symbol">?: </span><span class="tsd-signature-type">string</span></h5><div class="tsd-comment tsd-typography"><p>Defines the display language. Accepts an ISO language code such as <code>en</code> or <code>de</code>.
diff --git a/docs/embedding/sdk/api/MetabaseProviderProps.html b/docs/embedding/sdk/api/MetabaseProviderProps.html
index c1715e92a73..a86fcd0f873 100644
--- a/docs/embedding/sdk/api/MetabaseProviderProps.html
+++ b/docs/embedding/sdk/api/MetabaseProviderProps.html
@@ -28,7 +28,7 @@ listed plugins are loaded. Omit or pass <code>[]</code> to disable.</p>
</div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="classname"><code class="tsd-tag">Optional</code><span class="deprecated">class<wbr/>Name</span><a href="#classname" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">className</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span></div><div class="tsd-comment tsd-typography"><p>A custom class name to be added to the root element.</p>
</div><div class="tsd-comment tsd-typography"><div class="tsd-tag-deprecated"><h4 class="tsd-anchor-link" id="deprecated">Deprecated<a href="#deprecated" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>This prop is not used anymore.</p>
</div></div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="errorcomponent"><code class="tsd-tag">Optional</code><span>error<wbr/>Component</span><a href="#errorcomponent" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">errorComponent</span><span class="tsd-signature-symbol">?:</span> <a href="SdkErrorComponent.html" class="tsd-signature-type tsd-kind-type-alias">SdkErrorComponent</a></div><div class="tsd-comment tsd-typography"><p>A custom error component to display when the SDK encounters an error.</p>
-</div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="eventhandlers"><code class="tsd-tag">Optional</code><span>event<wbr/>Handlers</span><a href="#eventhandlers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">eventHandlers</span><span class="tsd-signature-symbol">?:</span> <a href="SdkEventHandlersConfig.html" class="tsd-signature-type tsd-kind-type-alias">SdkEventHandlersConfig</a></div><div class="tsd-comment tsd-typography"><p>See <a href="https://www.metabase.com/docs/latest/embedding/sdk/config#global-event-handlers">Global event handlers</a>.</p>
+</div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="eventhandlers"><code class="tsd-tag">Optional</code><span>event<wbr/>Handlers</span><a href="#eventhandlers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">eventHandlers</span><span class="tsd-signature-symbol">?:</span> <a href="SdkEventHandlersConfig.html" class="tsd-signature-type tsd-kind-type-alias">SdkEventHandlersConfig</a></div><div class="tsd-comment tsd-typography"><p>See <a href="https://www.metabase.com/docs/latest/embedding/config#handle-embed-events-react-sdk-only">Handle embed events</a>.</p>
</div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="loadercomponent"><code class="tsd-tag">Optional</code><span>loader<wbr/>Component</span><a href="#loadercomponent" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">loaderComponent</span><span class="tsd-signature-symbol">?:</span> <a href="https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L104" class="tsd-signature-type external" target="_blank">ComponentType</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-symbol">{</span> <span class="tsd-kind-property">label</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">&gt;</span></div><div class="tsd-comment tsd-typography"><p>A custom loader component to display while the SDK is loading.</p>
<p>The component receives an optional <code>label</code> prop that can be used to display a loading message.</p>
</div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="locale"><code class="tsd-tag">Optional</code><span>locale</span><a href="#locale" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">locale</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span></div><div class="tsd-comment tsd-typography"><p>Defines the display language. Accepts an ISO language code such as <code>en</code> or <code>de</code>.
diff --git a/docs/embedding/sdk/api/snippets/MetabaseProviderProps.md b/docs/embedding/sdk/api/snippets/MetabaseProviderProps.md
index 795bf09264f..a30217d82cb 100644
--- a/docs/embedding/sdk/api/snippets/MetabaseProviderProps.md
+++ b/docs/embedding/sdk/api/snippets/MetabaseProviderProps.md
@@ -12,7 +12,7 @@
| <a id="children"></a> `children` | [`ReactNode`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L478) | The children of the MetabaseProvider component. |
| <a id="classname"></a> ~~`className?`~~ | `string` | A custom class name to be added to the root element. **Deprecated** This prop is not used anymore. |
| <a id="errorcomponent"></a> `errorComponent?` | [`SdkErrorComponent`](./api/SdkErrorComponent.md) | A custom error component to display when the SDK encounters an error. |
-| <a id="eventhandlers"></a> `eventHandlers?` | [`SdkEventHandlersConfig`](./api/SdkEventHandlersConfig.md) | See [Global event handlers](https://www.metabase.com/docs/latest/embedding/sdk/config#global-event-handlers). |
+| <a id="eventhandlers"></a> `eventHandlers?` | [`SdkEventHandlersConfig`](./api/SdkEventHandlersConfig.md) | See [Handle embed events](https://www.metabase.com/docs/latest/embedding/config#handle-embed-events-react-sdk-only). |
| <a id="loadercomponent"></a> `loaderComponent?` | [`ComponentType`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L104)\<\{ `label?`: `string`; \}\> | A custom loader component to display while the SDK is loading. The component receives an optional `label` prop that can be used to display a loading message. |
| <a id="locale"></a> `locale?` | `string` | Defines the display language. Accepts an ISO language code such as `en` or `de`. Defaults to the instance locale. |
| <a id="pluginsconfig"></a> `pluginsConfig?` | [`MetabaseGlobalPluginsConfig`](./api/MetabaseGlobalPluginsConfig.md) | See [Plugins](https://www.metabase.com/docs/latest/embedding/sdk/plugins). |
diff --git a/docs/embedding/sdk/config.md b/docs/embedding/sdk/config.md
deleted file mode 100644
index 0438f4bed2c..00000000000
--- a/docs/embedding/sdk/config.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: Modular embedding SDK - config
-summary: Configure the Metabase modular embedding SDK with MetabaseProvider, set up authentication, handle global events, and reload embedded components.
----
-
-# Modular embedding SDK - config
-
-{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true %}
-
-## Passing a configuration object to `MetabaseProvider`
-
-To use the SDK in your app, you need to import the `MetabaseProvider` component and provide it with an `authConfig` object.
-
-### `MetabaseProvider`
-
-A component that configures the SDK and provides the Metabase SDK's context and theme.
-
-To pass a theme, use `defineMetabaseTheme`. See [Reuse a saved theme in the SDK](../appearance.md#reuse-a-saved-theme-in-the-sdk).
-
-#### API Reference
-
-- [Component](./api/MetabaseProvider.html)
-- [Props](./api/MetabaseProviderProps.html)
-
-#### Example
-
-```typescript
-{% include_file "{{ dirname }}/snippets/config/config-base.tsx" %}
-```
-
-#### Props
-
-{% include_file "{{ dirname }}/api/snippets/MetabaseProviderProps.md" snippet="properties" %}
-
-## Custom visualizations
-
-The SDK can render [custom visualizations](../../questions/visualizations/custom.md) that you allowlist with the `allowedCustomVisualizations` prop on `MetabaseProvider`. See [Custom visualizations in embeds](../custom-visualizations.md).
-
-## Loading and error components
-
-The `loaderComponent` and `errorComponent` props swap the SDK's default loading and error screens for your own React components. See [Customize loading, error, and empty states](./loading-and-errors.md).
-
-## Global event handlers
-
-You can listen for events by defining the `eventHandlers` prop for `MetabaseProvider`.
-
-### `SdkEventHandlersConfig`
-
-Accepts an object where each key is an event type and the corresponding value is the event handler function.
-
-#### API Reference
-
-- [Type](./api/SdkEventHandlersConfig.html)
-
-#### Example
-
-```typescript
-{% include_file "{{ dirname }}/snippets/config/config-with-event-handlers.tsx" snippet="example" %}
-```
-
-#### Props
-
-{% include_file "{{ dirname }}/api/snippets/SdkEventHandlersConfig.md" snippet="properties" %}
-
-## Reloading Metabase components
-
-In case you need to reload a Metabase component, for example, your users modify your application data and that data is used to render a question in Metabase. If you embed this question and want to force Metabase to reload the question to show the latest data, you can do so by using the `key` prop to force a component to reload.
-
-```typescript
-{% include_file "{{ dirname }}/snippets/config/reload-metabase-provider.tsx" snippet="example" %}
-```
diff --git a/docs/embedding/sdk/introduction.md b/docs/embedding/sdk/introduction.md
index 0c210c751ba..9ecde17f109 100644
--- a/docs/embedding/sdk/introduction.md
+++ b/docs/embedding/sdk/introduction.md
@@ -112,7 +112,7 @@ Start with one of the quickstarts, then see these pages for more info on compone
- [Embed a collection browser](../browser.md)
- [Custom visualizations](../custom-visualizations.md)
- [Plugins](./plugins.md)
-- [Config](./config.md)
+- [Configure your embeds](../config.md)
- [Customize loading, error, and empty states](./loading-and-errors.md)
- [Versioning](./version.md)
- [Notes on Next.js](./next-js.md)
diff --git a/docs/embedding/sdk/loading-and-errors.md b/docs/embedding/sdk/loading-and-errors.md
index 32c5f0d4475..3fb94a31f42 100644
--- a/docs/embedding/sdk/loading-and-errors.md
+++ b/docs/embedding/sdk/loading-and-errors.md
@@ -47,5 +47,5 @@ Unlike `loaderComponent` and `errorComponent`, these are [plugins](./plugins.md)
- [Modular embedding SDK plugins](./plugins.md)
- [Appearance](../appearance.md)
-- [Modular embedding SDK config](./config.md)
+- [Configure your embeds](../config.md)
- [Modular embedding components](../components.md)
diff --git a/docs/embedding/sdk/plugins.md b/docs/embedding/sdk/plugins.md
index 885449093f8..a6bc2260c0c 100644
--- a/docs/embedding/sdk/plugins.md
+++ b/docs/embedding/sdk/plugins.md
@@ -52,7 +52,7 @@ By default, links open in a new tab. Use `handleLink` to intercept link clicks
The function receives a URL string. Return `{ handled: true }` to prevent default navigation, or `{ handled: false }` to open the link in a new tab.
-The plugin `handleLink` can only be used [globally](#plugin-scope) on provider level. `handleLink` is also available in [modular embedding](../modular-embedding.md#page-level-config) via `pluginsConfig` in `defineMetabaseConfig`, with the same API.
+The plugin `handleLink` can only be used [globally](#plugin-scope) on provider level. `handleLink` is also available in [web components](../config.md#web-component-plugins) via `pluginsConfig` in `defineMetabaseConfig`, with the same API.
To create clickable links in your table columns, set the column's formatting to [display as link](../../data-modeling/metadata/formatting.md#display-as).
diff --git a/docs/embedding/sdk/snippets/config/config-base.tsx b/docs/embedding/sdk/snippets/config/config-base.tsx
index e81bfb552c8..3abdd007718 100644
--- a/docs/embedding/sdk/snippets/config/config-base.tsx
+++ b/docs/embedding/sdk/snippets/config/config-base.tsx
@@ -1,37 +1,19 @@
import React from "react";
import {
MetabaseProvider,
+ StaticDashboard,
defineMetabaseAuthConfig,
- defineMetabaseTheme,
} from "@metabase/embedding-sdk-react";
-// Configure authentication
const authConfig = defineMetabaseAuthConfig({
- metabaseInstanceUrl: "https://metabase.example.com", // Required: Your Metabase instance URL
-});
-
-// See the "Customizing appearance" section for more information
-const theme = defineMetabaseTheme({
- // Optional: Specify a font to use from the set of fonts supported by Metabase
- fontFamily: "Lato",
-
- // Optional: Match your application's color scheme
- colors: {
- brand: "#9B5966",
- "text-primary": "#4C5773",
- "text-secondary": "#696E7B",
- "text-tertiary": "#949AAB",
- },
+ metabaseInstanceUrl: "https://your-metabase.example.com", // Required
});
export default function App() {
return (
- <MetabaseProvider
- authConfig={authConfig}
- theme={theme}
- className="optional-class"
- >
- Hello World!
+ <MetabaseProvider authConfig={authConfig}>
+ {/* Metabase components go here */}
+ <StaticDashboard dashboardId={1} />
</MetabaseProvider>
);
}
diff --git a/docs/embedding/sdk/snippets/config/config-with-event-handlers.tsx b/docs/embedding/sdk/snippets/config/config-with-event-handlers.tsx
index 9e52d579c59..7b71ef81da2 100644
--- a/docs/embedding/sdk/snippets/config/config-with-event-handlers.tsx
+++ b/docs/embedding/sdk/snippets/config/config-with-event-handlers.tsx
@@ -1,23 +1,20 @@
import type { PropsWithChildren } from "react";
import {
+ type MetabaseAuthConfig,
MetabaseProvider,
type SdkDashboardLoadEvent,
- defineMetabaseAuthConfig,
} from "@metabase/embedding-sdk-react";
-const authConfig = defineMetabaseAuthConfig({
- metabaseInstanceUrl: "",
-});
+const authConfig = {} as MetabaseAuthConfig;
const Example = ({ children }: PropsWithChildren) => {
// [<snippet example>]
const handleDashboardLoad: SdkDashboardLoadEvent = (dashboard) => {
- /* do whatever you need to do - e.g. send analytics events, show notifications */
+ // Send analytics events, show notifications, etc.
};
const eventHandlers = {
onDashboardLoad: handleDashboardLoad,
- onDashboardLoadWithoutCards: handleDashboardLoad,
};
return (
diff --git a/docs/embedding/sdk/snippets/config/config-with-guest-auth.tsx b/docs/embedding/sdk/snippets/config/config-with-guest-auth.tsx
new file mode 100644
index 00000000000..f0cb799b4cd
--- /dev/null
+++ b/docs/embedding/sdk/snippets/config/config-with-guest-auth.tsx
@@ -0,0 +1,23 @@
+import {
+ MetabaseProvider,
+ StaticDashboard,
+ defineMetabaseAuthConfig,
+} from "@metabase/embedding-sdk-react";
+
+// [<snippet example>]
+// A JWT that your server signs with your Metabase embedding secret key.
+const token = "YOUR_SIGNED_JWT";
+
+const authConfig = defineMetabaseAuthConfig({
+ metabaseInstanceUrl: "https://your-metabase.example.com",
+ isGuest: true,
+});
+
+export default function App() {
+ return (
+ <MetabaseProvider authConfig={authConfig}>
+ <StaticDashboard token={token} />
+ </MetabaseProvider>
+ );
+}
+// [<endsnippet example>]
diff --git a/docs/embedding/sdk/snippets/config/config-with-locale.tsx b/docs/embedding/sdk/snippets/config/config-with-locale.tsx
new file mode 100644
index 00000000000..dd5a263edfd
--- /dev/null
+++ b/docs/embedding/sdk/snippets/config/config-with-locale.tsx
@@ -0,0 +1,15 @@
+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} locale="de">
+ {children}
+ </MetabaseProvider>
+ // [<endsnippet example>]
+);
diff --git a/docs/embedding/sdk/snippets/config/config-with-plugins.tsx b/docs/embedding/sdk/snippets/config/config-with-plugins.tsx
new file mode 100644
index 00000000000..91c6f1e074e
--- /dev/null
+++ b/docs/embedding/sdk/snippets/config/config-with-plugins.tsx
@@ -0,0 +1,21 @@
+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}
+ pluginsConfig={{
+ // Return the default actions, plus any custom actions you add
+ mapQuestionClickActions: (clickActions) => clickActions,
+ }}
+ >
+ {children}
+ </MetabaseProvider>
+ // [<endsnippet example>]
+);
diff --git a/docs/embedding/sdk/snippets/config/config-with-theme.tsx b/docs/embedding/sdk/snippets/config/config-with-theme.tsx
new file mode 100644
index 00000000000..6be1df0c206
--- /dev/null
+++ b/docs/embedding/sdk/snippets/config/config-with-theme.tsx
@@ -0,0 +1,24 @@
+import type { PropsWithChildren } from "react";
+import {
+ type MetabaseAuthConfig,
+ MetabaseProvider,
+ defineMetabaseTheme,
+} from "@metabase/embedding-sdk-react";
+
+const authConfig = {} as MetabaseAuthConfig;
+
+const Example = ({ children }: PropsWithChildren) => {
+ // [<snippet example>]
+ const theme = defineMetabaseTheme({
+ colors: {
+ brand: "#509EE3",
+ },
+ });
+
+ return (
+ <MetabaseProvider authConfig={authConfig} theme={theme}>
+ {children}
+ </MetabaseProvider>
+ );
+ // [<endsnippet example>]
+};
diff --git a/docs/embedding/sdk/snippets/config/reload-metabase-provider.tsx b/docs/embedding/sdk/snippets/config/reload-metabase-provider.tsx
index 6c9e3a8cf2a..41e2a72dd06 100644
--- a/docs/embedding/sdk/snippets/config/reload-metabase-provider.tsx
+++ b/docs/embedding/sdk/snippets/config/reload-metabase-provider.tsx
@@ -1,37 +1,27 @@
-import { useEffect, useState } from "react";
+import { useState } from "react";
import { InteractiveQuestion } from "@metabase/embedding-sdk-react";
-import { isEqual } from "underscore";
const yourQuestionId = 1;
+const order = {};
+
+const api = {
+ saveOrder: async (order: unknown) => {},
+};
const Example = () => {
// [<snippet example>]
- // Inside your application component
- const [data, setData] = useState({});
- // This is used to force reloading Metabase components
- const [counter, setCounter] = useState(0);
+ const [dataVersion, setDataVersion] = useState(0);
- // This ensures we only change the `data` reference when it's actually changed
- const handleDataChange = newData => {
- setData(prevData => {
- if (isEqual(prevData, newData)) {
- return prevData;
- }
-
- return newData;
- });
+ const saveOrder = async (order) => {
+ await api.saveOrder(order); // Your app changes its data...
+ setDataVersion((v) => v + 1); // ...then changes the key, reloading the embed.
};
- useEffect(() => {
- /**
- * When you set `data` as the `useEffect` hook's dependency, it will trigger the effect
- * and increment the counter which is used in a Metabase component's `key` prop, forcing it to reload.
- */
- if (data) {
- setCounter(counter => counter + 1);
- }
- }, [data]);
-
- return <InteractiveQuestion key={counter} questionId={yourQuestionId} />;
+ return (
+ <>
+ <button onClick={() => saveOrder(order)}>Save order</button>
+ <InteractiveQuestion key={dataVersion} questionId={yourQuestionId} />
+ </>
+ );
// [<endsnippet example>]
};
diff --git a/docs/embedding/start.md b/docs/embedding/start.md
index 0ce3651a833..d64658164af 100644
--- a/docs/embedding/start.md
+++ b/docs/embedding/start.md
@@ -62,6 +62,14 @@ Every `<metabase-browser>` attribute and the `CollectionBrowser` props.
Embed an AI chat with web components or the React SDK, so people can ask questions of their data in natural language.
+### [Configure your embeds](./config.md)
+
+Set the configuration that every embed on a page shares, like your Metabase URL, authentication, language, and theme, with web components or the React SDK.
+
+### [Config reference](./config-reference.md)
+
+Every `defineMetabaseConfig()` setting for web components, and the `MetabaseProvider` props for the React SDK.
+
### [Guest embedding](./guest-embedding.md)
Guest embedding is a secure way to embed charts and dashboards. Guest embeds are view-only; people won't be able to drill-through charts and tables.
diff --git a/docs/util/data/nav.yml b/docs/util/data/nav.yml
index 9c86a9134ba..b7b2cfd1321 100644
--- a/docs/util/data/nav.yml
+++ b/docs/util/data/nav.yml
@@ -280,6 +280,10 @@ categories:
url: "embedding/ai-chat"
- name: "Filters and parameters"
url: "embedding/parameters"
+ - name: "Config"
+ url: "embedding/config"
+ - name: "Config reference"
+ url: "embedding/config-reference"
- name: "Appearance"
url: "embedding/appearance"
- name: "Custom visualizations"
@@ -302,8 +306,6 @@ categories:
url: "embedding/sdk/loading-and-errors"
- name: "Configuration"
pages:
- - name: "Provider config"
- url: "embedding/sdk/config"
- name: "Working with Next.js"
url: "embedding/sdk/next-js"
- name: "Versioning"
diff --git a/frontend/src/embedding-sdk-bundle/types/metabase-provider.ts b/frontend/src/embedding-sdk-bundle/types/metabase-provider.ts
index 6a4b7299d1c..43b4d75cf2e 100644
--- a/frontend/src/embedding-sdk-bundle/types/metabase-provider.ts
+++ b/frontend/src/embedding-sdk-bundle/types/metabase-provider.ts
@@ -40,7 +40,7 @@ export interface MetabaseProviderProps {
pluginsConfig?: MetabaseGlobalPluginsConfig;
/**
- * See [Global event handlers](https://www.metabase.com/docs/latest/embedding/sdk/config#global-event-handlers).
+ * See [Handle embed events](https://www.metabase.com/docs/latest/embedding/config#handle-embed-events-react-sdk-only).
*/
eventHandlers?: SdkEventHandlersConfig;
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk/constants.ts b/frontend/src/metabase/embedding/embedding-iframe-sdk/constants.ts
index 18a406e22d1..64950638131 100644
--- a/frontend/src/metabase/embedding/embedding-iframe-sdk/constants.ts
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk/constants.ts
@@ -7,6 +7,7 @@ import type {
SdkIframeEmbedBaseSettings,
SdkIframeEmbedSettingKey,
} from "./types/embed";
+import type { MetabaseConfig } from "./types/modular-embedding";
/**
* The timeout to wait for a session token from the embed.js script.
@@ -30,7 +31,8 @@ export const ALLOWED_EMBED_SETTING_KEYS_MAP = {
"pluginsConfig",
"guestEmbedProviderUri",
"allowedCustomVisualizations",
- ] satisfies (keyof SdkIframeEmbedBaseSettings)[],
+ // Every allowed setting must be documented in `MetabaseConfig`
+ ] satisfies (keyof SdkIframeEmbedBaseSettings & keyof MetabaseConfig)[],
dashboard: [
"dashboardId",
"autoRefreshInterval",
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts b/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts
index 3e18d6f5546..792a907cb30 100644
--- a/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts
@@ -337,6 +337,105 @@ export interface MetabaseMetabotAttributes {
"target-collection"?: number | string;
}
+/**
+ * Settings for `defineMetabaseConfig()`.
+ *
+ * Page-level configuration shared by every web component on the page.
+ */
+export interface MetabaseConfig {
+ /**
+ * The URL of your Metabase, like `https://youlooknicetoday.metabaseapp.com`.
+ */
+ instanceUrl: string;
+
+ /**
+ * Whether the components authenticate as guest embeds, with a signed JWT
+ * instead of a Metabase session. See
+ * [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config#configure-a-guest-embed).
+ *
+ * @defaultValue false
+ */
+ isGuest?: boolean;
+
+ /**
+ * Guest embeds only. Your app's endpoint that signs guest tokens. The embed
+ * calls this endpoint for a token on load, and again when the current token
+ * expires. The endpoint should return `{ jwt: string }`. See
+ * [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config#configure-a-guest-embed).
+ */
+ guestEmbedProviderUri?: string;
+
+ /**
+ * The display language for every embed, as an ISO language code like `en`
+ * or `de`. Defaults to your Metabase instance's locale. See
+ * [Set the language](https://www.metabase.com/docs/latest/embedding/config#set-the-language).
+ */
+ locale?: string;
+
+ /**
+ * Colors, fonts, and per-component appearance overrides. See
+ * [Appearance](https://www.metabase.com/docs/latest/embedding/appearance).
+ */
+ theme?: object;
+
+ /**
+ * Plugins that customize component behavior. Web components support
+ * `handleLink`, for customizing what happens when people click a link.
+ * See [Web component plugins](https://www.metabase.com/docs/latest/embedding/config#web-component-plugins).
+ */
+ pluginsConfig?: {
+ /**
+ * Called when people click a link in an embed. Return `{ handled: true }`
+ * to handle the link yourself, or `{ handled: false }` to open the link
+ * in a new tab.
+ */
+ handleLink?: (url: string) => { handled: boolean };
+ };
+
+ /**
+ * The custom visualizations that components on the page can load, each
+ * prefixed with `custom:`, like `["custom:Calendar Heatmap"]`. Not available
+ * in guest embeds. See
+ * [Custom visualizations in embeds](https://www.metabase.com/docs/latest/embedding/custom-visualizations).
+ */
+ allowedCustomVisualizations?: `custom:${string}`[];
+
+ /**
+ * SSO embeds only. Which SSO method to use. If you've set up both SAML and
+ * JWT, embeds default to SAML. See
+ * [Authentication](https://www.metabase.com/docs/latest/embedding/authentication#if-both-saml-and-jwt-are-enabled-modular-embedding-will-default-to-saml).
+ */
+ preferredAuthMethod?: "jwt" | "saml";
+
+ /**
+ * SSO embeds with JWT only. The URL of your JWT provider. When set, embeds
+ * use JWT and skip the request that discovers the SSO method.
+ */
+ jwtProviderUri?: string;
+
+ /**
+ * SSO embeds with JWT only. A function that fetches the JWT for embeds. See
+ * [Customizing JWT authentication](https://www.metabase.com/docs/latest/embedding/authentication#customizing-jwt-authentication).
+ */
+ fetchRequestToken?: () => Promise<{ jwt: string }>;
+
+ /**
+ * Development only. Whether to render embeds with your own Metabase
+ * session. Only supported in Google Chrome. See
+ * [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config#preview-embeds-during-development).
+ *
+ * @defaultValue false
+ */
+ useExistingUserSession?: boolean;
+
+ /**
+ * Development only. An API key from your Metabase, which embeds use to
+ * render on localhost. See
+ * [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config#preview-embeds-during-development).
+ */
+ apiKey?: string;
+}
+
/**
* Used to enforce types in frontend/src/metabase/embedding/embedding-iframe-sdk/embed.ts
*