Embedding with React SDK

Overview

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)
Custom styling to match your application
TypeScript support with full type definitions

For iframe embedding, see the embedding reference.

Set up CORS

To use the React SDK, you need to update your “Cross-Origin Resource Sharing” (CORS) policy so the domain hosting your React app is allowed to call the Lightdash API. In Lightdash, go to Project settings -> Embed configuration -> CORS and add the origins where you will use the SDK, for example https://app.example.com or *.example.com. For self-hosted deployments, you can also configure instance-level allowed origins with environment variables:

LIGHTDASH_CORS_ALLOWED_DOMAINS=https://domain-where-you-are-going-to-use-the-sdk.com

CORS is enabled by default. Set LIGHTDASH_CORS_ENABLED=false only if you want to disable CORS for the whole instance.

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.

Installing the Lightdash SDK

In your frontend project, use your preferred package manager to install the SDK.

npm install @lightdash/sdk
# or
pnpm add @lightdash/sdk
# or
yarn add @lightdash/sdk

At the moment, we support React 18 and 19, so make sure your frontend is using React 18 or later. For Next.js, version 15 or later is required.

Import CSS styles

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.

Components and hooks

The Lightdash SDK exports components for embedding Lightdash content and hooks for building custom host-app UI around embedded content:

Lightdash.Dashboard - Embed complete dashboards with multiple tiles
Lightdash.DashboardBuilder - Let embedded users create a brand-new dashboard
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

All components share common props for authentication and styling.

Lightdash.Dashboard

Embed complete Lightdash dashboards with multiple visualizations, filters, and interactive features.

Props

type DashboardProps = {
  // Required
  instanceUrl: string;              // Your Lightdash instance URL
  token: string | Promise<string>;  // JWT (can be async)

  // Optional
  theme?: 'light' | 'dark';         // Force light or dark color scheme
  styles?: {
    backgroundColor?: string;       // Background color or 'transparent'
    fontFamily?: string;            // Font family for all text
  };
  filters?: SdkFilter[];            // Apply filters programmatically
  paletteUuid?: string;             // Color palette UUID for custom theming
  contentOverrides?: LanguageMap;   // Localization/translation overrides
  isEditMode?: boolean;             // Render the dashboard in edit mode (requires writeActions JWT)
  onEditModeChange?: (
    isEditMode: boolean,
  ) => void;                        // Callback when the embed enters or leaves edit mode
  onExplore?: (options: {
    chart: SavedChart
  }) => void;                       // Callback when user navigates to explore
};

Basic usage

import Lightdash from '@lightdash/sdk';

function MyDashboard() {
  return (
    <Lightdash.Dashboard
      instanceUrl="https://app.lightdash.cloud"
      token={generateToken()} // Server-side function
    />
  );
}

With filters

Apply filters programmatically using the filters prop:

import Lightdash, { FilterOperator } from '@lightdash/sdk';

<Lightdash.Dashboard
  instanceUrl="https://app.lightdash.cloud"
  token={token}
  filters={[
    {
      model: 'orders',
      field: 'status',
      operator: FilterOperator.EQUALS,
      value: 'completed',
    },
    {
      model: 'orders',
      field: 'created_date',
      operator: FilterOperator.IN_BETWEEN,
      value: ['2024-01-01', '2024-12-31'],
    },
  ]}
/>

See Filtering data for complete filter documentation.

With styling

<Lightdash.Dashboard
  instanceUrl="https://app.lightdash.cloud"
  token={token}
  styles={{
    backgroundColor: '#f5f5f5',
    fontFamily: 'Inter, sans-serif',
  }}
/>

With explore callback

Track when users navigate to explore:

<Lightdash.Dashboard
  instanceUrl="https://app.lightdash.cloud"
  token={generateToken({ canExplore: true })}
  onExplore={({ chart }) => {
    console.log('User exploring chart:', chart.name);
    // Track analytics, show help guides, etc.
  }}
/>

With edit mode

When the JWT includes a writeActions claim, you can render an existing dashboard in edit mode and let users rename it, add saved charts from the allowed space, move or resize tiles, and save changes. The host app controls the edit-mode state through isEditMode and onEditModeChange.

import Lightdash from '@lightdash/sdk';
import { useState } from 'react';

function EditableDashboard() {
  const [isEditMode, setIsEditMode] = useState(false);

  return (
    <>
      {!isEditMode && (
        <button onClick={() => setIsEditMode(true)}>Edit dashboard</button>
      )}
      <Lightdash.Dashboard
        instanceUrl="https://app.lightdash.cloud"
        token={generateToken()} // JWT must include writeActions
        isEditMode={isEditMode}
        onEditModeChange={setIsEditMode}
      />
    </>
  );
}

