From 85328b968b53726b6cc77335ecd38ad97cff7a79 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Sat, 11 Jul 2026 00:43:59 +0000
Subject: [PATCH] docs: add metrics catalog embedding guide and reference
---
docs.json | 1 +
guides/embedding/how-to-embed-content.mdx | 22 +++-
guides/embedding/metrics-catalog.mdx | 146 ++++++++++++++++++++++
references/embedding.mdx | 69 +++++++++-
references/react-sdk.mdx | 71 +++++++++++
5 files changed, 306 insertions(+), 3 deletions(-)
create mode 100644 guides/embedding/metrics-catalog.mdx
diff --git a/docs.json b/docs.json
index 9466bd40..21dbdc6f 100644
--- a/docs.json
+++ b/docs.json
@@ -315,6 +315,7 @@
"guides/embedding/dashboards",
"guides/embedding/charts",
"guides/embedding/ai-agents",
+ "guides/embedding/metrics-catalog",
"guides/embedding/data-apps"
]
},
diff --git a/guides/embedding/how-to-embed-content.mdx b/guides/embedding/how-to-embed-content.mdx
index 17c5a6f4..33b4fc42 100644
--- a/guides/embedding/how-to-embed-content.mdx
+++ b/guides/embedding/how-to-embed-content.mdx
@@ -12,7 +12,7 @@ import EmbedAvailability from '/snippets/embedding-availability.mdx';
## What can you embed?
-Lightdash supports embedding three types of content, each designed for different use cases:
+Lightdash supports embedding several types of content, each designed for different use cases:
### Dashboards
@@ -55,6 +55,21 @@ AI agent embedding requires the React SDK. iframe embedding is not supported for
[Learn more about embedding AI agents →](/guides/embedding/ai-agents)
+### Metrics catalog
+
+Embed the project's metrics catalog so users can browse the metrics and dimensions in your semantic layer, preview them, and — if you allow it — jump into Explore from any metric. Great for surfacing "what can I measure?" inside your product without exposing a full Lightdash workspace.
+
+**Use cases:**
+- A self-serve metric browser inside a customer-facing app
+- A discovery surface next to your own charts so users can find related metrics
+- Guided exploration where users start from a metric and continue into Explore
+
+
+Metrics catalog embedding requires the React SDK. iframe embedding is not supported for the metrics catalog.
+
+
+[Learn more about embedding the metrics catalog →](/guides/embedding/metrics-catalog)
+
### Data apps
Embed a [data app](/guides/data-apps) as standalone content in an iframe — the full app, no dashboard or surrounding chrome. Useful when you want to surface an entire AI-generated app as a feature in your product.
@@ -85,6 +100,7 @@ All three methods use the same JWT-based authentication and security model.
| Dashboards | ✓ | ✓ | ✓ |
| Individual charts | ✗ | ✗ | ✓ |
| AI agents | ✗ | ✗ | ✓ |
+| Metrics catalog | ✗ | ✗ | ✓ |
| Data apps (standalone) | ✓ | ✓ | ✗ |
| Requires embedding in an app | No | Yes | Yes |
| Setup complexity | Low | Low | Medium |
@@ -186,6 +202,10 @@ Lightdash provides code snippets you can copy and use in your app to generate va
Let customers chat with their data inside your application
+
+ Let customers browse and explore project metrics from your app
+
+
Embed a standalone data app in an iframe, no dashboard required
diff --git a/guides/embedding/metrics-catalog.mdx b/guides/embedding/metrics-catalog.mdx
new file mode 100644
index 00000000..fb82c7b0
--- /dev/null
+++ b/guides/embedding/metrics-catalog.mdx
@@ -0,0 +1,146 @@
+---
+title: "How to embed the metrics catalog"
+sidebarTitle: "Metrics catalog"
+description: "Embed the Lightdash metrics catalog so your users can browse the metrics and dimensions in a project without a Lightdash login."
+---
+
+import EmbedAvailability from '/snippets/embedding-availability.mdx';
+
+
+
+## Overview
+
+Metrics catalog embedding lets you drop the Lightdash metrics catalog directly into your application. Embedded users can browse the metrics defined in a project, search by name or category, preview a metric on a small chart, and — if you allow it — jump into Explore to slice the metric by any dimension in the model.
+
+Metrics catalog embeds use the same JWT-based security model as other embed types, with a dedicated `content.type: "metricsCatalog"` token. Dashboard, chart, and AI agent tokens cannot access the metrics catalog, and a metrics catalog token cannot render other embed surfaces.
+
+### When to use metrics catalog embedding
+
+- Give customers a self-serve "what can I measure?" view of your semantic layer inside your product.
+- Surface a metric browser next to your own charts so users can discover related metrics.
+- Let embedded users start a new exploration from any metric without exposing your full Lightdash workspace.
+
+### Available features
+
+Embedded metrics catalog supports:
+
+- Browsing all metrics in the project the JWT is scoped to
+- Searching and filtering by category
+- Previewing a metric with its default time-series chart
+- Continuing into an embedded Explore from any metric when `content.canExplore` is `true`
+- Saving Explore results into a fixed destination space via [write actions](/references/embedding#write-actions)
+- Row- and column-level filtering via [user attributes](/references/workspace/user-attributes)
+
+## Prerequisites
+
+Before you embed the metrics catalog, you need:
+
+- An embed secret for the project. See [Embedding quickstart](/guides/embedding/how-to-embed-content).
+- At least one metric defined in the project's semantic layer. See [How to create metrics](/get-started/develop-in-lightdash/how-to-create-metrics).
+- A React or Next.js host application — metrics catalog embedding is only available through the React SDK.
+- If you want embedded users to save charts from Explore, a destination space and a write actor. See [Write actions](/references/embedding#write-actions).
+
+## Embed the metrics catalog with the React SDK
+
+The React SDK ships a `Lightdash.MetricsCatalog` component that renders the catalog inside an iframe. When the embedded viewer clicks **Explore from here** on a metric, the same component swaps in an embedded Explore view — the host page never has to change route.
+
+```tsx
+import Lightdash from '@lightdash/sdk';
+
+function MyMetricsCatalog() {
+ return (
+
+ );
+}
+```
+
+See [`Lightdash.MetricsCatalog`](/references/react-sdk#lightdashmetricscatalog) for the full prop list and styling options.
+
+## Generate a metrics catalog embed token
+
+Metrics catalog embeds require a JWT with `content.type: "metricsCatalog"`. Generate it server-side using your embed secret.
+
+```javascript
+import jwt from 'jsonwebtoken';
+
+const token = jwt.sign({
+ content: {
+ type: 'metricsCatalog',
+ projectUuid: 'your-project-uuid',
+ canExplore: true,
+ },
+ writeActions: {
+ serviceAccountUserUuid: 'service-account-user-uuid',
+ spaceUuid: 'destination-space-uuid',
+ },
+ userAttributes: {
+ tenant_id: 'tenant-abc', // Row-level filtering for the embedded viewer
+ },
+ user: {
+ email: 'customer@example.com',
+ },
+}, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });
+```
+
+**Required fields:**
+
+- `content.type` — must be `"metricsCatalog"`.
+- `content.projectUuid` — pins the embed to a specific project. The catalog only lists metrics from this project.
+
+**Optional fields:**
+
+- `content.canExplore` — when `true`, embedded users can click **Explore from here** on any metric to open the embedded Explore view. Omit or set to `false` to keep the embed read-only.
+- `writeActions` — needed only when `canExplore` is `true` and you want embedded users to save charts they build from Explore. See [Write actions](/references/embedding#write-actions).
+- `userAttributes` — applies row- and column-level filters to catalog previews and Explore queries, identical to other embed types.
+- `user.email` / `user.externalId` — surfaced in audit and analytics for the embedded viewer.
+
+## Controlling access
+
+Metrics catalog embeds honor the same access controls as other embed surfaces:
+
+- The catalog only shows metrics from the project named in `content.projectUuid`.
+- [User attributes](/references/workspace/user-attributes) applied to the JWT hide metrics and dimensions whose `required_attributes` rules the embedded viewer does not satisfy, both in the catalog listing and in any Explore session launched from it.
+- Metric previews and Explore queries run with the write actor's permissions (when `writeActions` is set) plus any `userAttributes` filters, so embedded viewers only see rows and columns they are entitled to.
+- When `canExplore` is not set to `true`, the catalog is read-only — the **Explore from here** action is hidden and Explore routes reject the token.
+- Metrics catalog tokens are rejected by dashboard, chart, AI agent, and data app routes, and vice versa.
+
+## Example: read-only metrics catalog
+
+To publish a browse-only catalog without Explore or chart saving, mint a token with just `type` and `projectUuid`:
+
+```javascript
+const token = jwt.sign({
+ content: {
+ type: 'metricsCatalog',
+ projectUuid: 'your-project-uuid',
+ },
+ userAttributes: {
+ tenant_id: 'tenant-abc',
+ },
+}, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });
+```
+
+Embedded users can search and preview metrics, but the **Explore from here** action is hidden and Explore routes reject the token.
+
+## Next steps
+
+
+
+ Full prop reference for the Lightdash.MetricsCatalog component
+
+
+
+ Complete JWT structure for metrics catalog embed tokens
+
+
+
+ Configure the actor and destination space for embedded writes
+
+
+
+ Implement row- and column-level security in embedded content
+
+
diff --git a/references/embedding.mdx b/references/embedding.mdx
index da392dd1..2c378047 100644
--- a/references/embedding.mdx
+++ b/references/embedding.mdx
@@ -31,7 +31,7 @@ Embedded Lightdash content is available to view by anyone (not just folks with a
## Known limitations
-- Embedding works for dashboards, charts, and [data apps](/guides/data-apps). To embed explores, use the `canExplore` flag in a dashboard.
+- Embedding works for dashboards, charts, [AI agents](/guides/embedding/ai-agents), the [metrics catalog](/guides/embedding/metrics-catalog), and [data apps](/guides/data-apps). To embed explores, use the `canExplore` flag in a dashboard or metrics catalog token.
- The **Filter dashboard to** option when clicking on individual chart segments will not work on embedded dashboards.
If you're interested in embedding and one or more of these items are blockers, please reach out.
@@ -62,7 +62,7 @@ All tokens share these fields:
{
content: {
// Content configuration (required)
- type: 'dashboard' | 'chart' | 'aiAgent' | 'apiAccess',
+ type: 'dashboard' | 'chart' | 'aiAgent' | 'metricsCatalog' | 'dataApp' | 'apiAccess',
projectUuid?: string,
// ... type-specific fields
},
@@ -304,6 +304,71 @@ const token = jwt.sign({
}, SECRET, { expiresIn: '1h' });
```
+### Metrics catalog token
+
+For embedding the project [metrics catalog](/get-started/develop-in-lightdash/how-to-create-metrics) so embedded users can browse metrics and, optionally, continue into Explore. See [Embedding the metrics catalog](/guides/embedding/metrics-catalog) for the full walkthrough.
+
+```typescript
+{
+ content: {
+ type: 'metricsCatalog',
+
+ // Project identifier (required — pins the catalog to a single project)
+ projectUuid: string,
+
+ // Allow embedded users to open Explore from a metric (optional)
+ canExplore?: boolean,
+ },
+
+ // Optional: enable saving charts from the embedded Explore. Required only
+ // when canExplore is true and you want embedded users to save results.
+ writeActions?: {
+ spaceUuid: string,
+ serviceAccountUserUuid?: string,
+ userUuid?: string,
+ },
+
+ // Optional: row- and column-level filtering for the embedded viewer
+ userAttributes?: {
+ [attributeName: string]: string,
+ },
+
+ // Optional: user information surfaced in audit/analytics
+ user?: {
+ externalId?: string,
+ email?: string,
+ },
+}
+```
+
+
+Metrics catalog tokens only authorize the metrics catalog surface (and, when `canExplore` is `true`, the embedded Explore launched from a metric). Dashboard, chart, AI agent, and data app tokens are rejected by the metrics catalog routes, and metrics catalog tokens are rejected on other embed routes.
+
+
+**Example:**
+
+```javascript
+import jwt from 'jsonwebtoken';
+
+const token = jwt.sign({
+ content: {
+ type: 'metricsCatalog',
+ projectUuid: 'your-project-uuid',
+ canExplore: true,
+ },
+ writeActions: {
+ serviceAccountUserUuid: 'service-account-user-uuid',
+ spaceUuid: 'destination-space-uuid',
+ },
+ userAttributes: {
+ tenant_id: 'tenant-abc',
+ },
+ user: {
+ email: 'customer@example.com',
+ },
+}, SECRET, { expiresIn: '1h' });
+```
+
### Data app token
For embedding a [data app](/guides/data-apps) as standalone content in an iframe (no dashboard). See [How to embed data apps](/guides/embedding/data-apps) for the full guide.
diff --git a/references/react-sdk.mdx b/references/react-sdk.mdx
index 5fc3cb5d..b7ab0c6e 100644
--- a/references/react-sdk.mdx
+++ b/references/react-sdk.mdx
@@ -90,6 +90,7 @@ The Lightdash SDK exports components for embedding Lightdash content and hooks f
- `Lightdash.Chart` - Embed individual saved charts
- `Lightdash.Explore` - Embed interactive data exploration interface
- `Lightdash.AiAgent` - Embed an AI agent so users can chat with their data
+- `Lightdash.MetricsCatalog` - Embed the project metrics catalog so users can browse and explore metrics
- `Lightdash.useLightdashContent` - List spaces, dashboards, charts, and data apps for a custom content catalog
- `Lightdash.useLightdashAiAgentThreads` - List an embed user's previous AI agent threads to build a thread history UI
@@ -567,6 +568,76 @@ export function generateAiAgentToken() {
See [Embedding AI agents](/guides/embedding/ai-agents) for the full guide and [AI agent token](/references/embedding#ai-agent-token) for the complete JWT structure.
+### Lightdash.MetricsCatalog
+
+Embed the Lightdash [metrics catalog](/get-started/develop-in-lightdash/how-to-create-metrics) so embedded users can browse the metrics defined in a project, preview them, and — when the JWT allows it — continue into Explore without leaving your app.
+
+The component renders the catalog inside an iframe. When a viewer clicks **Explore from here** on a metric, the SDK swaps in an embedded Explore view; a **Back** action returns them to the catalog.
+
+#### Props
+
+```typescript
+type MetricsCatalogProps = {
+ // Required
+ instanceUrl: string; // Your Lightdash instance URL
+ token: string | Promise; // JWT with content.type: 'metricsCatalog'
+
+ // Optional
+ theme?: 'light' | 'dark'; // Force light or dark color scheme
+ styles?: {
+ backgroundColor?: string; // Background color or 'transparent'
+ fontFamily?: string; // Font family for all text
+ };
+};
+```
+
+
+`Lightdash.MetricsCatalog` does not accept `filters`, `contentOverrides`, or `onExplore`. The catalog and the embedded Explore it launches are managed inside the component.
+
+
+#### Basic usage
+
+```tsx
+import Lightdash from '@lightdash/sdk';
+
+function MyMetricsCatalog() {
+ return (
+
+ );
+}
+```
+
+#### Token generation for the metrics catalog
+
+Metrics catalog embeds require a JWT with `content.type: 'metricsCatalog'` and a `projectUuid`. Set `content.canExplore` to `true` to let embedded users open Explore from a metric, and include a `writeActions` claim if you want them to save the resulting charts back to Lightdash.
+
+```javascript
+// Backend API endpoint
+import jwt from 'jsonwebtoken';
+
+export function generateMetricsCatalogToken() {
+ return jwt.sign({
+ content: {
+ type: 'metricsCatalog',
+ projectUuid: 'your-project-uuid',
+ canExplore: true,
+ },
+ writeActions: {
+ serviceAccountUserUuid: 'service-account-user-uuid',
+ spaceUuid: 'destination-space-uuid',
+ },
+ userAttributes: {
+ tenant_id: 'tenant-abc',
+ },
+ }, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });
+}
+```
+
+Omit `canExplore` (or set it to `false`) to publish a read-only browse experience. See [Embedding the metrics catalog](/guides/embedding/metrics-catalog) for the full guide and [Metrics catalog token](/references/embedding#metrics-catalog-token) for the complete JWT structure.
+
## API hooks
### Lightdash.useLightdashContent