The Lightdash React SDK (@lightdash/sdk) provides React components for embedding Lightdash content in your React or Next.js applications. The SDK offers advantages over iframe embedding:
Seamless integration with your React application
Programmatic filters for dashboards
Callbacks for user interactions (e.g., explore navigation)
To use the React SDK, you need to update your “Cross-Origin Resource Sharing” (CORS) policy.This is done using environment variables. For Lightdash Cloud customers, contact the Lightdash team to update these for you.
Why CORS is neededEnabling CORS (Cross-Origin Resource Sharing) is necessary because browsers enforce security policies that prevent web applications from making requests to a different domain than the one that served the app (known as the Same-Origin Policy).Since the Lightdash React SDK interacts with a Lightdash API, you need to configure CORS on your Lightdash instance to allow your frontend application to communicate with the Lightdash server without being blocked by the browser.
CORS is only required for the React SDK. iframe embedding does not require CORS configuration.
The Lightdash SDK requires CSS styles to render components correctly. Import the SDK’s CSS file as the first import in your React application’s entry point:
import "@lightdash/sdk/sdk.css";import React from "react";import ReactDOM from "react-dom/client";import App from "./App";ReactDOM.createRoot(document.getElementById("root")!).render( <React.StrictMode> <App /> </React.StrictMode>);
The CSS import must be the first import in your entry file to ensure Lightdash styles load before other styles and avoid conflicts.
type ExploreProps = { // Required instanceUrl: string; // Your Lightdash instance URL token: string | Promise<string>; // JWT with canExplore: true // Optional styles?: { backgroundColor?: string; // Background color or 'transparent' fontFamily?: string; // Font family for all text }; contentOverrides?: LanguageMap; // Localization/translation overrides};
import Lightdash from '@lightdash/sdk';import { useState, useEffect } from 'react';function EmbeddedDashboard() { const [token, setToken] = useState<string | null>(null); useEffect(() => { // Fetch token from your backend fetch('/api/embed-token') .then(res => res.json()) .then(data => setToken(data.token)); }, []); if (!token) return <div>Loading...</div>; return ( <Lightdash.Dashboard instanceUrl="https://app.lightdash.cloud" token={token} /> );}
To ensure security, JWT generation code must run in your backend, and the Lightdash embed secret must never be exposed in frontend code. This prevents unauthorized access and protects sensitive data.
You can customize the appearance of embedded dashboards using color palettes. Define multiple color palettes in your organization settings, then apply them to embedded dashboards using the paletteUuid prop.For more on customizing appearance, see customizing the appearance of your project.
Filters can be passed to <Lightdash.Dashboard/> to filter dimensions by values. Filters are applied as AND operations, each further restricting results.
Filtering is only available for Dashboard components. Chart and Explore components do not support the filters prop.
For the filters prop to work, your JWT must have dashboardFiltersInteractivity set to enabled: 'all'. Without this configuration, filters will not be applied.
type SdkFilter = { model: string; // The model the dimension is part of field: string; // The name of the dimension to filter by operator: FilterOperator; // The filter operator (enum) value: unknown | unknown[]; // The value(s) to filter against};
The Lightdash SDK supports multilingual translation using standard i18n translation objects. To display a translated Lightdash dashboard, pass a correctly formatted translation object to the SDK.
The Lightdash CLI can produce translation maps for dashboards and charts. To include translation maps when downloading content, add the --language-map flag:
lightdash download --language-map
Alongside each downloaded dashboard and chart, there will be a <file name>.language.map.yml file containing translatable strings.Example translation map:
dashboard: sdk-dash: name: SDK dashboard demo description: "A dashboard demonstrating SDK features" tiles: - type: markdown properties: title: SDK demo dashboard content: >- This dashboard contains various tile types for showing SDK features. - type: saved_chart properties: title: "How do payment methods vary across different amount ranges?"
These translation maps can be imported into tools like Locize to begin translation.