Add-tile content is filtered to the JWT writeActions.spaceUuid, so users can only pick saved charts from the allowed space. See Write actions for the JWT claim.

Lightdash.DashboardBuilder

Let embedded users build a brand-new dashboard from scratch. On mount, the SDK creates an empty dashboard in the JWT writeActions.spaceUuid and renders it through the same embedded dashboard component as Lightdash.Dashboard. The host app controls when the dashboard is in edit mode. Use this when you want your customers to author their own dashboards inside your app — for example, a “Create dashboard” page in your customer portal — without giving them a Lightdash login.

Props

type DashboardBuilderProps = {
  // Required
  instanceUrl: string;              // Your Lightdash instance URL
  token: string | Promise<string>;  // JWT with writeActions claim

  // Optional
  theme?: 'light' | 'dark';
  styles?: {
    backgroundColor?: string;
    fontFamily?: string;
  };
  filters?: SdkFilter[];
  paletteUuid?: string;
  contentOverrides?: LanguageMap;
  isEditMode?: boolean;             // Render the new dashboard in edit mode
  onEditModeChange?: (
    isEditMode: boolean,
  ) => void;                        // Callback when the embed enters or leaves edit mode
  onDashboardReady?: (
    dashboard: EmbedDashboard,
  ) => void;                        // Called once the empty dashboard has been created
  onExplore?: (options: {
    chart: SavedChart
  }) => void;
};

Basic usage

import Lightdash from '@lightdash/sdk';
import { useEffect, useState } from 'react';

function MyDashboardBuilder() {
  const [isEditMode, setIsEditMode] = useState(false);
  const [isReady, setIsReady] = useState(false);

  return (
    <>
      {isReady && !isEditMode && (
        <button onClick={() => setIsEditMode(true)}>Edit dashboard</button>
      )}
      <Lightdash.DashboardBuilder
        instanceUrl="https://app.lightdash.cloud"
        token={generateToken()} // JWT must include writeActions
        isEditMode={isEditMode}
        onEditModeChange={setIsEditMode}
        onDashboardReady={() => setIsReady(true)}
      />
    </>
  );
}

Requirements and behavior

The JWT must include a writeActions claim with spaceUuid. JWTs without writeActions fail closed for write-capable paths.
The new dashboard is created in writeActions.spaceUuid, named “Untitled dashboard”, and is empty.
Add-tile content (saved charts and SQL charts) is filtered to the same space.
Dashboards created or edited through the SDK are normal Lightdash dashboards — they can be viewed and edited from Lightdash and vice versa.
See Write actions for the JWT claim and how to configure the actor and destination space.

Lightdash.Chart

Embed individual saved charts for focused, single-metric displays with minimal UI.

Props

type ChartProps = {
  // Required
  instanceUrl: string;              // Your Lightdash instance URL
  id: string;                       // Chart UUID (savedQueryUuid)
  token: string | Promise<string>;  // JWT with type: 'chart'

  // Optional
  theme?: 'light' | 'dark';         // Force light or dark color scheme
  styles?: {
    backgroundColor?: string;       // Background color or 'transparent'
    fontFamily?: string;            // Font family for all text
  };
  contentOverrides?: LanguageMap;   // Localization/translation overrides
};

Unlike Dashboard, Chart does not support filters or onExplore props since charts are read-only and cannot navigate to explore.

Basic usage

import Lightdash from '@lightdash/sdk';

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

With styling

<Lightdash.Chart
  instanceUrl="https://app.lightdash.cloud"
  id="your-chart-uuid"
  token={token}
  styles={{
    backgroundColor: 'white',
    fontFamily: 'Helvetica, Arial, sans-serif',
  }}
/>

Token generation for charts

Charts require a JWT with type: 'chart':

// Backend API endpoint
import jwt from 'jsonwebtoken';

export function generateChartToken(chartId) {
  return jwt.sign({
    content: {
      type: 'chart',
      contentId: chartId,  // savedQueryUuid
      canExportCsv: true,
      canExportImages: false,
      canViewUnderlyingData: true,
    },
  }, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '24h' });
}

See Embedding charts guide for details.

Lightdash.Explore

Embed interactive data exploration interface with full query builder capabilities.

Props

