How to Embed Charts

Embedding requires the embedding add-on for Cloud Pro or Enterprise. Get in touch to add embedding to your plan. For self-hosted deployments, follow embedding setup.

Try it and see the code. embed.lightdash.com is an interactive demo and helper that lets you preview embedded content and generate a JWT for your own project. For a working end-to-end example, see the example embed app on GitHub — a Node.js app that mints tokens server-side and renders a Lightdash dashboard.

Overview

Chart embedding displays a single saved chart with a minimal, focused interface — a clean, distraction-free view of one visualization, scoped to that chart alone. By default, chart embeds are read-only: viewers can’t change the configuration, apply filters, or reach Explore.

When to use chart embedding

Single KPI displays: show one key metric or visualization
Embedded widgets: add analytics widgets to application pages
Minimal UI: a clean, focused display with no dashboard chrome
Scoped access: grant access to specific charts, not entire dashboards

How it differs from dashboard embedding

Feature	Dashboard embedding	Chart embedding
Method	iframe or React SDK	iframe or React SDK
Content	Multiple tiles, tabs	Single chart
Filters	Interactive dashboard filters	Saved filters only, not interactive
JWT scope	Dashboard UUID	Chart UUID (`contentId`)
Explore	Can navigate to Explore	Only to drill down or edit, with edit mode

Chart embeds support all chart types (bar, line, pie, table, big number, and so on), parameterized charts with their saved values, and — when enabled in the JWT — viewing underlying data. For CSV and image export, see Limitations.

Set up a chart embed

Follow the embedding quickstart for the shared setup: create an embed secret and generate tokens from your backend. The chart-specific part is the allowlist — each chart must be added individually under Settings → Embed before it can be embedded.

Embed with an iframe

iframe embedding needs no libraries or CORS setup. Put the project UUID and the chart UUID in the path and the JWT in the hash fragment. The token’s content.contentId must match the chart UUID in the URL.

https://your-instance.lightdash.cloud/embed/{projectUuid}/chart/{chartUuid}#{jwtToken}

<iframe
  src="https://app.lightdash.cloud/embed/project-uuid/chart/chart-uuid#jwt-token"
  width="100%"
  height="600"
  frameborder="0"
  style="border: none;"
></iframe>

The iframe embedding reference covers URL parameters (including theme, backgroundColor, and timezone), responsive and dynamic sizing, token refresh, and troubleshooting.

Embed with the React SDK

Render a chart with Lightdash.Chart, passing the chart UUID and a server-generated token:

import Lightdash from '@lightdash/sdk';

function MyChart() {
  return (
    <Lightdash.Chart
      instanceUrl="https://app.lightdash.cloud"
      id="your-chart-uuid"
      token={generateToken()} // Server-side function
    />
  );
}

See the React SDK reference for installation, CORS setup, props, and styling.

Configure what viewers can do

A chart token is scoped to one chart via content.contentId (the saved chart UUID). Inside content, you can allow CSV export, image export, and viewing underlying data. For the full schema, see the chart token in the embedding reference.

import jwt from 'jsonwebtoken';

const token = jwt.sign({
  content: {
    type: 'chart',
    projectUuid: 'your-project-uuid',
    contentId: 'your-chart-uuid',

    canExportCsv: true,
    canExportImages: true,
    canViewUnderlyingData: true,
  },
  user: {
    externalId: 'user-123',
    email: 'user@example.com',
  },
}, LIGHTDASH_EMBED_SECRET, { expiresIn: '24h' });

Parameter values are fixed when the chart is saved. A chart embed displays the chart with its saved parameter configuration. If the token’s userAttributes don’t meet the required attributes of the chart’s model, the embed shows Error loading chart with an authorization message.

Edit and drill down

To let viewers edit the chart or drill into its data, add a writeActions claim whose write spaces include the chart’s space, make sure the write actor can update the chart, and pass isEditMode to Lightdash.Chart. The chart then renders in Explore: isEditMode={true} opens it for editing, and isEditMode={false} lets viewers click a data point and Drill into it, with a Back to Chart button. See Edit and drill into a chart.

Limitations

Chart embeds are single-scope. Without edit mode, viewers cannot modify dimensions, metrics, or visualization type, drill down, or reach the Explore view. In every mode, viewers can’t apply filters through the SDK filters prop or access any content beyond the chart named in contentId. A chart embed renders only the visualization, with no header or toolbar, so canExportCsv and canExportImages have no button to act on. View underlying data works, since viewers open it from the chart’s data points. To give viewers CSV and image export, add the chart as the only tile on a dashboard and embed that dashboard instead; dashboard tiles keep their export menu. If you need interactive filters or exploration, use dashboard embedding instead, or reach out with your use case. Drop a key metric into your own layout and let the chart background go transparent so it inherits your styling:

<div className="kpi-widget">
  <h3>Monthly Revenue</h3>
  <Lightdash.Chart
    instanceUrl="https://app.lightdash.cloud"
    id="revenue-chart-uuid"
    token={token}
    styles={{ backgroundColor: 'transparent' }}
  />
</div>

Pass user metadata in the token to attribute queries in usage analytics, and userAttributes for row-level security. Styling and localization props are covered in the React SDK reference.

​Overview

​When to use chart embedding

​How it differs from dashboard embedding

​Set up a chart embed

​Embed with an iframe

​Embed with the React SDK

​Configure what viewers can do

​Edit and drill down

​Limitations

​Example: single KPI widget

Overview

When to use chart embedding

How it differs from dashboard embedding

Set up a chart embed

Embed with an iframe

Embed with the React SDK

Configure what viewers can do

Edit and drill down

Limitations

Example: single KPI widget