Skip to content

Commit 990a4c7

Browse files
stevelikesmusicstevelikesmusic
committed
feat: update embedding docs
1 parent b9c673d commit 990a4c7

File tree

10 files changed

+2726
-296
lines changed

10 files changed

+2726
-296
lines changed

‎docs.json‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -190,8 +190,21 @@
190190
"group": "Embedding",
191191
"pages": [
192192
"guides/how-to-embed-content",
193-
"references/embedding",
194-
"references/react-sdk"
193+
{
194+
"group": "Embedding guides",
195+
"pages": [
196+
"guides/embedding/dashboards",
197+
"guides/embedding/charts"
198+
]
199+
},
200+
{
201+
"group": "Reference",
202+
"pages": [
203+
"references/embedding",
204+
"references/iframe-embedding",
205+
"references/react-sdk"
206+
]
207+
}
195208
]
196209
},
197210
{

‎guides/embedding/charts.mdx‎

Lines changed: 344 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,344 @@
1+
---
2+
title: "How to Embed Charts"
3+
sidebarTitle: "Charts"
4+
description: "Learn how to embed individual Lightdash charts with minimal UI for focused, single-metric displays"
5+
---
6+
7+
import EmbedAvailability from 'snippets/embedding-availability.mdx'
8+
9+
<EmbedAvailability />
10+
11+
## Overview
12+
13+
Chart embedding allows you to display single saved charts from Lightdash in your application with a minimal, focused interface. Unlike dashboard embedding, chart embeds are scoped to a specific chart and provide a clean, distraction-free view of a single visualization.
14+
15+
<Warning>
16+
Chart embedding is **only available via the React SDK**. iframe embedding for charts is not currently supported.
17+
</Warning>
18+
19+
### When to use chart embedding
20+
21+
- **Single KPI displays**: Show one key metric or visualization
22+
- **Embedded widgets**: Add analytics widgets to application pages
23+
- **Marketing pages**: Display metrics on public-facing pages
24+
- **Minimal UI requirements**: When you need a clean, focused display
25+
- **Scoped access**: Grant access to specific charts only, not entire dashboards
26+
27+
### Key differences from dashboard embedding
28+
29+
| Feature | Dashboard Embedding | Chart Embedding |
30+
|---------|-------------------|-----------------|
31+
| **Embedding method** | iframe or React SDK | React SDK only |
32+
| **Content** | Multiple tiles, tabs | Single chart only |
33+
| **Filters** | Interactive dashboard filters | No filters (pre-configured) |
34+
| **JWT scope** | Dashboard UUID | Scoped to chart UUID |
35+
| **UI** | Full dashboard interface | Minimal chart view |
36+
| **Explore** | Can navigate to explore | Cannot access explore |
37+
38+
### Available features
39+
40+
Chart embedding supports:
41+
- All chart types (bar, line, pie, table, big number, etc.)
42+
- Parameterized charts with pre-set values
43+
- Export to CSV (if enabled)
44+
- Export to PNG/images (if enabled)
45+
- View underlying data (if enabled)
46+
47+
<Warning>
48+
Chart embeds are **read-only**. Users cannot modify the chart configuration, apply filters, or access the underlying data model.
49+
</Warning>
50+
51+
## Setup
52+
53+
### Configure allowed charts
54+
55+
Add the charts you want to embed to your project's embed settings. Navigate to **Settings → Embed** and add specific charts to the allowed list.
56+
57+
<Frame>
58+
<img src="/images/guides/embed-add-chart.png" alt="Add allowed charts"/>
59+
</Frame>
60+
61+
## Embedding with React SDK
62+
63+
Chart embedding requires the Lightdash React SDK for seamless integration in your React application.
64+
65+
<Info>
66+
See the [React SDK reference](/references/react-sdk) for installation, setup, and complete configuration options.
67+
</Info>
68+
69+
### Basic usage
70+
71+
```tsx
72+
import Lightdash from '@lightdash/sdk';
73+
74+
function MyChart() {
75+
return (
76+
<Lightdash.Chart
77+
instanceUrl="https://app.lightdash.cloud"
78+
id="your-chart-uuid"
79+
token={generateToken()} // Server-side function
80+
/>
81+
);
82+
}
83+
```
84+
85+
### Component props
86+
87+
```typescript
88+
type ChartProps = {
89+
instanceUrl: string; // Required: Your Lightdash instance URL
90+
id: string; // Required: Chart UUID (savedQueryUuid)
91+
token: string | Promise<string>; // Required: JWT token
92+
styles?: {
93+
backgroundColor?: string; // Chart background color or 'transparent'
94+
fontFamily?: string; // Font family for text
95+
};
96+
contentOverrides?: LanguageMap; // Translation/localization overrides
97+
};
98+
```
99+
100+
<Info>
101+
Unlike the Dashboard component, Chart does not support `filters` or `onExplore` props since charts are read-only and cannot navigate to explore.
102+
</Info>
103+
104+
#### Advanced example with styling
105+
106+
```tsx
107+
import Lightdash from '@lightdash/sdk';
108+
109+
<Lightdash.Chart
110+
instanceUrl="https://app.lightdash.cloud"
111+
id="your-chart-uuid"
112+
token={await generateToken()}
113+
styles={{
114+
backgroundColor: 'white',
115+
fontFamily: 'Inter, sans-serif',
116+
}}
117+
/>
118+
```
119+
120+
## Configuring features
121+
122+
Control what users can do with your embedded chart by configuring feature options. These options work for both iframe and React SDK embedding methods and are set in the JWT token.
123+
124+
### Export CSV
125+
126+
Export CSV allows users to download the raw data behind the chart as a CSV file, useful for further analysis in spreadsheet applications.
127+
128+
**Configure in JWT token:**
129+
130+
```javascript
131+
{
132+
content: {
133+
type: 'chart',
134+
contentId: 'your-chart-uuid',
135+
canExportCsv: true,
136+
}
137+
}
138+
```
139+
140+
When enabled, users see a "Download CSV" option in the chart's menu.
141+
142+
### Export images
143+
144+
Export images allows users to download the chart visualization as a PNG image file, useful for presentations and reports.
145+
146+
**Configure in JWT token:**
147+
148+
```javascript
149+
{
150+
content: {
151+
type: 'chart',
152+
contentId: 'your-chart-uuid',
153+
canExportImages: true,
154+
}
155+
}
156+
```
157+
158+
### View underlying data
159+
160+
View underlying data shows users the raw data table behind the chart, making it easy to inspect the actual values and records that create the visualization.
161+
162+
**Configure in JWT token:**
163+
164+
```javascript
165+
{
166+
content: {
167+
type: 'chart',
168+
contentId: 'your-chart-uuid',
169+
canViewUnderlyingData: true,
170+
}
171+
}
172+
```
173+
174+
### Complete configuration example
175+
176+
```javascript
177+
import jwt from 'jsonwebtoken';
178+
179+
const token = jwt.sign({
180+
content: {
181+
type: 'chart',
182+
projectUuid: 'your-project-uuid',
183+
contentId: 'your-chart-uuid',
184+
185+
// Export capabilities
186+
canExportCsv: true,
187+
canExportImages: true,
188+
canViewUnderlyingData: true,
189+
},
190+
191+
// User information (for analytics)
192+
user: {
193+
externalId: 'user-123',
194+
email: 'user@example.com',
195+
},
196+
}, LIGHTDASH_EMBED_SECRET, { expiresIn: '24h' });
197+
```
198+
199+
## Limitations
200+
201+
Chart embeds have the following limitations compared to dashboard embeds:
202+
203+
### Cannot modify charts
204+
Charts are always read-only. Users cannot:
205+
- Change dimensions or metrics
206+
- Apply filters
207+
- Modify chart configuration
208+
- Change visualization type
209+
210+
### No filter support
211+
Charts use their saved filter configuration. You cannot:
212+
- Add interactive filters
213+
- Apply filters programmatically via SDK
214+
- Change filter values at runtime
215+
216+
### No explore access
217+
Users cannot:
218+
- Navigate to the explore view
219+
- Access the underlying data model
220+
- Run custom queries
221+
- View or edit SQL
222+
223+
### Scoped permissions
224+
The JWT token is scoped to the specific chart UUID in `contentId`. Users cannot:
225+
- Access other charts not in the token
226+
- View project configuration
227+
- Access explore metadata
228+
229+
<Info>
230+
If you need filter interactivity or exploration capabilities, consider using [dashboard embedding](/guides/embedding/dashboards) instead or contact us with your use-case.
231+
</Info>
232+
233+
## Use cases and examples
234+
235+
### Single KPI widget
236+
237+
Display a key performance indicator in your application dashboard:
238+
239+
```tsx
240+
<div className="kpi-widget">
241+
<h3>Monthly Revenue</h3>
242+
<Lightdash.Chart
243+
instanceUrl="https://app.lightdash.cloud"
244+
id="revenue-chart-uuid"
245+
token={token}
246+
styles={{ backgroundColor: 'transparent' }}
247+
/>
248+
</div>
249+
```
250+
251+
### Embedded metric in marketing page
252+
253+
Show a public-facing metric on your website:
254+
255+
```html
256+
<section class="metrics">
257+
<div class="metric">
258+
<h2>Active Users</h2>
259+
<iframe
260+
src="https://app.lightdash.cloud/embed/project-uuid/chart/active-users-uuid#token"
261+
width="300"
262+
height="200"
263+
frameborder="0"
264+
></iframe>
265+
</div>
266+
</section>
267+
```
268+
269+
### Parameterized chart
270+
271+
Display a chart with pre-set parameter values:
272+
273+
```javascript
274+
// Chart is saved with a parameter for "region"
275+
// Pass parameter value in the chart configuration
276+
const token = jwt.sign({
277+
content: {
278+
type: 'chart',
279+
contentId: 'sales-by-region-uuid',
280+
canExportCsv: true,
281+
},
282+
}, LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });
283+
```
284+
285+
<Info>
286+
Parameter values are set when the chart is saved. Chart embeds display the chart with its saved parameter configuration.
287+
</Info>
288+
289+
## Advanced features
290+
291+
### User metadata for analytics
292+
293+
Pass user information to track who's viewing your embedded charts.
294+
295+
```javascript
296+
{
297+
user: {
298+
externalId: 'user-123', // Your internal user ID
299+
email: 'user@example.com', // User's email
300+
}
301+
}
302+
```
303+
304+
This metadata appears in [query tags](/references/usage-analytics#query-tags) in Lightdash usage analytics.
305+
306+
### Custom styling (SDK only)
307+
308+
Apply custom styling to match your application's design.
309+
310+
```tsx
311+
<Lightdash.Chart
312+
instanceUrl="https://app.lightdash.cloud"
313+
id="chart-uuid"
314+
token={token}
315+
styles={{
316+
backgroundColor: 'transparent',
317+
fontFamily: 'Helvetica, Arial, sans-serif',
318+
}}
319+
/>
320+
```
321+
322+
### Localization (SDK only)
323+
324+
Translate embedded charts using the `contentOverrides` prop. See [React SDK localization](/references/react-sdk#localization) for details.
325+
326+
## Next steps
327+
328+
<CardGroup cols={2}>
329+
<Card title="Embedding dashboards" icon="grid-2" href="/guides/embedding/dashboards">
330+
Embed multiple charts with filters and interactivity
331+
</Card>
332+
333+
<Card title="iframe embedding reference" icon="code" href="/references/iframe-embedding">
334+
Complete iframe URL patterns and HTML embedding
335+
</Card>
336+
337+
<Card title="Embedding API reference" icon="book" href="/references/embedding">
338+
Complete JWT token structure documentation
339+
</Card>
340+
341+
<Card title="React SDK reference" icon="react" href="/references/react-sdk">
342+
Complete SDK component documentation
343+
</Card>
344+
</CardGroup>

0 commit comments

Comments
 (0)