type ExploreProps = {
  // Required
  instanceUrl: string;              // Your Lightdash instance URL
  token: string | Promise<string>;  // JWT with canExplore: true

  // Optional
  theme?: 'light' | 'dark';         // Force light or dark color scheme
  styles?: {
    backgroundColor?: string;       // Background color or 'transparent'
    fontFamily?: string;            // Font family for all text
  };
  contentOverrides?: LanguageMap;   // Localization/translation overrides
};

Basic usage

import Lightdash from '@lightdash/sdk';

function MyExplore() {
  return (
    <Lightdash.Explore
      instanceUrl="https://app.lightdash.cloud"
      token={generateExploreToken()} // Must include canExplore: true
    />
  );
}

With styling

<Lightdash.Explore
  instanceUrl="https://app.lightdash.cloud"
  token={token}
  styles={{
    backgroundColor: '#f9f9f9',
    fontFamily: 'Inter, sans-serif',
  }}
/>

Token generation for explores

Explores require canExplore: true in the JWT:

// Backend API endpoint
import jwt from 'jsonwebtoken';

export function generateExploreToken() {
  return jwt.sign({
    content: {
      type: 'dashboard',  // Can use dashboard type
      dashboardUuid: 'starting-dashboard-uuid',
      canExplore: true,   // Required for explore access
      canExportCsv: true,
      canExportImages: true,
    },
  }, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '4h' });
}

Lightdash.AiAgent

Embed a Lightdash AI agent so embedded users can chat with their data, generate charts, and save results back to a fixed space — without a Lightdash login. The component renders the agent inside an iframe. Use threadUuid to deep-link into an existing thread, or omit it to land on the new-thread screen.

Props

type AiAgentProps = {
  // Required
  instanceUrl: string;              // Your Lightdash instance URL
  agentUuid: string;                // Agent to embed (must match the JWT)
  token: string | Promise<string>;  // JWT with content.type: 'aiAgent'

  // Optional
  threadUuid?: string;              // Open a specific thread on load
  onThreadChange?: (options: { threadUuid: string }) => void; // Fires when the embed opens or creates a thread
  theme?: 'light' | 'dark';
  styles?: {
    backgroundColor?: string;
  };
};

Lightdash.AiAgent does not accept filters, contentOverrides, or onExplore. Threads, navigation, and chart actions are managed inside the embedded agent UI.

onThreadChange fires whenever the embedded agent creates a new thread or opens an existing one. Use it together with threadUuid to persist the current conversation in your app (for example in localStorage or your own backend) and resume it the next time the user returns. Under the hood, the SDK passes a targetOrigin query parameter to the iframe and listens for lightdash:aiAgentThreadChanged postMessage events from the embedded page — no extra setup is required on your side.

Basic usage

import Lightdash from '@lightdash/sdk';

function MyAiAgent() {
  return (
    <Lightdash.AiAgent
      instanceUrl="https://app.lightdash.cloud"
      agentUuid="your-agent-uuid"
      token={generateAiAgentToken()} // Server-side function
    />
  );
}

Open a specific thread

Pass threadUuid to deep-link the embed into a specific conversation on mount:

<Lightdash.AiAgent
  instanceUrl="https://app.lightdash.cloud"
  agentUuid="your-agent-uuid"
  threadUuid="thread-uuid"
  token={token}
/>

Persist and resume the last conversation

Combine threadUuid and onThreadChange to keep users on their most recent thread across page reloads. This example stores the latest thread UUID in localStorage:

import Lightdash from '@lightdash/sdk';
import { useState } from 'react';

const STORAGE_KEY = 'acme-shop:lightdash-ai-thread';

function ShopInsightsAgent({ token }: { token: string }) {
  const [threadUuid, setThreadUuid] = useState<string | undefined>(
    () => localStorage.getItem(STORAGE_KEY) ?? undefined,
  );

  return (
    <Lightdash.AiAgent
      instanceUrl="https://app.lightdash.cloud"
      agentUuid="agent-shop-insights"
      token={token}
      threadUuid={threadUuid}
      onThreadChange={({ threadUuid: nextThreadUuid }) => {
        setThreadUuid(nextThreadUuid);
        localStorage.setItem(STORAGE_KEY, nextThreadUuid);
      }}
    />
  );
}

Token generation for AI agents

AI agent embeds require a JWT with content.type: 'aiAgent' and a writeActions claim that pins the destination space and the actor used for agent queries and chart saves:

// Backend API endpoint
import jwt from 'jsonwebtoken';

