Skip to content

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

docs(sdk): move llms.txt under docs/embedding (#67526)

Phoomparin Mano09d69f2cdf3b
diff --git a/docs/embedding/llms.txt b/docs/embedding/llms.txt
new file mode 100644
index 00000000000..e7f13671d69
--- /dev/null
+++ b/docs/embedding/llms.txt
@@ -0,0 +1,1264 @@
+# Metabase Modular Embedding Reference
+
+> Complete guide for embedding Metabase charts, dashboards, query builder, and AI chat into your applications.
+
+## Overview
+
+Metabase offers two primary ways to embed analytics:
+
+1. **Modular Embedding JS** - Embed individual components (dashboards, questions, query builder, AI chat) with full customization
+2. **Modular Embedding SDK** - React SDK for advanced embedding with custom layouts and plugins
+
+### When to Use Modular Embedding
+
+- **SSO Embeds**: Multi-tenant self-service analytics with drill-through, query builder, and AI chat. Requires JWT or SAML authentication.
+- **Guest Embeds**: Simple, secure charts and dashboards without SSO. View-only with locked parameters for data filtering.
+
+### Feature Comparison
+
+| Feature | SSO | Guest | SDK |
+|---------|-----|-------|-----|
+| Charts & Dashboards | ✅ | ✅ | ✅ |
+| Drill-through | ✅ | ❌ | ✅ |
+| Query Builder | ✅ | ❌ | ✅ |
+| AI Chat (Metabot) | ✅ | ❌ | ✅ |
+| Collection Browser | ✅ | ❌ | ✅ |
+| Advanced Theming | ✅ | ❌ | ✅ |
+| Custom Layouts | ❌ | ❌ | ✅ |
+| Plugins | ❌ | ❌ | ✅ |
+| Data Permissions | ✅ | ❌ | ✅ |
+
+---
+
+## Quick Start Paths
+
+### Path 1: Simple Web Components (No React Required)
+
+Best for: Adding analytics to any web app with minimal code.
+
+```html
+<!-- Load embedding library -->
+<script defer src="https://your-metabase-url/app/embed.js"></script>
+
+<script>
+ defineMetabaseConfig({
+ instanceUrl: "https://your-metabase-url",
+ apiKey: "mb_dev_api_key", // For local testing only
+ theme: {
+ colors: {
+ brand: "#9B5966",
+ background: "#FFFFFF"
+ }
+ }
+ });
+</script>
+
+<!-- Embed a dashboard -->
+<metabase-dashboard dashboard-id="1" with-title="true"></metabase-dashboard>
+
+<!-- Embed a question -->
+<metabase-question question-id="5"></metabase-question>
+```
+
+### Path 2: React SDK (Advanced)
+
+Best for: React apps needing custom layouts, plugins, and full control.
+
+```bash
+# Install (use dist-tag matching your Metabase version)
+npm install @metabase/embedding-sdk-react@58-stable
+```
+
+```tsx
+import { MetabaseProvider, StaticDashboard } from "@metabase/embedding-sdk-react";
+
+function App() {
+ return (
+ <MetabaseProvider
+ authConfig={{
+ metabaseInstanceUrl: "https://your-metabase-url",
+ apiKey: "mb_dev_api_key" // For local testing only
+ }}
+ >
+ <StaticDashboard dashboardId={1} />
+ </MetabaseProvider>
+ );
+}
+```
+
+---
+
+## Authentication
+
+### Development: API Keys (localhost only)
+
+```javascript
+// Web components
+defineMetabaseConfig({
+ instanceUrl: "https://your-metabase-url",
+ apiKey: "mb_your_api_key"
+});
+
+// React SDK
+authConfig={{
+ metabaseInstanceUrl: "https://your-metabase-url",
+ apiKey: "mb_your_api_key"
+}}
+```
+
+**⚠️ API keys only work on localhost and should never be used in production.**
+
+### Production: JWT SSO (Requires Pro/Enterprise)
+
+**⚠️ Important:** The SDK automatically uses the JWT endpoint configured in Metabase Admin settings. You don't need `fetchRequestToken` unless you require custom headers/auth.
+
+#### Backend Setup (Node.js example)
+
+```javascript
+const jwt = require("jsonwebtoken");
+
+app.get("/sso/metabase", async (req, res) => {
+ const user = getCurrentUser(req);
+
+ const token = jwt.sign(
+ {
+ email: user.email,
+ first_name: user.firstName,
+ last_name: user.lastName,
+ groups: [user.group],
+ exp: Math.round(Date.now() / 1000) + 60 * 10 // 10 min expiration
+ },
+ METABASE_JWT_SHARED_SECRET
+ );
+
+ // For SDK requests (check for response=json query param)
+ if (req.query.response === "json") {
+ res.status(200).json({ jwt: token });
+ } else {
+ // For full app embedding
+ const ssoUrl = `${METABASE_INSTANCE_URL}/auth/sso?token=true&jwt=${token}`;
+ res.redirect(ssoUrl);
+ }
+});
+```
+
+#### Frontend Configuration
+
+```tsx
+// React SDK
+import { defineMetabaseAuthConfig } from "@metabase/embedding-sdk-react";
+
+// ✅ CORRECT - Default setup (works for most cases)
+const authConfig = defineMetabaseAuthConfig({
+ metabaseInstanceUrl: "https://your-metabase-url"
+ // SDK automatically uses JWT endpoint configured in Metabase admin
+ // No fetchRequestToken needed!
+});
+
+// ❌ DEPRECATED - DO NOT USE
+const authConfig = defineMetabaseAuthConfig({
+ metabaseInstanceUrl: "https://your-metabase-url",
+ authProviderUri: "..." // REMOVED - configure in Metabase admin instead
+});
+```
+
+### Production: SAML SSO (Requires Enterprise)
+
+```tsx
+const authConfig = defineMetabaseAuthConfig({
+ metabaseInstanceUrl: "https://your-metabase-url",
+ preferredAuthMethod: "saml"
+});
+```
+
+### Guest Embeds (No User Accounts Required)
+
+Backend generates signed JWT tokens containing resource ID and locked parameters:
+
+```javascript
+const jwt = require("jsonwebtoken");
+
+const payload = {
+ resource: { dashboard: 10 }, // or { question: 5 }
+ params: { category: ["Gizmo"] }, // Locked parameters
+ exp: Math.round(Date.now() / 1000) + 10 * 60
+};
+
+const token = jwt.sign(payload, METABASE_SECRET_KEY);
+```
+
+Frontend:
+
+```html
+<script>
+ defineMetabaseConfig({
+ isGuest: true,
+ instanceUrl: "https://your-metabase-url"
+ });
+</script>
+
+<metabase-dashboard token="YOUR_JWT_TOKEN"></metabase-dashboard>
+```
+
+**⚠️ Never hardcode tokens in HTML. Fetch from your backend dynamically.**
+
+## ⚠️ Common Gotchas for Code Generation
+
+### 1. Deprecated Props (DO NOT USE)
+- ❌ `authProviderUri` - DEPRECATED, remove from all code
+- ❌ `jwtProviderUri` - DEPRECATED, remove from all code
+- ❌ `config` prop on MetabaseProvider - DEPRECATED, use `authConfig` instead
+
+### 2. fetchRequestToken Usually Not Needed
+**DON'T add `fetchRequestToken` unless explicitly needed for custom headers/auth.**
+
+The SDK automatically fetches tokens from the JWT endpoint configured in Metabase Admin settings. Adding `fetchRequestToken` unnecessarily can break backend code that handles legacy interactive embedding redirects, especially if you forget to pass `response=json` in the request.
+
+**Only use `fetchRequestToken` when:**
+- You need custom headers (e.g., `Authorization: Bearer ${token}`)
+- You need custom fetch logic beyond the default
+
+**Default behavior (works for most cases):**
+```tsx
+const authConfig = defineMetabaseAuthConfig({
+ metabaseInstanceUrl: "https://your-metabase-url"
+ // No fetchRequestToken needed - SDK uses admin-configured JWT endpoint
+});
+```
+
+**Custom fetchRequestToken (only when needed):**
+```tsx
+const authConfig = defineMetabaseAuthConfig({
+ metabaseInstanceUrl: "https://your-metabase-url",
+ fetchRequestToken: async () => {
+ const response = await fetch("https://your-backend/sso/metabase", {
+ headers: { "Authorization": `Bearer ${yourToken}` }
+ // SDK adds ?response=json automatically
+ });
+ return await response.json();
+ }
+});
+```
+
+### 3. Numeric IDs Must Be Integers, Not Strings
+**ALWAYS parse URL parameters and strings to integers using `parseInt()`.**
+
+```tsx
+// ❌ WRONG - String IDs will cause errors
+const dashboardId = searchParams.get("id"); // "123" (string)
+<StaticDashboard dashboardId={dashboardId} /> // ERROR!
+
+// ✅ CORRECT - Parse to integer
+const dashboardId = parseInt(searchParams.get("id"), 10); // 123 (number)
+<StaticDashboard dashboardId={dashboardId} /> // Works!
+
+// ✅ Also works with entity IDs (strings starting with letters)
+const dashboardId = searchParams.get("id"); // "abc123def"
+<StaticDashboard dashboardId={dashboardId} /> // Works!
+```
+
+**Rule of thumb:**
+- Numeric IDs (e.g., `123`): Must be `number` type → use `parseInt(value, 10)`
+- Entity IDs (e.g., `"abc123def"`): Must be `string` type → use as-is
+
+---
+
+## React SDK Components
+
+### Dashboards
+
+#### StaticDashboard
+Lightweight, view-only dashboard.
+
+```tsx
+import { StaticDashboard } from "@metabase/embedding-sdk-react";
+
+<StaticDashboard
+ dashboardId={123}
+ withTitle={true}
+ withDownloads={false}
+ initialParameters={{ productId: 42 }}
+ hiddenParameters={["category"]}
+/>
+```
+
+#### InteractiveDashboard
+Dashboard with drill-downs, click behaviors, and question navigation.
+
+```tsx
+import { InteractiveDashboard } from "@metabase/embedding-sdk-react";
+
+<InteractiveDashboard
+ dashboardId={123}
+ withTitle={true}
+ withDownloads={true}
+ plugins={{
+ dashboardCardMenu: {
+ withDownloads: true,
+ withEditLink: false,
+ customItems: [
+ {
+ label: "Custom Action",
+ icon: "info",
+ action: (question) => console.log(question)
+ }
+ ]
+ }
+ }}
+/>
+```
+
+#### EditableDashboard
+Fully editable dashboard with add/edit/layout capabilities.
+
+```tsx
+import { EditableDashboard } from "@metabase/embedding-sdk-react";
+
+<EditableDashboard
+ dashboardId={123}
+ onSave={(dashboard) => console.log("Saved:", dashboard)}
+/>
+```
+
+### Questions
+
+#### StaticQuestion
+Lightweight, view-only question/chart.
+
+```tsx
+import { StaticQuestion } from "@metabase/embedding-sdk-react";
+
+<StaticQuestion
+ questionId={456}
+ height="400px"
+ initialSqlParameters={{ productId: 42 }} // For SQL questions only
+/>
+```
+
+#### InteractiveQuestion
+Question with filters, summarize, drill-through, and query builder.
+
+```tsx
+import { InteractiveQuestion } from "@metabase/embedding-sdk-react";
+
+// Default layout
+<InteractiveQuestion questionId={456} />
+
+// Custom layout with namespaced components
+<InteractiveQuestion questionId={456}>
+ <InteractiveQuestion.Title />
+ <InteractiveQuestion.Filter />
+ <InteractiveQuestion.Summarize />
+ <InteractiveQuestion.QuestionVisualization />
+ <InteractiveQuestion.SaveButton />
+</InteractiveQuestion>
+```
+
+#### Query Builder (New Question)
+
+```tsx
+<InteractiveQuestion questionId="new">
+ <InteractiveQuestion.Editor />
+ <InteractiveQuestion.QuestionVisualization />
+ <InteractiveQuestion.SaveButton />
+</InteractiveQuestion>
+```
+
+### AI Chat (Metabot)
+
+Embed AI-powered natural language querying.
+
+```tsx
+import { MetabotQuestion } from "@metabase/embedding-sdk-react";
+
+<MetabotQuestion
+ collectionId={7} // Scope AI to specific collection
+ layout="sidebar" // "auto" | "stacked" | "sidebar"
+/>
+```
+
+### Collection Browser
+
+Let users navigate and explore Metabase collections.
+
+```tsx
+import { CollectionBrowser } from "@metabase/embedding-sdk-react";
+
+<CollectionBrowser
+ initialCollectionId="root"
+ readOnly={false}
+ visibleEntityTypes={["dashboard", "question"]}
+/>
+```
+
+### Create Dashboard Modal
+
+```tsx
+import { CreateDashboardModal } from "@metabase/embedding-sdk-react";
+
+<CreateDashboardModal
+ collectionId={7}
+ onClose={() => setIsOpen(false)}
+ onCreate={(dashboard) => console.log("Created:", dashboard)}
+/>
+```
+
+---
+
+## Web Component Reference
+
+### Dashboard Component
+
+```html
+<metabase-dashboard
+ dashboard-id="1" <!-- Required: ID or entity ID -->
+ with-title="true" <!-- Show title (default: true) -->
+ with-downloads="false" <!-- Enable downloads (default: false) -->
+ drills="true" <!-- Enable drill-through (default: true) -->
+ with-subscriptions="false" <!-- Enable subscriptions -->
+ refresh="60" <!-- Auto-refresh in seconds -->
+ initial-parameters='{"productId": "42"}'
+ hidden-parameters='["category"]'
+></metabase-dashboard>
+```
+
+### Question Component
+
+```html
+<metabase-question
+ question-id="5" <!-- Required: ID or entity ID, or "new" -->
+ with-title="true" <!-- Show title (default: true) -->
+ with-downloads="false" <!-- Enable downloads (default: false) -->
+ drills="true" <!-- Enable drill-through (default: true) -->
+ initial-sql-parameters='{"productId": "42"}' <!-- SQL questions only -->
+ is-save-enabled="false" <!-- Allow saving -->
+ target-collection="personal" <!-- Force save location -->
+></metabase-question>
+```
+
+### Browser Component
+
+```html
+<metabase-browser
+ initial-collection="root" <!-- Required: collection ID or "root" -->
+ read-only="false" <!-- Allow create/edit (default: true) -->
+></metabase-browser>
+```
+
+### AI Chat Component
+
+```html
+<metabase-metabot
+ layout="auto" <!-- "auto" | "stacked" | "sidebar" -->
+></metabase-metabot>
+```
+
+---
+
+## Theming and Appearance
+
+### Complete Theme Object
+
+```javascript
+{
+ fontFamily: "Lato", // or "Custom" for Metabase custom font
+ fontSize: "16px",
+ lineHeight: 1.5,
+
+ colors: {
+ // Primary colors
+ brand: "#9B5966",
+ "brand-hover": "#DDECFA",
+ "brand-hover-light": "#EEF6FC",
+
+ // Text colors
+ "text-primary": "#4C5773",
+ "text-secondary": "#696E7B",
+ "text-tertiary": "#949AAB",
+
+ // Background colors
+ background: "#FFFFFF",
+ "background-light": "#F0F2F5",
+ "background-secondary": "#EDF2F5",
+ "background-hover": "#F9FBFC",
+ "background-disabled": "#F3F5F7",
+
+ // UI elements
+ border: "#EEECEC",
+ filter: "#7172AD",
+ summarize: "#88BF4D",
+ positive: "#BADC58",
+ negative: "#FF7979",
+ focus: "#CAE1F7",
+ shadow: "rgba(0,0,0,0.08)",
+
+ // Chart colors (up to 8)
+ charts: [
+ "#9B59B6",
+ { base: "#E74C3C", tint: "#EE6B56", shade: "#CB4436" }
+ ]
+ },
+
+ components: {
+ dashboard: {
+ backgroundColor: "#2F3640",
+ gridBorderColor: "#EEECEC",
+ card: {
+ backgroundColor: "#2D2D30",
+ border: "1px solid #EEECEC"
+ }
+ },
+
+ question: {
+ backgroundColor: "#2E353B",
+ toolbar: {
+ backgroundColor: "#F3F5F7"
+ }
+ },
+
+ tooltip: {
+ textColor: "#FFFFFF",
+ secondaryTextColor: "#949AAB",
+ backgroundColor: "#2E353B",
+ focusedBackgroundColor: "#0A0E10"
+ },
+
+ table: {
+ cell: {
+ textColor: "#4C5773",
+ backgroundColor: "#FFFFFF",
+ fontSize: "12.5px"
+ },
+ idColumn: {
+ textColor: "#9B5966",
+ backgroundColor: "#F5E9EB"
+ }
+ },
+
+ number: {
+ value: {
+ fontSize: "24px",
+ lineHeight: "21px"
+ }
+ },
+
+ cartesian: {
+ padding: "4px 8px"
+ },
+
+ pivotTable: {
+ cell: { fontSize: "12px" },
+ rowToggle: {
+ textColor: "#FFFFFF",
+ backgroundColor: "#95A5A6"
+ }
+ },
+
+ popover: {
+ zIndex: 4
+ }
+ }
+}
+```
+
+### Applying Themes
+
+#### Web Components
+
+```html
+<script>
+ defineMetabaseConfig({
+ instanceUrl: "https://your-metabase-url",
+ theme: {
+ colors: {
+ brand: "#9B5966",
+ background: "#FFFFFF"
+ }
+ }
+ });
+</script>
+```
+
+#### React SDK
+
+```tsx
+import { defineMetabaseTheme } from "@metabase/embedding-sdk-react";
+
+const theme = defineMetabaseTheme({
+ colors: {
+ brand: "#9B5966",
+ background: "#FFFFFF"
+ }
+});
+
+<MetabaseProvider theme={theme} authConfig={authConfig}>
+ {/* Your components */}
+</MetabaseProvider>
+```
+
+---
+
+## Plugins (React SDK Only)
+
+### Global Plugins
+
+Applied to all components via `MetabaseProvider`:
+
+```tsx
+<MetabaseProvider
+ authConfig={authConfig}
+ pluginsConfig={{
+ mapQuestionClickActions: (clickActions, dataPoint) => {
+ // Return custom actions or default actions
+ return [
+ ...clickActions,
+ {
+ name: "custom-action",
+ title: "Custom Action",
+ icon: "info",
+ action: () => console.log(dataPoint)
+ }
+ ];
+ },
+
+ handleLink: (url) => {
+ console.log("Link clicked:", url);
+ return false; // Prevent default
+ },
+
+ getNoDataIllustration: () => "data:image/svg+xml;base64,...",
+ getNoObjectIllustration: () => "data:image/svg+xml;base64,..."
+ }}
+>
+ {/* Your components */}
+</MetabaseProvider>
+```
+
+### Component-Level Plugins
+
+Applied to individual components:
+
+```tsx
+<InteractiveQuestion
+ questionId={456}
+ plugins={{
+ mapQuestionClickActions: (clickActions, dataPoint) => {
+ // Custom behavior for this question only
+ if (dataPoint.column.name === "Plan") {
+ return [{
+ name: "alert",
+ title: "Show Alert",
+ action: () => alert(dataPoint.value)
+ }];
+ }
+ return clickActions; // Default for other columns
+ }
+ }}
+/>
+```
+
+### Dashboard Card Menu Plugin
+
+```tsx
+<InteractiveDashboard
+ dashboardId={123}
+ plugins={{
+ dashboardCardMenu: {
+ withDownloads: true,
+ withEditLink: false,
+ customItems: [
+ {
+ label: "Export to CSV",
+ icon: "download",
+ action: (question) => {
+ // Custom export logic
+ console.log("Exporting:", question);
+ }
+ }
+ ]
+ }
+ }}
+/>
+```
+
+Or replace the entire menu:
+
+```tsx
+<InteractiveDashboard
+ dashboardId={123}
+ plugins={{
+ dashboardCardMenu: (question) => (
+ <CustomMenu question={question} />
+ )
+ }}
+/>
+```
+
+---
+
+## Setup Checklist
+
+### Metabase Configuration
+
+1. **Enable Modular Embedding**
+ - Go to **Admin Settings > Embedding**
+ - Toggle **Enable modular embedding** (for web components) or **Modular embedding SDK** (for React)
+
+2. **Configure CORS**
+ - Add allowed origins: `https://*.example.com`
+ - `localhost` is automatically included for development
+
+3. **SameSite Cookie Setting** (if embedding on different domain)
+ - Go to **Admin Settings > Embedding > Security**
+ - Set **SameSite cookie** to **None** (requires HTTPS)
+
+4. **Authentication Setup**
+ - **Development**: Create API key at **Settings > Authentication > API keys**
+ - **Production (JWT)**: Configure at **Settings > Authentication > JWT**
+ - **Production (SAML)**: Configure at **Settings > Authentication > SAML**
+
+### Application Setup
+
+#### Web Components
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+ <title>Embedded Analytics</title>
+</head>
+<body>
+ <!-- 1. Load embedding library -->
+ <script defer src="https://your-metabase-url/app/embed.js"></script>
+
+ <!-- 2. Configure -->
+ <script>
+ function defineMetabaseConfig(config) {
+ window.metabaseConfig = config;
+ }
+
+ defineMetabaseConfig({
+ instanceUrl: "https://your-metabase-url",
+ apiKey: "mb_dev_api_key" // For local testing
+ });
+ </script>
+
+ <!-- 3. Embed components -->
+ <metabase-dashboard dashboard-id="1"></metabase-dashboard>
+</body>
+</html>
+```
+
+#### React SDK
+
+```bash
+# 1. Install
+npm install @metabase/embedding-sdk-react@58-stable
+```
+
+```tsx
+// 2. Configure and embed
+import { MetabaseProvider, StaticDashboard } from "@metabase/embedding-sdk-react";
+
+function App() {
+ return (
+ <MetabaseProvider
+ authConfig={{ // ✅ authConfig NOT config
+ metabaseInstanceUrl: "https://your-metabase-url",
+ apiKey: "mb_dev_api_key"
+ }}
+ >
+ <StaticDashboard dashboardId={1} /> {/* ✅ number type */}
+ </MetabaseProvider>
+ );
+}
+```
+
+---
+
+## Common Patterns
+
+### Multi-Tenant Analytics with Data Segregation
+
+```javascript
+// Backend: Sign JWT with user's group
+const token = jwt.sign(
+ {
+ email: user.email,
+ groups: [user.tenantId], // e.g., "tenant_123"
+ exp: Math.round(Date.now() / 1000) + 60 * 10
+ },
+ METABASE_JWT_SHARED_SECRET
+);
+```
+
+In Metabase, configure [data sandboxing](https://www.metabase.com/docs/latest/permissions/data-sandboxes) to filter data based on `groups`.
+
+### Custom JWT Fetch (Only When You Need Custom Headers)
+
+**⚠️ Only use this pattern if you need custom headers or auth. Most apps don't need this.**
+
+```tsx
+import { defineMetabaseAuthConfig } from "@metabase/embedding-sdk-react";
+
+// Only add fetchRequestToken if you need custom headers/auth
+const authConfig = defineMetabaseAuthConfig({
+ metabaseInstanceUrl: "https://your-metabase-url",
+ fetchRequestToken: async () => {
+ const response = await fetch("https://your-backend/sso/metabase", {
+ method: "GET",
+ credentials: "include", // For cookies
+ headers: {
+ "Authorization": `Bearer ${yourAuthToken}` // Custom header
+ }
+ // SDK automatically adds ?response=json query param
+ });
+ return await response.json(); // { jwt: "..." }
+ }
+});
+```
+
+### Dynamic Parameters
+
+```tsx
+const [productId, setProductId] = useState(42);
+
+<InteractiveDashboard
+ dashboardId={123} // ✅ number type
+ initialParameters={{ productId }} // ✅ values can be any type
+/>
+```
+
+### Parsing IDs from URL Parameters
+
+```tsx
+import { useSearchParams } from "react-router-dom";
+
+function DashboardPage() {
+ const [searchParams] = useSearchParams();
+
+ // ✅ CORRECT - Parse numeric IDs to integers
+ const dashboardId = parseInt(searchParams.get("id"), 10);
+
+ // ❌ WRONG - Don't pass string IDs for numeric dashboards
+ // const dashboardId = searchParams.get("id"); // "123" won't work!
+
+ return <InteractiveDashboard dashboardId={dashboardId} />;
+}
+```
+
+### Guest Embed with Locked Parameters
+
+```javascript
+// Backend: Lock parameters to prevent tampering
+const payload = {
+ resource: { dashboard: 10 },
+ params: {
+ // User can't change these
+ tenant_id: user.tenantId,
+ // User can change these
+ date_range: null
+ },
+ exp: Math.round(Date.now() / 1000) + 10 * 60
+};
+```
+
+### Checking Authentication Status
+
+```tsx
+import { useMetabaseAuthStatus } from "@metabase/embedding-sdk-react";
+
+function MyComponent() {
+ const { status, user } = useMetabaseAuthStatus();
+
+ if (status === "loading") return <Spinner />;
+ if (status === "error") return <Error />;
+ if (status === "success") return <Dashboard user={user} />;
+}
+```
+
+### Custom Loading and Error Components
+
+```tsx
+const CustomLoader = () => <div>Loading analytics...</div>;
+const CustomError = ({ error }) => <div>Error: {error.message}</div>;
+
+<MetabaseProvider
+ authConfig={authConfig}
+ loaderComponent={CustomLoader}
+ errorComponent={CustomError}
+>
+ {/* Your components */}
+</MetabaseProvider>
+```
+
+---
+
+## SDK Hooks
+
+### useMetabaseAuthStatus
+Get current authentication status.
+
+```tsx
+const { status, user } = useMetabaseAuthStatus();
+// status: "loading" | "success" | "error"
+// user: { id, email, first_name, last_name, groups }
+```
+
+### useCurrentUser
+Get current authenticated user.
+
+```tsx
+const user = useCurrentUser();
+// Returns: { id, email, first_name, last_name, groups }
+```
+
+### useCreateDashboardApi
+Programmatically create dashboards.
+
+```tsx
+const createDashboard = useCreateDashboardApi();
+
+const handleCreate = async () => {
+ const dashboard = await createDashboard({
+ name: "New Dashboard",
+ description: "Description",
+ collection_id: 7
+ });
+ console.log("Created:", dashboard);
+};
+```
+
+### useApplicationName
+Get Metabase instance name.
+
+```tsx
+const appName = useApplicationName();
+```
+
+### useAvailableFonts
+Get available fonts in Metabase.
+
+```tsx
+const fonts = useAvailableFonts();
+```
+
+---
+
+## Versioning
+
+**Critical**: Use npm dist-tag matching your Metabase version.
+
+| Metabase Version | npm Install Command |
+|------------------|---------------------|
+| 1.58.x | `npm install @metabase/embedding-sdk-react@58-stable` |
+| 1.57.x | `npm install @metabase/embedding-sdk-react@57-stable` |
+| 1.56.x | `npm install @metabase/embedding-sdk-react@56-stable` |
+| 1.55.x | `npm install @metabase/embedding-sdk-react@55-stable` |
+| 1.54.x | `npm install @metabase/embedding-sdk-react@54-stable` |
+
+Starting with Metabase 57, the SDK uses a two-part architecture:
+- **SDK Package**: Lightweight npm package (`@metabase/embedding-sdk-react`)
+- **SDK Bundle**: Full SDK code served from your Metabase instance
+
+This ensures version compatibility between SDK and Metabase.
+
+---
+
+## Limitations
+
+### SDK Limitations
+- No server-side rendering (SSR)
+- No verified content or official collections
+- No subscriptions or alerts in SDK components
+- No custom click behavior destinations to other Metabase items
+- Only one interactive dashboard per page (multiple static dashboards OK)
+- Leaflet 1.x compatibility issues (use Leaflet 2.x)
+
+### Guest Embed Limitations
+- No drill-through or click actions
+- No query builder
+- No AI chat
+- No row/column-level security (use locked parameters instead)
+- No usage analytics
+
+---
+
+## Security Best Practices
+
+1. **Never share Metabase accounts**
+ - Each end-user must have their own account (for SSO embeds)
+ - Session tokens can be used to access Metabase API directly
+
+2. **Never hardcode secrets**
+ - API keys and JWT secrets belong on backend only
+ - Fetch tokens dynamically from your server
+
+3. **Use data sandboxing**
+ - Configure [row-level permissions](https://www.metabase.com/docs/latest/permissions/data-sandboxes) in Metabase
+ - Map user groups to data filters
+
+4. **Validate JWT payloads**
+ - Always validate exp (expiration)
+ - Keep expiration short (10-15 minutes)
+
+5. **Secure CORS**
+ - Only allow specific origins
+ - Never use wildcard (`*`) in production
+
+6. **HTTPS required**
+ - SameSite=None cookies require HTTPS
+ - Use HTTPS for all production embeds
+
+---
+
+## Troubleshooting
+
+### "Failed to fetch" errors
+- Check CORS configuration in Metabase
+- Verify `instanceUrl` matches your Metabase domain exactly
+- Check browser console for specific CORS errors
+
+### Authentication failures
+- Verify JWT signature matches secret key
+- Check JWT expiration hasn't passed
+- Ensure user exists in Metabase with correct email
+- Check groups match Metabase group names
+
+### Components not rendering
+- Ensure `MetabaseProvider` wraps all SDK components
+- Check IDs are correct (numeric IDs must be `number` type, not strings)
+- Parse URL parameters with `parseInt(value, 10)` for numeric IDs
+- Verify user has permissions to view the item
+- Check browser console for errors
+
+### TypeScript errors about ID types
+```tsx
+// ❌ WRONG
+const id = "123"; // string
+<StaticDashboard dashboardId={id} /> // Type error!
+
+// ✅ CORRECT
+const id = 123; // number
+<StaticDashboard dashboardId={id} />
+
+// ✅ CORRECT - Parse from URL
+const id = parseInt(urlParams.get("id"), 10);
+<StaticDashboard dashboardId={id} />
+```
+
+### Theme not applying
+- Colors must be valid CSS color values
+- Component-level styles override global theme
+- Visualization settings in Metabase override theme
+
+### Cross-domain issues
+- Set SameSite=None in Metabase settings
+- Use HTTPS (required for SameSite=None)
+- Safari may require "Allow cross-site tracking"
+
+---
+
+## Resources
+
+- **Live Demo**: [Shoppy Demo App](https://metaba.se/sdk-demo)
+- **Sample Code**: [Shoppy Source](https://github.com/metabase/shoppy)
+- **Sample App**: [Embedding Sample](https://github.com/metabase/modular-embedding-sample-app)
+- **SDK on npm**: [metaba.se/sdk-npm](https://metaba.se/sdk-npm)
+- **Documentation**: [Metabase Embedding Docs](https://www.metabase.com/docs/latest/embedding/introduction)
+- **Bug Reports**: [GitHub Issues](https://github.com/metabase/metabase/issues)
+- **Community**: [Discourse Forums](https://discourse.metabase.com/)
+
+---
+
+## Architecture Notes
+
+### Web Components Architecture
+- Metabase serves `embed.js` from your instance
+- Custom elements: `<metabase-dashboard>`, `<metabase-question>`, etc.
+- Framework-agnostic (works with any web stack)
+
+### React SDK Architecture (v57+)
+- **SDK Package** (`@metabase/embedding-sdk-react`): Lightweight bootstrapper
+- **SDK Bundle**: Full code served from Metabase instance
+- Ensures SDK always matches Metabase version
+
+### Authentication Flow (JWT)
+1. User accesses your app
+2. Your app sends request to your backend
+3. Backend generates signed JWT with user info
+4. Backend returns `{ jwt: "..." }` to frontend
+5. SDK sends JWT to Metabase
+6. Metabase validates signature and creates session
+7. Session cookie enables subsequent API calls
+
+### Entity IDs vs Numeric IDs
+- **Numeric IDs**: `dashboardId={123}` - Changes when importing/exporting
+- **Entity IDs**: `dashboardId="abc123def"` - Stable across environments
+- Use Entity IDs for production embeds that sync across instances
+
+---
+
+## Quick Reference
+
+### ⚠️ Deprecated Fields - DO NOT USE
+```
+authProviderUri - REMOVED: Configure JWT endpoint in Metabase admin instead
+jwtProviderUri - REMOVED: Configure JWT endpoint in Metabase admin instead
+config (MetabaseProvider) - REMOVED: Use authConfig prop instead
+```
+
+### Essential Web Component Attributes
+```
+dashboard-id, question-id - Required: resource identifier
+with-title - Boolean: show/hide title
+with-downloads - Boolean: enable/disable downloads
+drills - Boolean: enable/disable drill-through
+initial-parameters - JSON: default filter values
+hidden-parameters - Array: filters to hide
+token - String: JWT for guest embeds
+refresh - Number: auto-refresh interval (seconds)
+```
+
+### Essential SDK Props
+```
+dashboardId, questionId - Required: number (not string!) or entity ID string
+ ⚠️ Parse URL params: parseInt(value, 10)
+withTitle - Boolean: show/hide title
+withDownloads - Boolean: enable/disable downloads
+initialParameters - Object: default filter values
+hiddenParameters - Array: filters to hide
+isSaveEnabled - Boolean: allow saving
+targetCollection - String/Number: force save location
+plugins - Object: plugin configuration
+```
+
+### Essential MetabaseProvider Props
+```
+authConfig - Required: authentication config (NOT "config")
+theme - Object: theme configuration
+pluginsConfig - Object: global plugins
+loaderComponent - Component: custom loader
+errorComponent - Component: custom error display
+```
+
+**⚠️ DEPRECATED Props (DO NOT USE):**
+```
+config - DEPRECATED: Use authConfig instead
+```
+
+---
+
+## Entity ID Usage Pattern
+
+```tsx
+// Get entity ID from Metabase
+// Admin > Tools > Model Caching > Click info icon on any item
+
+// Use in embeds (stable across environments)
+<StaticDashboard dashboardId="abc123def456" />
+<StaticQuestion questionId="xyz789ghi012" />
+```
+
+---
+
+## Example: Complete Production Setup
+
+**⚠️ Note:** This example shows `fetchRequestToken` for demonstration, but most apps using cookie-based auth don't need it. Only add `fetchRequestToken` if you need custom headers.
+
+### Backend (Express.js)
+
+```javascript
+const express = require("express");
+const jwt = require("jsonwebtoken");
+const cors = require("cors");
+
+const app = express();
+
+// CORS for SDK requests
+app.use(cors({
+ origin: "https://your-app.com",
+ credentials: true
+}));
+
+// JWT endpoint
+app.get("/sso/metabase", async (req, res) => {
+ const user = await getCurrentUser(req);
+
+ const token = jwt.sign(
+ {
+ email: user.email,
+ first_name: user.firstName,
+ last_name: user.lastName,
+ groups: [`tenant_${user.tenantId}`],
+ exp: Math.round(Date.now() / 1000) + 60 * 10
+ },
+ process.env.METABASE_JWT_SECRET
+ );
+
+ if (req.query.response === "json") {
+ res.json({ jwt: token });
+ } else {
+ res.redirect(`${process.env.METABASE_URL}/auth/sso?token=true&jwt=${token}`);
+ }
+});
+
+app.listen(3001);
+```
+
+### Frontend (React)
+
+```tsx
+import {
+ MetabaseProvider,
+ InteractiveDashboard,
+ defineMetabaseAuthConfig
+} from "@metabase/embedding-sdk-react";
+
+// ✅ CORRECT - Default (no fetchRequestToken needed for cookie-based auth)
+const authConfig = defineMetabaseAuthConfig({
+ metabaseInstanceUrl: "https://metabase.company.com"
+});
+
+// Or if you need custom headers:
+// const authConfig = defineMetabaseAuthConfig({
+// metabaseInstanceUrl: "https://metabase.company.com",
+// fetchRequestToken: async () => {
+// const response = await fetch("https://api.company.com/sso/metabase", {
+// credentials: "include",
+// headers: { "Authorization": `Bearer ${token}` }
+// });
+// return await response.json();
+// }
+// });
+
+function Analytics() {
+ return (
+ <MetabaseProvider authConfig={authConfig}> {/* ✅ authConfig NOT config */}
+ <InteractiveDashboard dashboardId="abc123def" /> {/* ✅ Entity ID (string) */}
+ </MetabaseProvider>
+ );
+}
+```
+
+### Metabase Configuration
+
+1. **JWT Setup** (Admin > Authentication > JWT)
+ - JWT Identity Provider URI: `https://api.company.com/sso/metabase`
+ - String used by Metabase to encode: `[Copy shared secret from backend]`
+
+2. **Embedding** (Admin > Embedding)
+ - Enable modular embedding SDK: ✓
+ - Authorized origins: `https://your-app.com`
+
+3. **SameSite Cookie** (Admin > Embedding > Security)
+ - SameSite cookie setting: None
+
+4. **Data Permissions** (Admin > Permissions > Data)
+ - Create groups: `tenant_123`, `tenant_456`, etc.
+ - Configure data sandboxes per group
+
+---
+
+*Last Updated: December 2025*
+*Metabase Version: 1.58+*
\ No newline at end of file
diff --git a/docs/llms.txt b/docs/llms.txt
index e7f13671d69..3de079fde03 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -1,1264 +1,6 @@
-# Metabase Modular Embedding Reference
+# Metabase
-> Complete guide for embedding Metabase charts, dashboards, query builder, and AI chat into your applications.
+Links to `llms.txt` files for Metabase. These files contains the full documentation and guide for AI agents on these Metabase-related topics:
-## Overview
+- [Embedding Metabase with Modular Embedding](./embedding/llms.txt)
-Metabase offers two primary ways to embed analytics:
-
-1. **Modular Embedding JS** - Embed individual components (dashboards, questions, query builder, AI chat) with full customization
-2. **Modular Embedding SDK** - React SDK for advanced embedding with custom layouts and plugins
-
-### When to Use Modular Embedding
-
-- **SSO Embeds**: Multi-tenant self-service analytics with drill-through, query builder, and AI chat. Requires JWT or SAML authentication.
-- **Guest Embeds**: Simple, secure charts and dashboards without SSO. View-only with locked parameters for data filtering.
-
-### Feature Comparison
-
-| Feature | SSO | Guest | SDK |
-|---------|-----|-------|-----|
-| Charts & Dashboards | ✅ | ✅ | ✅ |
-| Drill-through | ✅ | ❌ | ✅ |
-| Query Builder | ✅ | ❌ | ✅ |
-| AI Chat (Metabot) | ✅ | ❌ | ✅ |
-| Collection Browser | ✅ | ❌ | ✅ |
-| Advanced Theming | ✅ | ❌ | ✅ |
-| Custom Layouts | ❌ | ❌ | ✅ |
-| Plugins | ❌ | ❌ | ✅ |
-| Data Permissions | ✅ | ❌ | ✅ |
-
----
-
-## Quick Start Paths
-
-### Path 1: Simple Web Components (No React Required)
-
-Best for: Adding analytics to any web app with minimal code.
-
-```html
-<!-- Load embedding library -->
-<script defer src="https://your-metabase-url/app/embed.js"></script>
-
-<script>
- defineMetabaseConfig({
- instanceUrl: "https://your-metabase-url",
- apiKey: "mb_dev_api_key", // For local testing only
- theme: {
- colors: {
- brand: "#9B5966",
- background: "#FFFFFF"
- }
- }
- });
-</script>
-
-<!-- Embed a dashboard -->
-<metabase-dashboard dashboard-id="1" with-title="true"></metabase-dashboard>
-
-<!-- Embed a question -->
-<metabase-question question-id="5"></metabase-question>
-```
-
-### Path 2: React SDK (Advanced)
-
-Best for: React apps needing custom layouts, plugins, and full control.
-
-```bash
-# Install (use dist-tag matching your Metabase version)
-npm install @metabase/embedding-sdk-react@58-stable
-```
-
-```tsx
-import { MetabaseProvider, StaticDashboard } from "@metabase/embedding-sdk-react";
-
-function App() {
- return (
- <MetabaseProvider
- authConfig={{
- metabaseInstanceUrl: "https://your-metabase-url",
- apiKey: "mb_dev_api_key" // For local testing only
- }}
- >
- <StaticDashboard dashboardId={1} />
- </MetabaseProvider>
- );
-}
-```
-
----
-
-## Authentication
-
-### Development: API Keys (localhost only)
-
-```javascript
-// Web components
-defineMetabaseConfig({
- instanceUrl: "https://your-metabase-url",
- apiKey: "mb_your_api_key"
-});
-
-// React SDK
-authConfig={{
- metabaseInstanceUrl: "https://your-metabase-url",
- apiKey: "mb_your_api_key"
-}}
-```
-
-**⚠️ API keys only work on localhost and should never be used in production.**
-
-### Production: JWT SSO (Requires Pro/Enterprise)
-
-**⚠️ Important:** The SDK automatically uses the JWT endpoint configured in Metabase Admin settings. You don't need `fetchRequestToken` unless you require custom headers/auth.
-
-#### Backend Setup (Node.js example)
-
-```javascript
-const jwt = require("jsonwebtoken");
-
-app.get("/sso/metabase", async (req, res) => {
- const user = getCurrentUser(req);
-
- const token = jwt.sign(
- {
- email: user.email,
- first_name: user.firstName,
- last_name: user.lastName,
- groups: [user.group],
- exp: Math.round(Date.now() / 1000) + 60 * 10 // 10 min expiration
- },
- METABASE_JWT_SHARED_SECRET
- );
-
- // For SDK requests (check for response=json query param)
- if (req.query.response === "json") {
- res.status(200).json({ jwt: token });
- } else {
- // For full app embedding
- const ssoUrl = `${METABASE_INSTANCE_URL}/auth/sso?token=true&jwt=${token}`;
- res.redirect(ssoUrl);
- }
-});
-```
-
-#### Frontend Configuration
-
-```tsx
-// React SDK
-import { defineMetabaseAuthConfig } from "@metabase/embedding-sdk-react";
-
-// ✅ CORRECT - Default setup (works for most cases)
-const authConfig = defineMetabaseAuthConfig({
- metabaseInstanceUrl: "https://your-metabase-url"
- // SDK automatically uses JWT endpoint configured in Metabase admin
- // No fetchRequestToken needed!
-});
-
-// ❌ DEPRECATED - DO NOT USE
-const authConfig = defineMetabaseAuthConfig({
- metabaseInstanceUrl: "https://your-metabase-url",
- authProviderUri: "..." // REMOVED - configure in Metabase admin instead
-});
-```
-
-### Production: SAML SSO (Requires Enterprise)
-
-```tsx
-const authConfig = defineMetabaseAuthConfig({
- metabaseInstanceUrl: "https://your-metabase-url",
- preferredAuthMethod: "saml"
-});
-```
-
-### Guest Embeds (No User Accounts Required)
-
-Backend generates signed JWT tokens containing resource ID and locked parameters:
-
-```javascript
-const jwt = require("jsonwebtoken");
-
-const payload = {
- resource: { dashboard: 10 }, // or { question: 5 }
- params: { category: ["Gizmo"] }, // Locked parameters
- exp: Math.round(Date.now() / 1000) + 10 * 60
-};
-
-const token = jwt.sign(payload, METABASE_SECRET_KEY);
-```
-
-Frontend:
-
-```html
-<script>
- defineMetabaseConfig({
- isGuest: true,
- instanceUrl: "https://your-metabase-url"
- });
-</script>
-
-<metabase-dashboard token="YOUR_JWT_TOKEN"></metabase-dashboard>
-```
-
-**⚠️ Never hardcode tokens in HTML. Fetch from your backend dynamically.**
-
-## ⚠️ Common Gotchas for Code Generation
-
-### 1. Deprecated Props (DO NOT USE)
-- ❌ `authProviderUri` - DEPRECATED, remove from all code
-- ❌ `jwtProviderUri` - DEPRECATED, remove from all code
-- ❌ `config` prop on MetabaseProvider - DEPRECATED, use `authConfig` instead
-
-### 2. fetchRequestToken Usually Not Needed
-**DON'T add `fetchRequestToken` unless explicitly needed for custom headers/auth.**
-
-The SDK automatically fetches tokens from the JWT endpoint configured in Metabase Admin settings. Adding `fetchRequestToken` unnecessarily can break backend code that handles legacy interactive embedding redirects, especially if you forget to pass `response=json` in the request.
-
-**Only use `fetchRequestToken` when:**
-- You need custom headers (e.g., `Authorization: Bearer ${token}`)
-- You need custom fetch logic beyond the default
-
-**Default behavior (works for most cases):**
-```tsx
-const authConfig = defineMetabaseAuthConfig({
- metabaseInstanceUrl: "https://your-metabase-url"
- // No fetchRequestToken needed - SDK uses admin-configured JWT endpoint
-});
-```
-
-**Custom fetchRequestToken (only when needed):**
-```tsx
-const authConfig = defineMetabaseAuthConfig({
- metabaseInstanceUrl: "https://your-metabase-url",
- fetchRequestToken: async () => {
- const response = await fetch("https://your-backend/sso/metabase", {
- headers: { "Authorization": `Bearer ${yourToken}` }
- // SDK adds ?response=json automatically
- });
- return await response.json();
- }
-});
-```
-
-### 3. Numeric IDs Must Be Integers, Not Strings
-**ALWAYS parse URL parameters and strings to integers using `parseInt()`.**
-
-```tsx
-// ❌ WRONG - String IDs will cause errors
-const dashboardId = searchParams.get("id"); // "123" (string)
-<StaticDashboard dashboardId={dashboardId} /> // ERROR!
-
-// ✅ CORRECT - Parse to integer
-const dashboardId = parseInt(searchParams.get("id"), 10); // 123 (number)
-<StaticDashboard dashboardId={dashboardId} /> // Works!
-
-// ✅ Also works with entity IDs (strings starting with letters)
-const dashboardId = searchParams.get("id"); // "abc123def"
-<StaticDashboard dashboardId={dashboardId} /> // Works!
-```
-
-**Rule of thumb:**
-- Numeric IDs (e.g., `123`): Must be `number` type → use `parseInt(value, 10)`
-- Entity IDs (e.g., `"abc123def"`): Must be `string` type → use as-is
-
----
-
-## React SDK Components
-
-### Dashboards
-
-#### StaticDashboard
-Lightweight, view-only dashboard.
-
-```tsx
-import { StaticDashboard } from "@metabase/embedding-sdk-react";
-
-<StaticDashboard
- dashboardId={123}
- withTitle={true}
- withDownloads={false}
- initialParameters={{ productId: 42 }}
- hiddenParameters={["category"]}
-/>
-```
-
-#### InteractiveDashboard
-Dashboard with drill-downs, click behaviors, and question navigation.
-
-```tsx
-import { InteractiveDashboard } from "@metabase/embedding-sdk-react";
-
-<InteractiveDashboard
- dashboardId={123}
- withTitle={true}
- withDownloads={true}
- plugins={{
- dashboardCardMenu: {
- withDownloads: true,
- withEditLink: false,
- customItems: [
- {
- label: "Custom Action",
- icon: "info",
- action: (question) => console.log(question)
- }
- ]
- }
- }}
-/>
-```
-
-#### EditableDashboard
-Fully editable dashboard with add/edit/layout capabilities.
-
-```tsx
-import { EditableDashboard } from "@metabase/embedding-sdk-react";
-
-<EditableDashboard
- dashboardId={123}
- onSave={(dashboard) => console.log("Saved:", dashboard)}
-/>
-```
-
-### Questions
-
-#### StaticQuestion
-Lightweight, view-only question/chart.
-
-```tsx
-import { StaticQuestion } from "@metabase/embedding-sdk-react";
-
-<StaticQuestion
- questionId={456}
- height="400px"
- initialSqlParameters={{ productId: 42 }} // For SQL questions only
-/>
-```
-
-#### InteractiveQuestion
-Question with filters, summarize, drill-through, and query builder.
-
-```tsx
-import { InteractiveQuestion } from "@metabase/embedding-sdk-react";
-
-// Default layout
-<InteractiveQuestion questionId={456} />
-
-// Custom layout with namespaced components
-<InteractiveQuestion questionId={456}>
- <InteractiveQuestion.Title />
- <InteractiveQuestion.Filter />
- <InteractiveQuestion.Summarize />
- <InteractiveQuestion.QuestionVisualization />
- <InteractiveQuestion.SaveButton />
-</InteractiveQuestion>
-```
-
-#### Query Builder (New Question)
-
-```tsx
-<InteractiveQuestion questionId="new">
- <InteractiveQuestion.Editor />
- <InteractiveQuestion.QuestionVisualization />
- <InteractiveQuestion.SaveButton />
-</InteractiveQuestion>
-```
-
-### AI Chat (Metabot)
-
-Embed AI-powered natural language querying.
-
-```tsx
-import { MetabotQuestion } from "@metabase/embedding-sdk-react";
-
-<MetabotQuestion
- collectionId={7} // Scope AI to specific collection
- layout="sidebar" // "auto" | "stacked" | "sidebar"
-/>
-```
-
-### Collection Browser
-
-Let users navigate and explore Metabase collections.
-
-```tsx
-import { CollectionBrowser } from "@metabase/embedding-sdk-react";
-
-<CollectionBrowser
- initialCollectionId="root"
- readOnly={false}
- visibleEntityTypes={["dashboard", "question"]}
-/>
-```
-
-### Create Dashboard Modal
-
-```tsx
-import { CreateDashboardModal } from "@metabase/embedding-sdk-react";
-
-<CreateDashboardModal
- collectionId={7}
- onClose={() => setIsOpen(false)}
- onCreate={(dashboard) => console.log("Created:", dashboard)}
-/>
-```
-
----
-
-## Web Component Reference
-
-### Dashboard Component
-
-```html
-<metabase-dashboard
- dashboard-id="1" <!-- Required: ID or entity ID -->
- with-title="true" <!-- Show title (default: true) -->
- with-downloads="false" <!-- Enable downloads (default: false) -->
- drills="true" <!-- Enable drill-through (default: true) -->
- with-subscriptions="false" <!-- Enable subscriptions -->
- refresh="60" <!-- Auto-refresh in seconds -->
- initial-parameters='{"productId": "42"}'
- hidden-parameters='["category"]'
-></metabase-dashboard>
-```
-
-### Question Component
-
-```html
-<metabase-question
- question-id="5" <!-- Required: ID or entity ID, or "new" -->
- with-title="true" <!-- Show title (default: true) -->
- with-downloads="false" <!-- Enable downloads (default: false) -->
- drills="true" <!-- Enable drill-through (default: true) -->
- initial-sql-parameters='{"productId": "42"}' <!-- SQL questions only -->
- is-save-enabled="false" <!-- Allow saving -->
- target-collection="personal" <!-- Force save location -->
-></metabase-question>
-```
-
-### Browser Component
-
-```html
-<metabase-browser
- initial-collection="root" <!-- Required: collection ID or "root" -->
- read-only="false" <!-- Allow create/edit (default: true) -->
-></metabase-browser>
-```
-
-### AI Chat Component
-
-```html
-<metabase-metabot
- layout="auto" <!-- "auto" | "stacked" | "sidebar" -->
-></metabase-metabot>
-```
-
----
-
-## Theming and Appearance
-
-### Complete Theme Object
-
-```javascript
-{
- fontFamily: "Lato", // or "Custom" for Metabase custom font
- fontSize: "16px",
- lineHeight: 1.5,
-
- colors: {
- // Primary colors
- brand: "#9B5966",
- "brand-hover": "#DDECFA",
- "brand-hover-light": "#EEF6FC",
-
- // Text colors
- "text-primary": "#4C5773",
- "text-secondary": "#696E7B",
- "text-tertiary": "#949AAB",
-
- // Background colors
- background: "#FFFFFF",
- "background-light": "#F0F2F5",
- "background-secondary": "#EDF2F5",
- "background-hover": "#F9FBFC",
- "background-disabled": "#F3F5F7",
-
- // UI elements
- border: "#EEECEC",
- filter: "#7172AD",
- summarize: "#88BF4D",
- positive: "#BADC58",
- negative: "#FF7979",
- focus: "#CAE1F7",
- shadow: "rgba(0,0,0,0.08)",
-
- // Chart colors (up to 8)
- charts: [
- "#9B59B6",
- { base: "#E74C3C", tint: "#EE6B56", shade: "#CB4436" }
- ]
- },
-
- components: {
- dashboard: {
- backgroundColor: "#2F3640",
- gridBorderColor: "#EEECEC",
- card: {
- backgroundColor: "#2D2D30",
- border: "1px solid #EEECEC"
- }
- },
-
- question: {
- backgroundColor: "#2E353B",
- toolbar: {
- backgroundColor: "#F3F5F7"
- }
- },
-
- tooltip: {
- textColor: "#FFFFFF",
- secondaryTextColor: "#949AAB",
- backgroundColor: "#2E353B",
- focusedBackgroundColor: "#0A0E10"
- },
-
- table: {
- cell: {
- textColor: "#4C5773",
- backgroundColor: "#FFFFFF",
- fontSize: "12.5px"
- },
- idColumn: {
- textColor: "#9B5966",
- backgroundColor: "#F5E9EB"
- }
- },
-
- number: {
- value: {
- fontSize: "24px",
- lineHeight: "21px"
- }
- },
-
- cartesian: {
- padding: "4px 8px"
- },
-
- pivotTable: {
- cell: { fontSize: "12px" },
- rowToggle: {
- textColor: "#FFFFFF",
- backgroundColor: "#95A5A6"
- }
- },
-
- popover: {
- zIndex: 4
- }
- }
-}
-```
-
-### Applying Themes
-
-#### Web Components
-
-```html
-<script>
- defineMetabaseConfig({
- instanceUrl: "https://your-metabase-url",
- theme: {
- colors: {
- brand: "#9B5966",
- background: "#FFFFFF"
- }
- }
- });
-</script>
-```
-
-#### React SDK
-
-```tsx
-import { defineMetabaseTheme } from "@metabase/embedding-sdk-react";
-
-const theme = defineMetabaseTheme({
- colors: {
- brand: "#9B5966",
- background: "#FFFFFF"
- }
-});
-
-<MetabaseProvider theme={theme} authConfig={authConfig}>
- {/* Your components */}
-</MetabaseProvider>
-```
-
----
-
-## Plugins (React SDK Only)
-
-### Global Plugins
-
-Applied to all components via `MetabaseProvider`:
-
-```tsx
-<MetabaseProvider
- authConfig={authConfig}
- pluginsConfig={{
- mapQuestionClickActions: (clickActions, dataPoint) => {
- // Return custom actions or default actions
- return [
- ...clickActions,
- {
- name: "custom-action",
- title: "Custom Action",
- icon: "info",
- action: () => console.log(dataPoint)
- }
- ];
- },
-
- handleLink: (url) => {
- console.log("Link clicked:", url);
- return false; // Prevent default
- },
-
- getNoDataIllustration: () => "data:image/svg+xml;base64,...",
- getNoObjectIllustration: () => "data:image/svg+xml;base64,..."
- }}
->
- {/* Your components */}
-</MetabaseProvider>
-```
-
-### Component-Level Plugins
-
-Applied to individual components:
-
-```tsx
-<InteractiveQuestion
- questionId={456}
- plugins={{
- mapQuestionClickActions: (clickActions, dataPoint) => {
- // Custom behavior for this question only
- if (dataPoint.column.name === "Plan") {
- return [{
- name: "alert",
- title: "Show Alert",
- action: () => alert(dataPoint.value)
- }];
- }
- return clickActions; // Default for other columns
- }
- }}
-/>
-```
-
-### Dashboard Card Menu Plugin
-
-```tsx
-<InteractiveDashboard
- dashboardId={123}
- plugins={{
- dashboardCardMenu: {
- withDownloads: true,
- withEditLink: false,
- customItems: [
- {
- label: "Export to CSV",
- icon: "download",
- action: (question) => {
- // Custom export logic
- console.log("Exporting:", question);
- }
- }
- ]
- }
- }}
-/>
-```
-
-Or replace the entire menu:
-
-```tsx
-<InteractiveDashboard
- dashboardId={123}
- plugins={{
- dashboardCardMenu: (question) => (
- <CustomMenu question={question} />
- )
- }}
-/>
-```
-
----
-
-## Setup Checklist
-
-### Metabase Configuration
-
-1. **Enable Modular Embedding**
- - Go to **Admin Settings > Embedding**
- - Toggle **Enable modular embedding** (for web components) or **Modular embedding SDK** (for React)
-
-2. **Configure CORS**
- - Add allowed origins: `https://*.example.com`
- - `localhost` is automatically included for development
-
-3. **SameSite Cookie Setting** (if embedding on different domain)
- - Go to **Admin Settings > Embedding > Security**
- - Set **SameSite cookie** to **None** (requires HTTPS)
-
-4. **Authentication Setup**
- - **Development**: Create API key at **Settings > Authentication > API keys**
- - **Production (JWT)**: Configure at **Settings > Authentication > JWT**
- - **Production (SAML)**: Configure at **Settings > Authentication > SAML**
-
-### Application Setup
-
-#### Web Components
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
- <title>Embedded Analytics</title>
-</head>
-<body>
- <!-- 1. Load embedding library -->
- <script defer src="https://your-metabase-url/app/embed.js"></script>
-
- <!-- 2. Configure -->
- <script>
- function defineMetabaseConfig(config) {
- window.metabaseConfig = config;
- }
-
- defineMetabaseConfig({
- instanceUrl: "https://your-metabase-url",
- apiKey: "mb_dev_api_key" // For local testing
- });
- </script>
-
- <!-- 3. Embed components -->
- <metabase-dashboard dashboard-id="1"></metabase-dashboard>
-</body>
-</html>
-```
-
-#### React SDK
-
-```bash
-# 1. Install
-npm install @metabase/embedding-sdk-react@58-stable
-```
-
-```tsx
-// 2. Configure and embed
-import { MetabaseProvider, StaticDashboard } from "@metabase/embedding-sdk-react";
-
-function App() {
- return (
- <MetabaseProvider
- authConfig={{ // ✅ authConfig NOT config
- metabaseInstanceUrl: "https://your-metabase-url",
- apiKey: "mb_dev_api_key"
- }}
- >
- <StaticDashboard dashboardId={1} /> {/* ✅ number type */}
- </MetabaseProvider>
- );
-}
-```
-
----
-
-## Common Patterns
-
-### Multi-Tenant Analytics with Data Segregation
-
-```javascript
-// Backend: Sign JWT with user's group
-const token = jwt.sign(
- {
- email: user.email,
- groups: [user.tenantId], // e.g., "tenant_123"
- exp: Math.round(Date.now() / 1000) + 60 * 10
- },
- METABASE_JWT_SHARED_SECRET
-);
-```
-
-In Metabase, configure [data sandboxing](https://www.metabase.com/docs/latest/permissions/data-sandboxes) to filter data based on `groups`.
-
-### Custom JWT Fetch (Only When You Need Custom Headers)
-
-**⚠️ Only use this pattern if you need custom headers or auth. Most apps don't need this.**
-
-```tsx
-import { defineMetabaseAuthConfig } from "@metabase/embedding-sdk-react";
-
-// Only add fetchRequestToken if you need custom headers/auth
-const authConfig = defineMetabaseAuthConfig({
- metabaseInstanceUrl: "https://your-metabase-url",
- fetchRequestToken: async () => {
- const response = await fetch("https://your-backend/sso/metabase", {
- method: "GET",
- credentials: "include", // For cookies
- headers: {
- "Authorization": `Bearer ${yourAuthToken}` // Custom header
- }
- // SDK automatically adds ?response=json query param
- });
- return await response.json(); // { jwt: "..." }
- }
-});
-```
-
-### Dynamic Parameters
-
-```tsx
-const [productId, setProductId] = useState(42);
-
-<InteractiveDashboard
- dashboardId={123} // ✅ number type
- initialParameters={{ productId }} // ✅ values can be any type
-/>
-```
-
-### Parsing IDs from URL Parameters
-
-```tsx
-import { useSearchParams } from "react-router-dom";
-
-function DashboardPage() {
- const [searchParams] = useSearchParams();
-
- // ✅ CORRECT - Parse numeric IDs to integers
- const dashboardId = parseInt(searchParams.get("id"), 10);
-
- // ❌ WRONG - Don't pass string IDs for numeric dashboards
- // const dashboardId = searchParams.get("id"); // "123" won't work!
-
- return <InteractiveDashboard dashboardId={dashboardId} />;
-}
-```
-
-### Guest Embed with Locked Parameters
-
-```javascript
-// Backend: Lock parameters to prevent tampering
-const payload = {
- resource: { dashboard: 10 },
- params: {
- // User can't change these
- tenant_id: user.tenantId,
- // User can change these
- date_range: null
- },
- exp: Math.round(Date.now() / 1000) + 10 * 60
-};
-```
-
-### Checking Authentication Status
-
-```tsx
-import { useMetabaseAuthStatus } from "@metabase/embedding-sdk-react";
-
-function MyComponent() {
- const { status, user } = useMetabaseAuthStatus();
-
- if (status === "loading") return <Spinner />;
- if (status === "error") return <Error />;
- if (status === "success") return <Dashboard user={user} />;
-}
-```
-
-### Custom Loading and Error Components
-
-```tsx
-const CustomLoader = () => <div>Loading analytics...</div>;
-const CustomError = ({ error }) => <div>Error: {error.message}</div>;
-
-<MetabaseProvider
- authConfig={authConfig}
- loaderComponent={CustomLoader}
- errorComponent={CustomError}
->
- {/* Your components */}
-</MetabaseProvider>
-```
-
----
-
-## SDK Hooks
-
-### useMetabaseAuthStatus
-Get current authentication status.
-
-```tsx
-const { status, user } = useMetabaseAuthStatus();
-// status: "loading" | "success" | "error"
-// user: { id, email, first_name, last_name, groups }
-```
-
-### useCurrentUser
-Get current authenticated user.
-
-```tsx
-const user = useCurrentUser();
-// Returns: { id, email, first_name, last_name, groups }
-```
-
-### useCreateDashboardApi
-Programmatically create dashboards.
-
-```tsx
-const createDashboard = useCreateDashboardApi();
-
-const handleCreate = async () => {
- const dashboard = await createDashboard({
- name: "New Dashboard",
- description: "Description",
- collection_id: 7
- });
- console.log("Created:", dashboard);
-};
-```
-
-### useApplicationName
-Get Metabase instance name.
-
-```tsx
-const appName = useApplicationName();
-```
-
-### useAvailableFonts
-Get available fonts in Metabase.
-
-```tsx
-const fonts = useAvailableFonts();
-```
-
----
-
-## Versioning
-
-**Critical**: Use npm dist-tag matching your Metabase version.
-
-| Metabase Version | npm Install Command |
-|------------------|---------------------|
-| 1.58.x | `npm install @metabase/embedding-sdk-react@58-stable` |
-| 1.57.x | `npm install @metabase/embedding-sdk-react@57-stable` |
-| 1.56.x | `npm install @metabase/embedding-sdk-react@56-stable` |
-| 1.55.x | `npm install @metabase/embedding-sdk-react@55-stable` |
-| 1.54.x | `npm install @metabase/embedding-sdk-react@54-stable` |
-
-Starting with Metabase 57, the SDK uses a two-part architecture:
-- **SDK Package**: Lightweight npm package (`@metabase/embedding-sdk-react`)
-- **SDK Bundle**: Full SDK code served from your Metabase instance
-
-This ensures version compatibility between SDK and Metabase.
-
----
-
-## Limitations
-
-### SDK Limitations
-- No server-side rendering (SSR)
-- No verified content or official collections
-- No subscriptions or alerts in SDK components
-- No custom click behavior destinations to other Metabase items
-- Only one interactive dashboard per page (multiple static dashboards OK)
-- Leaflet 1.x compatibility issues (use Leaflet 2.x)
-
-### Guest Embed Limitations
-- No drill-through or click actions
-- No query builder
-- No AI chat
-- No row/column-level security (use locked parameters instead)
-- No usage analytics
-
----
-
-## Security Best Practices
-
-1. **Never share Metabase accounts**
- - Each end-user must have their own account (for SSO embeds)
- - Session tokens can be used to access Metabase API directly
-
-2. **Never hardcode secrets**
- - API keys and JWT secrets belong on backend only
- - Fetch tokens dynamically from your server
-
-3. **Use data sandboxing**
- - Configure [row-level permissions](https://www.metabase.com/docs/latest/permissions/data-sandboxes) in Metabase
- - Map user groups to data filters
-
-4. **Validate JWT payloads**
- - Always validate exp (expiration)
- - Keep expiration short (10-15 minutes)
-
-5. **Secure CORS**
- - Only allow specific origins
- - Never use wildcard (`*`) in production
-
-6. **HTTPS required**
- - SameSite=None cookies require HTTPS
- - Use HTTPS for all production embeds
-
----
-
-## Troubleshooting
-
-### "Failed to fetch" errors
-- Check CORS configuration in Metabase
-- Verify `instanceUrl` matches your Metabase domain exactly
-- Check browser console for specific CORS errors
-
-### Authentication failures
-- Verify JWT signature matches secret key
-- Check JWT expiration hasn't passed
-- Ensure user exists in Metabase with correct email
-- Check groups match Metabase group names
-
-### Components not rendering
-- Ensure `MetabaseProvider` wraps all SDK components
-- Check IDs are correct (numeric IDs must be `number` type, not strings)
-- Parse URL parameters with `parseInt(value, 10)` for numeric IDs
-- Verify user has permissions to view the item
-- Check browser console for errors
-
-### TypeScript errors about ID types
-```tsx
-// ❌ WRONG
-const id = "123"; // string
-<StaticDashboard dashboardId={id} /> // Type error!
-
-// ✅ CORRECT
-const id = 123; // number
-<StaticDashboard dashboardId={id} />
-
-// ✅ CORRECT - Parse from URL
-const id = parseInt(urlParams.get("id"), 10);
-<StaticDashboard dashboardId={id} />
-```
-
-### Theme not applying
-- Colors must be valid CSS color values
-- Component-level styles override global theme
-- Visualization settings in Metabase override theme
-
-### Cross-domain issues
-- Set SameSite=None in Metabase settings
-- Use HTTPS (required for SameSite=None)
-- Safari may require "Allow cross-site tracking"
-
----
-
-## Resources
-
-- **Live Demo**: [Shoppy Demo App](https://metaba.se/sdk-demo)
-- **Sample Code**: [Shoppy Source](https://github.com/metabase/shoppy)
-- **Sample App**: [Embedding Sample](https://github.com/metabase/modular-embedding-sample-app)
-- **SDK on npm**: [metaba.se/sdk-npm](https://metaba.se/sdk-npm)
-- **Documentation**: [Metabase Embedding Docs](https://www.metabase.com/docs/latest/embedding/introduction)
-- **Bug Reports**: [GitHub Issues](https://github.com/metabase/metabase/issues)
-- **Community**: [Discourse Forums](https://discourse.metabase.com/)
-
----
-
-## Architecture Notes
-
-### Web Components Architecture
-- Metabase serves `embed.js` from your instance
-- Custom elements: `<metabase-dashboard>`, `<metabase-question>`, etc.
-- Framework-agnostic (works with any web stack)
-
-### React SDK Architecture (v57+)
-- **SDK Package** (`@metabase/embedding-sdk-react`): Lightweight bootstrapper
-- **SDK Bundle**: Full code served from Metabase instance
-- Ensures SDK always matches Metabase version
-
-### Authentication Flow (JWT)
-1. User accesses your app
-2. Your app sends request to your backend
-3. Backend generates signed JWT with user info
-4. Backend returns `{ jwt: "..." }` to frontend
-5. SDK sends JWT to Metabase
-6. Metabase validates signature and creates session
-7. Session cookie enables subsequent API calls
-
-### Entity IDs vs Numeric IDs
-- **Numeric IDs**: `dashboardId={123}` - Changes when importing/exporting
-- **Entity IDs**: `dashboardId="abc123def"` - Stable across environments
-- Use Entity IDs for production embeds that sync across instances
-
----
-
-## Quick Reference
-
-### ⚠️ Deprecated Fields - DO NOT USE
-```
-authProviderUri - REMOVED: Configure JWT endpoint in Metabase admin instead
-jwtProviderUri - REMOVED: Configure JWT endpoint in Metabase admin instead
-config (MetabaseProvider) - REMOVED: Use authConfig prop instead
-```
-
-### Essential Web Component Attributes
-```
-dashboard-id, question-id - Required: resource identifier
-with-title - Boolean: show/hide title
-with-downloads - Boolean: enable/disable downloads
-drills - Boolean: enable/disable drill-through
-initial-parameters - JSON: default filter values
-hidden-parameters - Array: filters to hide
-token - String: JWT for guest embeds
-refresh - Number: auto-refresh interval (seconds)
-```
-
-### Essential SDK Props
-```
-dashboardId, questionId - Required: number (not string!) or entity ID string
- ⚠️ Parse URL params: parseInt(value, 10)
-withTitle - Boolean: show/hide title
-withDownloads - Boolean: enable/disable downloads
-initialParameters - Object: default filter values
-hiddenParameters - Array: filters to hide
-isSaveEnabled - Boolean: allow saving
-targetCollection - String/Number: force save location
-plugins - Object: plugin configuration
-```
-
-### Essential MetabaseProvider Props
-```
-authConfig - Required: authentication config (NOT "config")
-theme - Object: theme configuration
-pluginsConfig - Object: global plugins
-loaderComponent - Component: custom loader
-errorComponent - Component: custom error display
-```
-
-**⚠️ DEPRECATED Props (DO NOT USE):**
-```
-config - DEPRECATED: Use authConfig instead
-```
-
----
-
-## Entity ID Usage Pattern
-
-```tsx
-// Get entity ID from Metabase
-// Admin > Tools > Model Caching > Click info icon on any item
-
-// Use in embeds (stable across environments)
-<StaticDashboard dashboardId="abc123def456" />
-<StaticQuestion questionId="xyz789ghi012" />
-```
-
----
-
-## Example: Complete Production Setup
-
-**⚠️ Note:** This example shows `fetchRequestToken` for demonstration, but most apps using cookie-based auth don't need it. Only add `fetchRequestToken` if you need custom headers.
-
-### Backend (Express.js)
-
-```javascript
-const express = require("express");
-const jwt = require("jsonwebtoken");
-const cors = require("cors");
-
-const app = express();
-
-// CORS for SDK requests
-app.use(cors({
- origin: "https://your-app.com",
- credentials: true
-}));
-
-// JWT endpoint
-app.get("/sso/metabase", async (req, res) => {
- const user = await getCurrentUser(req);
-
- const token = jwt.sign(
- {
- email: user.email,
- first_name: user.firstName,
- last_name: user.lastName,
- groups: [`tenant_${user.tenantId}`],
- exp: Math.round(Date.now() / 1000) + 60 * 10
- },
- process.env.METABASE_JWT_SECRET
- );
-
- if (req.query.response === "json") {
- res.json({ jwt: token });
- } else {
- res.redirect(`${process.env.METABASE_URL}/auth/sso?token=true&jwt=${token}`);
- }
-});
-
-app.listen(3001);
-```
-
-### Frontend (React)
-
-```tsx
-import {
- MetabaseProvider,
- InteractiveDashboard,
- defineMetabaseAuthConfig
-} from "@metabase/embedding-sdk-react";
-
-// ✅ CORRECT - Default (no fetchRequestToken needed for cookie-based auth)
-const authConfig = defineMetabaseAuthConfig({
- metabaseInstanceUrl: "https://metabase.company.com"
-});
-
-// Or if you need custom headers:
-// const authConfig = defineMetabaseAuthConfig({
-// metabaseInstanceUrl: "https://metabase.company.com",
-// fetchRequestToken: async () => {
-// const response = await fetch("https://api.company.com/sso/metabase", {
-// credentials: "include",
-// headers: { "Authorization": `Bearer ${token}` }
-// });
-// return await response.json();
-// }
-// });
-
-function Analytics() {
- return (
- <MetabaseProvider authConfig={authConfig}> {/* ✅ authConfig NOT config */}
- <InteractiveDashboard dashboardId="abc123def" /> {/* ✅ Entity ID (string) */}
- </MetabaseProvider>
- );
-}
-```
-
-### Metabase Configuration
-
-1. **JWT Setup** (Admin > Authentication > JWT)
- - JWT Identity Provider URI: `https://api.company.com/sso/metabase`
- - String used by Metabase to encode: `[Copy shared secret from backend]`
-
-2. **Embedding** (Admin > Embedding)
- - Enable modular embedding SDK: ✓
- - Authorized origins: `https://your-app.com`
-
-3. **SameSite Cookie** (Admin > Embedding > Security)
- - SameSite cookie setting: None
-
-4. **Data Permissions** (Admin > Permissions > Data)
- - Create groups: `tenant_123`, `tenant_456`, etc.
- - Configure data sandboxes per group
-
----
-
-*Last Updated: December 2025*
-*Metabase Version: 1.58+*
\ No newline at end of file