Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 22 additions & 15 deletions guides/embedding/how-to-embed-content.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,27 +40,30 @@ Chart embedding requires the React SDK. iframe embedding is only available for d

[Learn more about embedding charts →](/guides/embedding/charts)

## How can you embed content?
## How can you share or embed content?

Lightdash offers two embedding methods. The choice mainly comes down to what you're embedding and how much customization you need.
Lightdash offers three ways to share embedded content. The choice depends on whether you need to embed content in your own application or simply share a link.

**[iframe embedding](/references/iframe-embedding)** is simple to set up. You only need to generate a JWT, construct a URL, and add this to an `<iframe>` tag. There are no additional setup requirements and this works anywhere (React, Vue, plain HTML). Note that iframe embedding currently only supports dashboards (chart embedding via iframe is not supported).
**Shareable URL** is the simplest option. Lightdash can generate a standalone URL that anyone can open directly in their browser — no iframe, no SDK, and no Lightdash account required. This is useful when you want to share a dashboard with users outside your organisation (e.g., clients, partners, or stakeholders) without embedding it in an application. The URL uses the same JWT-based security as the other methods, so it expires after the time you set and can include user attributes for row-level filtering.

**[React SDK](/references/react-sdk)** (`@lightdash/sdk`) is the more powerful option. It supports both dashboards and charts, lets you pass filters programmatically, hook into user interaction callbacks (like when someone navigates to Explore), and apply custom styling to match your app. It requires a React/Next.js app and CORS configuration on the Lightdash instance (Cloud customers need to contact Lightdash to set that up).
**[iframe embedding](/references/iframe-embedding)** lets you embed a dashboard inside your own web page. You generate a JWT, construct a URL, and add it to an `<iframe>` tag. There are no additional setup requirements and this works anywhere (React, Vue, plain HTML). Note that iframe embedding currently only supports dashboards (chart embedding via iframe is not supported).

Both methods use the same JWT-based authentication and security model.
**[React SDK](/references/react-sdk)** (`@lightdash/sdk`) is the most powerful option. It supports both dashboards and charts, lets you pass filters programmatically, hook into user interaction callbacks (like when someone navigates to Explore), and apply custom styling to match your app. It requires a React/Next.js app and CORS configuration on the Lightdash instance (Cloud customers need to contact Lightdash to set that up).

All three methods use the same JWT-based authentication and security model.

### Quick comparison

| Feature | iframe | React SDK |
|---|---|---|
| Dashboards | ✓ | ✓ |
| Individual charts | ✗ | ✓ |
| Setup complexity | Low | Medium |
| CORS needed | No | Yes |
| Programmatic filters | Via JWT config | Via SDK `filters` prop |
| Custom styling | Limited | Full control |
| Framework requirement | None | React / Next.js |
| Feature | Shareable URL | iframe | React SDK |
|---|---|---|---|
| Dashboards | ✓ | ✓ | ✓ |
| Individual charts | ✗ | ✗ | ✓ |
| Requires embedding in an app | No | Yes | Yes |
| Setup complexity | Low | Low | Medium |
| CORS needed | No | No | Yes |
| Programmatic filters | Via JWT config | Via JWT config | Via SDK `filters` prop |
| Custom styling | No | Limited | Full control |
| Framework requirement | None | None | React / Next.js |

### Passing filters to embedded dashboards

Expand Down Expand Up @@ -105,6 +108,10 @@ Under the "Configure" section, you can:

Click on `Preview` to see how the embedded content will look, and click on `Generate & copy URL` to get a one-off embed URL for testing.

<Tip>
The generated URL can be shared directly with anyone — they can open it in their browser without needing a Lightdash account or any embedding setup. This is a quick way to share a dashboard with people outside your organisation (e.g., clients or partners) without building an iframe or React integration.
</Tip>

### Step 4: Generate tokens programmatically

Although you can generate URLs directly from Lightdash with a long expiration, it is recommended to generate your own JWTs in your backend with a short expiration using your `secret` to make sure people can't be using embed URLs outside your app.
Expand Down Expand Up @@ -149,7 +156,7 @@ Lightdash provides code snippets you can copy and use in your app to generate va

No, embedded Lightdash content is available to view by anyone (not just folks with a Lightdash login).

So, for example, you could embed a dashboard in your product, and anyone who has access to your product would have access to that dashboard. No need to login to Lightdash.
So, for example, you could embed a dashboard in your product, and anyone who has access to your product would have access to that dashboard. No need to login to Lightdash. You can also share a dashboard URL directly with someone outside your organisation — they just open the link in their browser.

We make sure that the links are secure and have a set expiry time that you pick.

Expand Down
9 changes: 8 additions & 1 deletion references/embedding.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,14 @@ import EmbedAvailability from '/snippets/embedding-availability.mdx';

## Overview

This document provides complete API reference for JWT structure and configuration options used by both embedding methods (iframe and React SDK).
This document provides complete API reference for JWT structure and configuration options used across all embedding and sharing methods.

Lightdash supports three ways to share embedded content:
- **Shareable URL** — Generate a link that anyone can open directly in their browser, no iframe or SDK needed. Ideal for sharing dashboards with external users like clients or partners.
- **iframe embedding** — Embed dashboards inside your own web pages using a standard `<iframe>` tag.
- **React SDK** — Embed dashboards and charts in React/Next.js apps with full programmatic control.

All three methods use the same JWT-based authentication described below.

**For method-specific implementation details, see:**
- [iframe embedding reference](/references/iframe-embedding) - URL patterns, HTML embedding
Expand Down
Loading