export function generateAiAgentToken() {
  return jwt.sign({
    content: {
      type: 'aiAgent',
      projectUuid: 'your-project-uuid',
      agentUuid: 'your-agent-uuid',
    },
    writeActions: {
      serviceAccountUserUuid: 'service-account-user-uuid',
      spaceUuid: 'destination-space-uuid',
    },
    userAttributes: {
      tenant_id: 'tenant-abc',
    },
  }, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });
}

See Embedding AI agents for the full guide and AI agent token for the complete JWT structure.

Lightdash.MetricsCatalog

Embed the Lightdash metrics catalog 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

type MetricsCatalogProps = {
  // Required
  instanceUrl: string;              // Your Lightdash instance URL
  token: string | Promise<string>;  // 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

import Lightdash from '@lightdash/sdk';

function MyMetricsCatalog() {
  return (
    <Lightdash.MetricsCatalog
      instanceUrl="https://app.lightdash.cloud"
      token={generateMetricsCatalogToken()} // Server-side function
    />
  );
}

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.

// 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 for the full guide and Metrics catalog token for the complete JWT structure.

API hooks

Lightdash.useLightdashContent

Use useLightdashContent when you want your own app to list Lightdash content instead of embedding the Lightdash home page. A common pattern is to let customers choose a space in your UI, show the dashboards and charts in that space, then render the selected object with Lightdash.Dashboard or Lightdash.Chart. The hook calls the Lightdash content API and returns metadata only. It does not render the selected chart or dashboard, and it does not replace the chart or dashboard embed token you pass to the render component.

Backend: generate an API access token

Generate the token on your backend with your Lightdash embed secret. Never expose the embed secret in browser code.

import jwt from 'jsonwebtoken';

export function generateContentCatalogToken() {
  return jwt.sign(
    {
      content: {
        type: 'apiAccess',
        projectUuid: 'your-project-uuid',
        serviceAccountUserUuid: 'service-account-user-uuid',
      },
      user: {
        externalId: 'customer-user-123',
        email: 'customer@example.com',
      },
      userAttributes: {
        tenant_id: 'tenant-abc',
      },
    },
    process.env.LIGHTDASH_EMBED_SECRET,
    { expiresIn: '1h' },
  );
}

The service account controls what the hook can list. If the service account cannot view a private space, content from that space is not returned.

Frontend: list content in a space

import Lightdash from '@lightdash/sdk';

function ContentCatalog({
  instanceUrl,
  projectUuid,
  token,
  spaceUuid,
}: {
  instanceUrl: string;
  projectUuid: string;
  token: string;
  spaceUuid: string;
}) {
  const { data, error, isLoading, refetch } = Lightdash.useLightdashContent(
    {
      instanceUrl,
      projectUuid,
      auth: {
        type: 'embedToken',
        token,
      },
    },
    {
      spaceUuids: [spaceUuid],
      contentTypes: ['dashboard', 'chart'],
      page: 1,
      pageSize: 50,
      sortBy: 'name',
      sortDirection: 'asc',
    },
  );

  if (isLoading) return <p>Loading content...</p>;
  if (error) return <p>Unable to load content</p>;

  return (
    <div>
      <button type="button" onClick={() => refetch()}>
        Refresh
      </button>

      {data?.data.map((item) => (
        <button key={item.uuid} type="button">
          {item.name}
        </button>
      ))}
    </div>
  );
}

Options

type ListContentOptions = {
  projectUuids?: string[];
  spaceUuids?: string[];
  parentSpaceUuid?: string;
  contentTypes?: Array<'space' | 'dashboard' | 'chart' | 'data_app'>;
  page?: number;
  pageSize?: number;
  search?: string;
  sortBy?: 'name' | 'space_name' | 'last_updated_at';
  sortDirection?: 'asc' | 'desc';
};

Use the spaceUuids option as a filter, not as an authorization boundary. Authorization comes from the API access token’s service account permissions.

apiAccess tokens are for API reads such as content listing. To let embedded users save charts or dashboards, use an embed token that supports writeActions.

Lightdash.useLightdashAiAgentThreads

Use useLightdashAiAgentThreads when you want to show your users a list of their previous AI agent conversations — for example a “Recent chats” sidebar next to a Lightdash.AiAgent embed. The hook calls the AI agent threads endpoint with the embed JWT, so it returns only threads that belong to the JWT-authenticated embed user and are scoped to their embed space. Pair it with Lightdash.AiAgent’s threadUuid and onThreadChange props to let users resume any past conversation.

Options

type ListAiAgentThreadsOptions = {
  agentUuid: string;      // The agent whose threads should be listed
  projectUuid?: string;   // Falls back to the projectUuid on LightdashApiClientConfig
};

The hook takes the same LightdashApiClientConfig as useLightdashContent, with auth.type: 'embedToken' and the AI agent embed JWT as the token.

Types

type LightdashAiAgentThreadResults = LightdashAiAgentThread[];

// One entry per thread the embed user can see. Full shape lives in
// @lightdash/common's ApiAiAgentThreadSummaryListResponse; the useful fields
// for building thread history UIs are:
type LightdashAiAgentThread = {
  uuid: string;
  title?: string;
  firstMessage: { message: string };
  // ...additional metadata such as timestamps
};

Example: thread history + resume

import Lightdash, {
  useLightdashAiAgentThreads,
  type LightdashApiClientConfig,
} from '@lightdash/sdk';
import { useState } from 'react';

const STORAGE_KEY = 'acme-shop:lightdash-ai-thread';

function ShopInsightsAgentWithHistory({
  token,
  projectUuid,
  agentUuid,
}: {
  token: string;
  projectUuid: string;
  agentUuid: string;
}) {
  const apiConfig: LightdashApiClientConfig = {
    instanceUrl: 'https://app.lightdash.cloud',
    projectUuid,
    auth: { type: 'embedToken', token },
  };

  const threads = Lightdash.useLightdashAiAgentThreads(apiConfig, {
    agentUuid,
    projectUuid,
  });

  const [threadUuid, setThreadUuid] = useState<string | undefined>(
    () => localStorage.getItem(STORAGE_KEY) ?? undefined,
  );

  return (
    <div style={{ display: 'grid', gridTemplateColumns: '280px 1fr' }}>
      <aside>
        <button type="button" onClick={() => setThreadUuid(undefined)}>
          New thread
        </button>

        {threads.isLoading && <p>Loading history…</p>}
        {threads.data?.map((thread) => (
          <button
            key={thread.uuid}
            type="button"
            onClick={() => setThreadUuid(thread.uuid)}
          >
            {thread.title ?? thread.firstMessage.message}
          </button>
        ))}
      </aside>

      <Lightdash.AiAgent
        instanceUrl="https://app.lightdash.cloud"
        token={token}
        agentUuid={agentUuid}
        threadUuid={threadUuid}
        onThreadChange={({ threadUuid: nextThreadUuid }) => {
          setThreadUuid(nextThreadUuid);
          localStorage.setItem(STORAGE_KEY, nextThreadUuid);
          // Refresh the sidebar so new threads show up immediately.
          threads.refetch();
        }}
      />
    </div>
  );
}

useLightdashAiAgentThreads uses the same embed JWT you pass to Lightdash.AiAgent. The token’s content.agentUuid and writeActions.spaceUuid are what scope the returned threads — the hook cannot list threads from a different agent or space, even if you pass a different agentUuid argument.

Generating embed tokens

All SDK components require JWTs generated server-side. Here’s a complete example:

Backend API endpoint

// server/api/embed-token.ts
import jwt from 'jsonwebtoken';

export async function generateEmbedToken(req, res) {
  // Authenticate user
  const userId = req.user.id;
  const user = await getUserFromDatabase(userId);

  // Generate token with user-specific attributes
  const token = jwt.sign({
    content: {
      type: 'dashboard',
      dashboardUuid: 'your-dashboard-uuid',
      dashboardFiltersInteractivity: {
        enabled: 'all',
      },
      canExportCsv: true,
      canExplore: true,
    },
    userAttributes: {
      tenant_id: user.tenantId,  // Row-level filtering
    },
    user: {
      externalId: user.id,
      email: user.email,
    },
  }, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });

  res.json({ token });
}

Frontend React component

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.

Applying styles

Override styles within Lightdash components to match your application’s design.

Supported style overrides

styles?: {
  fontFamily?: string;       // Sets all fonts within the component
  backgroundColor?: string;  // Sets the background color or 'transparent'
}

Both properties accept normal CSS values and are set on a styles object passed to any component.

Font family

Sets the font family for all text within the embedded content. Font sizes and other properties are preserved.

<Lightdash.Dashboard
  instanceUrl={lightdashUrl}
  token={lightdashToken}
  styles={{
    fontFamily: 'Inter, sans-serif',
  }}
/>

Some charts and components set font-family explicitly, so the fontFamily style is applied with higher specificity to override these.

Background color

Sets the background for the embedded content. Can be any color value or 'transparent'.

<Lightdash.Dashboard
  instanceUrl={lightdashUrl}
  token={lightdashToken}
  styles={{
    backgroundColor: 'transparent',
  }}
/>

Complete example

<Lightdash.Dashboard
  instanceUrl={lightdashUrl}
  token={lightdashToken}
  styles={{
    backgroundColor: '#f5f5f5',
    fontFamily: 'Helvetica, Arial, sans-serif',
  }}
/>

CSS class overrides

Beyond the styles prop, you can target embedded dashboard elements directly from your application’s stylesheet. Each element below carries a stable, human-readable classname that is part of the SDK’s public API — it won’t change when internal layout does, so your overrides stay resilient across releases.

Class	Element
`ld-dashboard-header`	The dashboard header bar
`ld-dashboard-filters`	The filter bar row
`ld-dashboard-filter`	An individual filter pill
`ld-dashboard-date-zoom`	The date-zoom control(s)
`ld-dashboard-parameters`	The parameters row
`ld-dashboard-parameter`	An individual parameter pill
`ld-dashboard-filter-dropdown`	An open filter’s dropdown
`ld-dashboard-date-zoom-dropdown`	The open date-zoom menu
`ld-dashboard-parameter-dropdown`	An open parameter’s dropdown

.ld-dashboard-filters {
  gap: 1rem;
}

.ld-dashboard-filter-dropdown {
  font-size: 1rem;
  min-width: 380px;
}

The filter, date-zoom, and parameter dropdowns render in a portal at the page root — outside the dashboard container — so target them with a global selector rather than as a descendant of the embedded dashboard.

Light and dark mode

Use the theme prop to render embedded content in either 'light' or 'dark' mode. This is typically driven by the host application’s own theme state, so the embedded dashboard, chart, or explore matches the surrounding UI.

<Lightdash.Dashboard
  instanceUrl={lightdashUrl}
  token={lightdashToken}
  theme="dark"
/>

The theme prop is supported on Lightdash.Dashboard, Lightdash.Chart, and Lightdash.Explore.

When theme is set, the SDK forces the Mantine color scheme and ignores any user-toggled preference stored in the embed. Omit the prop to let the embed use its default (light) color scheme.

Syncing with your app’s theme

Pass your app’s current theme value directly to the SDK so the embed re-renders when it changes:

import Lightdash from '@lightdash/sdk';
import { useState } from 'react';

function EmbeddedDashboard() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  return (
    <Lightdash.Dashboard
      instanceUrl={lightdashUrl}
      token={lightdashToken}
      theme={theme}
    />
  );
}

Combining with `styles.backgroundColor`

When theme is set, the embed uses the matching Mantine body background by default. If you also pass styles.backgroundColor, your value takes precedence:

<Lightdash.Dashboard
  instanceUrl={lightdashUrl}
  token={lightdashToken}
  theme="dark"
  styles={{
    backgroundColor: '#0b0b0f', // Overrides the default dark background
  }}
/>

Color palettes

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.

Setting up color palettes

Go to Organization settings > Appearance in Lightdash
Define one or more color palettes
Copy the palette UUID for the palette you want to use (or fetch from API GET /api/v1/org/color-palettes)

Applying a palette

Pass the paletteUuid prop to the Lightdash.Dashboard component:

<Lightdash.Dashboard
  instanceUrl="https://app.lightdash.cloud"
  token={token}
  paletteUuid="your-palette-uuid"
/>

Filtering data

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.

Filter structure

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
};

Basic example

<Lightdash.Dashboard
  instanceUrl={lightdashUrl}
  token={lightdashToken}
  filters={[
    {
      model: 'dbt_users',
      field: 'browser',
      operator: FilterOperator.INCLUDE,
      value: ['chrome', 'safari'],
    },
  ]}
/>

Multiple filters

Filters are applied as AND operations:

<Lightdash.Dashboard
  instanceUrl={lightdashUrl}
  token={lightdashToken}
  filters={[
    {
      model: 'dbt_users',
      field: 'created_date_week',
      operator: FilterOperator.IN_BETWEEN,
      value: ['2024-08', '2024-10'],
    },
    {
      model: 'dbt_users',
      field: 'browser',
      operator: FilterOperator.INCLUDE,
      value: ['chrome', 'safari'],
    },
    {
      model: 'orders',
      field: 'status',
      operator: FilterOperator.EQUALS,
      value: 'completed',
    },
  ]}
/>

FilterOperator enum

Import FilterOperator from the SDK:

import Lightdash, { FilterOperator } from '@lightdash/sdk';

Available operators:

Operator	Description	Value Type
`FilterOperator.IS_NULL`	Field is null	n/a
`FilterOperator.NOT_NULL`	Field is not null	n/a
`FilterOperator.EQUALS`	Field equals value	single value
`FilterOperator.NOT_EQUALS`	Field does not equal value	single value
`FilterOperator.STARTS_WITH`	Field starts with value	single value
`FilterOperator.ENDS_WITH`	Field ends with value	single value
`FilterOperator.INCLUDE`	Field includes any of values	array
`FilterOperator.NOT_INCLUDE`	Field does not include values	array
`FilterOperator.LESS_THAN`	Field is less than value	single value
`FilterOperator.LESS_THAN_OR_EQUAL`	Field is ≤ value	single value
`FilterOperator.GREATER_THAN`	Field is greater than value	single value
`FilterOperator.GREATER_THAN_OR_EQUAL`	Field is ≥ value	single value
`FilterOperator.IN_THE_PAST`	Date in the past N units	single value
`FilterOperator.NOT_IN_THE_PAST`	Date not in past N units	single value
`FilterOperator.IN_THE_NEXT`	Date in the next N units	single value
`FilterOperator.IN_THE_CURRENT`	Date in current period	single value
`FilterOperator.NOT_IN_THE_CURRENT`	Date not in current period	single value
`FilterOperator.IN_BETWEEN`	Field between two values	array with 2 values
`FilterOperator.NOT_IN_BETWEEN`	Field not between values	array with 2 values

Available fields

Only fields that are available for filtering can be filtered. These are specified in the JWT passed to the SDK.

To generate tokens with filterable fields, configure your embed in the Lightdash UI or include the appropriate fields in your JWT structure.

Localization

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.

Recommended tools

Translation maps – The Lightdash CLI can generate translation maps when downloading content as code
Runtime translation management – Use a translation library like i18next
Translation production tools – Tools like Locize help manage translations efficiently

Video overview

Translation maps

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.

Runtime translation

At runtime, pass a translation object to the SDK’s contentOverrides prop. We suggest using i18Next to load translations:

import i18n from 'i18next';

<Lightdash.Dashboard
  instanceUrl={lightdashUrl}
  token={lightdashToken}
  contentOverrides={i18n.getResourceBundle(
    i18n.language,      // Specify language
    'demo-dashboard',   // Specify namespace
  )}
/>

Setting up i18Next with Locize

import i18next from 'i18next';
import { initReactI18next } from 'react-i18next';
import Locize from 'i18next-locize-backend';

i18next
  .use(Locize)  // Add Locize backend
  .use(initReactI18next)  // Bind react-i18next
  .init({
    // Locize configuration
    backend: {
      projectId: 'your-locize-project-id',
      apiKey: 'your-api-key',
      referenceLng: 'en',
    },
    lng: 'en',
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false,
    },
  });

What can be translated

Can be translated (UI strings specified in Lightdash):

Dashboard names and descriptions
Tile titles
Chart names
Axis labels
Series names
Markdown content

Cannot be translated (data from your warehouse):

String values in charts
Dimension values
Metric names from database
Raw data in tables

Strings originating from your data warehouse cannot be translated by the SDK. They are presented as they exist in your database.

Complete example

Here’s a full example integrating everything:

Backend (Express + Node.js)

// server.js
import express from 'express';
import jwt from 'jsonwebtoken';
import cors from 'cors';

const app = express();
app.use(cors());

app.get('/api/dashboard-token', authenticateUser, async (req, res) => {
  const user = await getUserFromDatabase(req.user.id);

  const token = jwt.sign({
    content: {
      type: 'dashboard',
      dashboardUuid: 'abc-123-def-456',
      dashboardFiltersInteractivity: { enabled: 'all' },
      parameterInteractivity: { enabled: true },
      canExportCsv: true,
      canExportImages: true,
      canExplore: true,
      canViewUnderlyingData: true,
    },
    userAttributes: {
      tenant_id: user.tenantId,
      region: user.region,
    },
    user: {
      externalId: user.id,
      email: user.email,
    },
  }, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '2h' });

  res.json({ token, projectUuid: process.env.LIGHTDASH_PROJECT_UUID });
});

app.listen(3000);

Frontend (React)

// Dashboard.tsx
import { useState, useEffect } from 'react';
import Lightdash, { FilterOperator } from '@lightdash/sdk';

export function EmbeddedDashboard() {
  const [token, setToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch('/api/dashboard-token')
      .then(res => res.json())
      .then(data => {
        setToken(data.token);
        setLoading(false);
      })
      .catch(err => {
        console.error('Failed to load token:', err);
        setLoading(false);
      });
  }, []);

  if (loading) return <div>Loading analytics...</div>;
  if (!token) return <div>Failed to load dashboard</div>;

  return (
    <div style={{ height: '100vh', width: '100%' }}>
      <Lightdash.Dashboard
        instanceUrl="https://app.lightdash.cloud"
        token={token}
        filters={[
          {
            model: 'orders',
            field: 'status',
            operator: FilterOperator.EQUALS,
            value: 'completed',
          },
        ]}
        styles={{
          backgroundColor: 'transparent',
          fontFamily: 'Inter, -apple-system, sans-serif',
        }}
        onExplore={({ chart }) => {
          console.log('User exploring:', chart.name);
          // Track analytics event
        }}
      />
    </div>
  );
}

Embedding quickstart

Get started with embedding in 5 minutes

Embedding API reference

Complete JWT structure and configuration

iframe embedding reference

Complete iframe URL patterns and HTML embedding

Embedding dashboards

Complete guide to dashboard embedding

Embedding charts

Complete guide to chart embedding

User attributes

Implement row-level security with user attributes

​Overview

​Set up CORS

​Installing the Lightdash SDK

​Import CSS styles

​Components and hooks

​Lightdash.Dashboard

​Props

​Basic usage

​With filters

​With styling

​With explore callback

​With edit mode

​Lightdash.DashboardBuilder

​Props

​Basic usage

​Requirements and behavior

​Lightdash.Chart

​Props

​Basic usage

​With styling

​Token generation for charts

​Lightdash.Explore

​Props

​Basic usage

​With styling

​Token generation for explores

​Lightdash.AiAgent

​Props

​Basic usage

​Open a specific thread

​Persist and resume the last conversation

​Token generation for AI agents

​Lightdash.MetricsCatalog

​Props

​Basic usage

​Token generation for the metrics catalog

​API hooks

​Lightdash.useLightdashContent

​Backend: generate an API access token

​Frontend: list content in a space

​Options

​Lightdash.useLightdashAiAgentThreads

​Options

​Types

​Example: thread history + resume

​Generating embed tokens

​Backend API endpoint

​Frontend React component

​Applying styles

​Supported style overrides

​Font family

​Background color

​Complete example

​CSS class overrides

​Light and dark mode

​Syncing with your app’s theme

​Combining with styles.backgroundColor

​Color palettes

​Setting up color palettes

​Applying a palette

​Filtering data

​Filter structure

​Basic example

​Multiple filters

​FilterOperator enum

​Available fields

​Localization

​Recommended tools

​Video overview

​Translation maps

​Runtime translation

​Setting up i18Next with Locize

​What can be translated

​Complete example

​Backend (Express + Node.js)

​Frontend (React)

​See also

Embedding quickstart

Embedding API reference

iframe embedding reference

Overview

Set up CORS

Installing the Lightdash SDK

Import CSS styles

Components and hooks

Lightdash.Dashboard

Props

Basic usage

With filters

With styling

With explore callback

With edit mode

Lightdash.DashboardBuilder

Props

Basic usage

Requirements and behavior

Lightdash.Chart

Props

Basic usage

With styling

Token generation for charts

Lightdash.Explore

Props

Basic usage

With styling

Token generation for explores

Lightdash.AiAgent

Props

Basic usage

Open a specific thread

Persist and resume the last conversation

Token generation for AI agents

Lightdash.MetricsCatalog

Props

Basic usage

Token generation for the metrics catalog

API hooks

Lightdash.useLightdashContent

Backend: generate an API access token

Frontend: list content in a space

Options

Lightdash.useLightdashAiAgentThreads

Options

Types

Example: thread history + resume

Generating embed tokens

Backend API endpoint

Frontend React component

Applying styles

Supported style overrides

Font family

Background color

Complete example

CSS class overrides

Light and dark mode

Syncing with your app’s theme

Combining with `styles.backgroundColor`

Color palettes

Setting up color palettes

Applying a palette

Filtering data

Filter structure

Basic example

Multiple filters

FilterOperator enum

Available fields

Localization

Recommended tools

Video overview

Translation maps

Runtime translation

Setting up i18Next with Locize

What can be translated

Complete example

Backend (Express + Node.js)

Frontend (React)

See also