Embedding with React SDK

Components, props, and hooks for embedding Lightdash content in a React or Next.js app

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

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 each origin where you’ll use the SDK.

Use origin mode for exact origins and simple subdomain wildcards:

• https://app.example.com allows only that exact origin.
• *.example.com allows HTTPS subdomains like https://app.example.com and is saved as a regex pattern.

Use regex mode (.*) for advanced patterns. Enter the pattern body only; Lightdash matches the whole origin automatically. For example, https:\\/\\/.*\\.example\\.com allows subdomains of example.com.

Only add origins you control. Avoid broad patterns that could match arbitrary external domains.

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.

Browsers enforce a Same-Origin Policy that blocks a web application from making requests to a domain other than the one that served it. Because the React SDK calls the Lightdash API from your frontend, your instance has to name your application’s origin in its CORS configuration for those requests to go through.

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. See Embedding dashboards for the JWT claims that control what viewers can do.

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;   // Translate your content (names, titles, markdown)
  uiOverrides?: SdkUiOverrides;     // Translate Lightdash UI strings (filters, menus, buttons)
  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;
  uiOverrides?: SdkUiOverrides;
  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;   // Translate your content (names, titles, markdown)
  uiOverrides?: SdkUiOverrides;     // Translate Lightdash UI strings (filters, menus, buttons)
};

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;   // Translate your content (names, titles, markdown)
  uiOverrides?: SdkUiOverrides;     // Translate Lightdash UI strings (filters, menus, buttons)
};

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, uiOverrides, 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, uiOverrides, 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: '[e-mail]',
      },
      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, signed with the embed secret from embed setup. Here’s a complete example, including user attributes for row-level filtering:

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-guided-setup	The guided setup card shown while required filters or requirement groups are unmet

.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

1. Go to Organization settings > Appearance in Lightdash
2. Define one or more color palettes
3. 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. The 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 React SDK has two translation props, split by what they translate:

Prop	Translates	Shape
contentOverrides	Your content: dashboard and chart names, tile titles, markdown, labels	LanguageMap, slug-keyed, generated with lightdash download --language-map
uiOverrides	Lightdash’s UI: filter operators and inputs, the filter popover, date zoom, tile menus, export buttons	Flat { key: string } map with a fixed, typed key set

There is no locale setting and no bundled language packs. Your app owns locale state and passes the translated strings for the language it wants. Anything you don’t override renders in the built-in English.

Both props are accepted by Lightdash.Dashboard, Lightdash.DashboardBuilder, Lightdash.Chart, and Lightdash.Explore. They are React SDK props only; iframe embeds are not translatable.

Translating your content with contentOverrides

contentOverrides translates the content you author in Lightdash: dashboard names and descriptions, tile titles, chart names, axis labels, series names, and markdown content.

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

Translating the Lightdash UI with uiOverrides

uiOverrides translates the interface Lightdash renders around your content: filter operators and inputs, the add/edit filter popover, the date zoom control, tile menus, and dashboard export buttons.

Pass a flat object mapping keys to translated strings. The key set is exported as the TypeScript type SdkUiOverrides from @lightdash/sdk, so editors autocomplete every key and unknown keys are compile errors.

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

const frenchUi: SdkUiOverrides = {
  'filters.addFilter': 'Ajouter un filtre',
  'filters.apply': 'Appliquer',
  'filters.operators.equals': 'est',
  'filters.operators.inThePast': 'au cours des derniers',
  'filters.unitsOfTime.days.plural': 'jours',
  'filters.unitsOfTime.days.completedPlural': 'jours révolus',
  'dateZoom.defaultZoom': 'Zoom par défaut',
  'tileMenu.downloadData': 'Télécharger les données',
};

<Lightdash.Dashboard
  instanceUrl={instanceUrl}
  token={token}
  contentOverrides={frenchLanguageMap} // your content
  uiOverrides={frenchUi}               // Lightdash's UI
/>;

Both the @lightdash/sdk package and your Lightdash instance must be on a version that includes uiOverrides. If you self-host, upgrade your instance as well, since the strings render inside Lightdash’s UI. There is no feature flag; uiOverrides is available wherever embedding is available.

Available keys

Keys are flat dot-paths, namespaced by the surface they translate:

• filters.* – operator labels (including date-specific variants), units of time, filter pills, the add/edit filter popover, value inputs, autocomplete states, the collapsed filter-bar summary, cross-filtering menu items, and the required-filters flow viewers see
• dateZoom.* – the date zoom control, granularity names, tooltips, and the per-tile zoom indicator
• tileMenu.* – the tile menu: Explore from here, Download data, Export image, View underlying data
• dashboard.* – dashboard-level export and print buttons

Every key is also exported through the SdkUiOverrides type in @lightdash/sdk, so your editor autocompletes the full set. The complete list with the built-in English defaults:

All translatable keys with English defaults

{
  "tileMenu.exploreFromHere": "Explore from here",
  "tileMenu.downloadData": "Download data",
  "tileMenu.exportImage": "Export image",
  "tileMenu.viewUnderlyingData": "View underlying data",
  "dateZoom.defaultZoom": "Default zoom",
  "dateZoom.none": "None",
  "dateZoom.viewModeTooltip": "Charts will display dates using their original granularity settings.",
  "dateZoom.appliesToOneChart": "Applies to {n} chart not in a zoom control",
  "dateZoom.appliesToManyCharts": "Applies to {n} charts not in a zoom control",
  "dateZoom.noChartsUseDefault": "No charts use the default (every chart is in a zoom control)",
  "dateZoom.granularities.Second": "Second",
  "dateZoom.granularities.Minute": "Minute",
  "dateZoom.granularities.Hour": "Hour",
  "dateZoom.granularities.Day": "Day",
  "dateZoom.granularities.Week": "Week",
  "dateZoom.granularities.Month": "Month",
  "dateZoom.granularities.Quarter": "Quarter",
  "dateZoom.granularities.Year": "Year",
  "dateZoom.dateZoomLabel": "Date zoom:",
  "dateZoom.onLabel": "On:",
  "filters.summary.filterSingular": "filter",
  "filters.summary.filterPlural": "filters",
  "filters.summary.parameterSingular": "parameter",
  "filters.summary.parameterPlural": "parameters",
  "filters.summary.dateZoomLabel": "Date Zoom:",
  "filters.summary.default": "Default",
  "filters.summary.showFilters": "Show filters",
  "filters.operators.isNull": "is null",
  "filters.operators.notNull": "is not null",
  "filters.operators.equals": "is",
  "filters.operators.notEquals": "is not",
  "filters.operators.startsWith": "starts with",
  "filters.operators.endsWith": "ends with",
  "filters.operators.doesNotInclude": "does not include",
  "filters.operators.include": "includes",
  "filters.operators.lessThan": "is less than",
  "filters.operators.lessThanOrEqual": "is less than or equal",
  "filters.operators.greaterThan": "is greater than",
  "filters.operators.greaterThanOrEqual": "is greater than or equal",
  "filters.operators.inThePast": "in the last",
  "filters.operators.notInThePast": "not in the last",
  "filters.operators.inTheNext": "in the next",
  "filters.operators.inTheCurrent": "in the current",
  "filters.operators.notInTheCurrent": "not in the current",
  "filters.operators.inBetween": "is between",
  "filters.operators.notInBetween": "is not between",
  "filters.operators.inPeriodToDate": "in all",
  "filters.dateOperators.lessThan": "is before",
  "filters.dateOperators.lessThanOrEqual": "is on or before",
  "filters.dateOperators.greaterThan": "is after",
  "filters.dateOperators.greaterThanOrEqual": "is on or after",
  "filters.dateOperators.inBetween": "is between",
  "filters.operators.inPeriodToDateDropdown": "in all periods to date",
  "filters.operators.inPeriodToDateDescription": "Trims every period in the range to the same point as today — e.g. with weeks selected, if today is Thursday, you get Mon–Thu of every week. Useful for like-for-like comparisons (WTD, MTD, QTD, YTD). For just the current period so far, use \"in the current\" instead.",
  "filters.nullValue": "(null)",
  "filters.betweenJoiner": "and",
  "filters.selectValuePlaceholder": "Select value",
  "filters.selectPeriodPlaceholder": "Select period",
  "filters.periodToDate.years": "year to date",
  "filters.periodToDate.quarters": "quarter to date",
  "filters.periodToDate.months": "month to date",
  "filters.periodToDate.weeks": "week to date",
  "filters.periodToDate.fallback": "period to date",
  "filters.periodToDateSelect.years": "years to date",
  "filters.periodToDateSelect.quarters": "quarters to date",
  "filters.periodToDateSelect.months": "months to date",
  "filters.periodToDateSelect.weeks": "weeks to date",
  "filters.unitsOfTime.milliseconds.singular": "millisecond",
  "filters.unitsOfTime.milliseconds.plural": "milliseconds",
  "filters.unitsOfTime.milliseconds.completedSingular": "completed millisecond",
  "filters.unitsOfTime.milliseconds.completedPlural": "completed milliseconds",
  "filters.unitsOfTime.seconds.singular": "second",
  "filters.unitsOfTime.seconds.plural": "seconds",
  "filters.unitsOfTime.seconds.completedSingular": "completed second",
  "filters.unitsOfTime.seconds.completedPlural": "completed seconds",
  "filters.unitsOfTime.minutes.singular": "minute",
  "filters.unitsOfTime.minutes.plural": "minutes",
  "filters.unitsOfTime.minutes.completedSingular": "completed minute",
  "filters.unitsOfTime.minutes.completedPlural": "completed minutes",
  "filters.unitsOfTime.hours.singular": "hour",
  "filters.unitsOfTime.hours.plural": "hours",
  "filters.unitsOfTime.hours.completedSingular": "completed hour",
  "filters.unitsOfTime.hours.completedPlural": "completed hours",
  "filters.unitsOfTime.days.singular": "day",
  "filters.unitsOfTime.days.plural": "days",
  "filters.unitsOfTime.days.completedSingular": "completed day",
  "filters.unitsOfTime.days.completedPlural": "completed days",
  "filters.unitsOfTime.weeks.singular": "week",
  "filters.unitsOfTime.weeks.plural": "weeks",
  "filters.unitsOfTime.weeks.completedSingular": "completed week",
  "filters.unitsOfTime.weeks.completedPlural": "completed weeks",
  "filters.unitsOfTime.months.singular": "month",
  "filters.unitsOfTime.months.plural": "months",
  "filters.unitsOfTime.months.completedSingular": "completed month",
  "filters.unitsOfTime.months.completedPlural": "completed months",
  "filters.unitsOfTime.quarters.singular": "quarter",
  "filters.unitsOfTime.quarters.plural": "quarters",
  "filters.unitsOfTime.quarters.completedSingular": "completed quarter",
  "filters.unitsOfTime.quarters.completedPlural": "completed quarters",
  "filters.unitsOfTime.years.singular": "year",
  "filters.unitsOfTime.years.plural": "years",
  "filters.unitsOfTime.years.completedSingular": "completed year",
  "filters.unitsOfTime.years.completedPlural": "completed years",
  "filters.addFilter": "Add filter",
  "filters.apply": "Apply",
  "filters.isAnyValue": "is any value",
  "filters.requiredFilterTooltip": "This is a required filter defined in the model configuration and cannot be removed.",
  "filters.placeholders.anyValue": "any value",
  "filters.placeholders.enterValue": "Enter value",
  "filters.placeholders.enterValues": "Enter value(s)",
  "filters.placeholders.startTyping": "Start typing to filter results",
  "filters.placeholders.selectDate": "Select a date",
  "filters.placeholders.selectDates": "Select date(s)",
  "filters.placeholders.selectValue": "Select a value",
  "filters.autocomplete.loading": "Loading...",
  "filters.autocomplete.noResults": "No results found",
  "filters.autocomplete.addValue": "Add \"{value}\"",
  "filters.autocomplete.maxResultsContinue": "Showing first {n} results. Continue typing...",
  "filters.autocomplete.maxResultsStart": "Showing first {n} results. Start typing...",
  "filters.autocomplete.editValuesTooltip": "Edit filter values",
  "filters.autocomplete.filterNotAvailable": "Filter not available",
  "filters.values.true": "True",
  "filters.values.false": "False",
  "filters.config.filterSettingsTab": "Filter Settings",
  "filters.config.filterSettingsTabTooltip": "Select the value you want to filter your dimension by",
  "filters.config.tilesTab": "Tiles",
  "filters.config.tilesTabTooltip": "Select tiles to apply filter to and which field to filter by",
  "filters.config.tabsAndTilesTab": "Tabs & tiles",
  "filters.config.tabsAndTilesTabTooltip": "Select which tabs and tiles this filter applies to",
  "filters.config.selectField": "Select a field to filter",
  "filters.config.selectFilterPlaceholder": "Select a filter",
  "filters.config.searchFieldPlaceholder": "Search field...",
  "filters.actions.cancel": "Cancel",
  "filters.actions.clearAll": "Clear all",
  "filters.config.applyRequiredTooltip": "Filter field and value required",
  "filters.config.applyLockedRequiredTooltip": "A locked, required filter must have a value",
  "filters.config.resetToOriginal": "Reset to original value",
  "filters.config.resetToOriginalAria": "Reset filter to original value",
  "filters.config.selectColumn": "Select a column to filter",
  "filters.config.searchColumnPlaceholder": "Search column...",
  "filters.config.noMatchingFields": "No matching fields",
  "filters.config.fieldsInThisTab": "Fields in this tab",
  "filters.config.otherAvailableFields": "Other available fields",
  "filters.config.valueLabel": "Value",
  "filters.config.clearToAnyValue": "Clear to any value",
  "filters.config.alreadyAnyValue": "Already showing any value",
  "filters.config.noValueToClear": "No value to clear",
  "filters.config.expandTab": "Expand tab",
  "filters.config.collapseTab": "Collapse tab",
  "filters.config.noTilesInTab": "No tiles in this tab",
  "filters.config.noFieldsMatchingType": "No fields matching filter type",
  "filters.config.fieldNotAvailableInChart": "The selected field '{field}' is not available in this chart",
  "filters.coverage.noMatchingCharts": "No charts have a matching field for this filter.",
  "filters.coverage.reviewTileTargets": "Review tile targets",
  "filters.coverage.wontAffectCurrentTab": "This filter won't affect charts on the current tab.",
  "filters.coverage.appliesAutomaticallyTo": "It applies automatically to:",
  "filters.coverage.reviewAndChangeTarget": "Review tile targets and change the filter target",
  "filters.notAppliedToAnyTiles": "This filter is not applied to any tiles",
  "filters.notAppliedToAnyTabs": "This filter is not applied to any tabs",
  "filters.filterIsLocked": "Filter is locked",
  "filters.filterIsLockedOnTab": "Filter is locked on this tab",
  "filters.tableLabel": "Table: ",
  "filters.tablesLabel": "Tables: ",
  "filters.invalidFilter": "Invalid filter",
  "filters.required.setValueTooltip": "Required: set a value to run this dashboard",
  "filters.required.setValueGroupTooltip": "Required: set a value on this or an alternative filter to run this dashboard",
  "filters.required.modalTitle": "Set filters to load this dashboard",
  "filters.required.modalDescription": "Data loads automatically once the filters below are set.",
  "filters.required.change": "Change",
  "filters.required.setInToolbar": "Set filters in the toolbar instead",
  "filters.crossFilter.menuLabel": "Filter dashboard on {field} to",
  "filters.crossFilter.showOnly": "Show only",
  "filters.crossFilter.exclude": "Exclude",
  "filters.inputs.startDate": "Start date",
  "filters.inputs.endDate": "End date",
  "filters.inputs.minValue": "Min value",
  "filters.inputs.maxValue": "Max value",
  "filters.inputs.bothValuesRequired": "Both values are required",
  "filters.inputs.minLessThanMax": "Minimum should be less than the maximum",
  "filters.inputs.typeToAddValue": "Please type to add the filter value",
  "filters.inputs.selectQuarter": "Select Quarter",
  "filters.inputs.pasteDetected": "Multiple comma-separated values detected:",
  "filters.inputs.pasteQuestion": "Would you like to add them as single or multiple values?",
  "filters.inputs.singleValue": "Single value",
  "filters.inputs.multipleValues": "Multiple values",
  "filters.autocomplete.manageValuesTooltip": "Manage filter values",
  "filters.autocomplete.refreshTooltip": "Click to refresh filter values",
  "filters.autocomplete.resultsLoadedAt": "Results loaded at {time}",
  "filters.manageValues.title": "Manage values",
  "filters.manageValues.filterValuesTitle": "Manage filter values",
  "filters.manageValues.clearAllValues": "Clear all values",
  "filters.manageValues.importCsv": "Import CSV",
  "filters.manageValues.importCsvAria": "Import CSV file",
  "filters.manageValues.selectAllShown": "Select all shown",
  "filters.manageValues.selections": "Selections",
  "filters.manageValues.searchPlaceholder": "Search values…",
  "filters.manageValues.valuesCount": "{n} values",
  "filters.manageValues.selectedCount": "({n} selected)",
  "filters.manageValues.noValuesYet": "No values yet",
  "filters.manageValues.noMatches": "No matches",
  "filters.manageValues.tryDifferentSearch": "Try a different search.",
  "filters.manageValues.importCsvHint": "Import a CSV to populate this filter, then you can review and remove items here.",
  "filters.resetAll": "Reset all filters",
  "filters.unsavedFiltersTooltip": "Filters you add are not saved",
  "filters.summary.hideFilters": "Hide filters",
  "filters.summary.hide": "Hide",
  "dashboard.exportAllTiles": "Export all tiles",
  "dashboard.printPage": "Print this page"
}

Complete Spanish example

{
  "tileMenu.exploreFromHere": "Explorar desde aquí",
  "tileMenu.downloadData": "Descargar datos",
  "tileMenu.exportImage": "Exportar imagen",
  "tileMenu.viewUnderlyingData": "Ver datos subyacentes",
  "dateZoom.defaultZoom": "Zoom predeterminado",
  "dateZoom.none": "Ninguno",
  "dateZoom.viewModeTooltip": "Los gráficos mostrarán las fechas con su granularidad original.",
  "dateZoom.appliesToOneChart": "Se aplica a {n} gráfico fuera de un control de zoom",
  "dateZoom.appliesToManyCharts": "Se aplica a {n} gráficos fuera de un control de zoom",
  "dateZoom.noChartsUseDefault": "Ningún gráfico usa el predeterminado (todos están en un control de zoom)",
  "dateZoom.granularities.Second": "Segundo",
  "dateZoom.granularities.Minute": "Minuto",
  "dateZoom.granularities.Hour": "Hora",
  "dateZoom.granularities.Day": "Día",
  "dateZoom.granularities.Week": "Semana",
  "dateZoom.granularities.Month": "Mes",
  "dateZoom.granularities.Quarter": "Trimestre",
  "dateZoom.granularities.Year": "Año",
  "dateZoom.dateZoomLabel": "Zoom de fecha:",
  "dateZoom.onLabel": "En:",
  "filters.summary.filterSingular": "filtro",
  "filters.summary.filterPlural": "filtros",
  "filters.summary.parameterSingular": "parámetro",
  "filters.summary.parameterPlural": "parámetros",
  "filters.summary.dateZoomLabel": "Zoom de fecha:",
  "filters.summary.default": "Predeterminado",
  "filters.summary.showFilters": "Mostrar filtros",
  "filters.operators.isNull": "es nulo",
  "filters.operators.notNull": "no es nulo",
  "filters.operators.equals": "es",
  "filters.operators.notEquals": "no es",
  "filters.operators.startsWith": "empieza por",
  "filters.operators.endsWith": "termina en",
  "filters.operators.doesNotInclude": "no incluye",
  "filters.operators.include": "incluye",
  "filters.operators.lessThan": "es menor que",
  "filters.operators.lessThanOrEqual": "es menor o igual que",
  "filters.operators.greaterThan": "es mayor que",
  "filters.operators.greaterThanOrEqual": "es mayor o igual que",
  "filters.operators.inThePast": "en los últimos",
  "filters.operators.notInThePast": "no en los últimos",
  "filters.operators.inTheNext": "en los próximos",
  "filters.operators.inTheCurrent": "en este",
  "filters.operators.notInTheCurrent": "no en este",
  "filters.operators.inBetween": "está entre",
  "filters.operators.notInBetween": "no está entre",
  "filters.operators.inPeriodToDate": "en todos",
  "filters.dateOperators.lessThan": "es antes de",
  "filters.dateOperators.lessThanOrEqual": "es el o antes de",
  "filters.dateOperators.greaterThan": "es después de",
  "filters.dateOperators.greaterThanOrEqual": "es el o después de",
  "filters.dateOperators.inBetween": "está entre",
  "filters.operators.inPeriodToDateDropdown": "en todos los períodos hasta la fecha",
  "filters.operators.inPeriodToDateDescription": "Recorta cada período del rango al mismo punto que hoy; p. ej., con semanas seleccionadas, si hoy es jueves, obtienes de lunes a jueves de cada semana. Útil para comparaciones equivalentes (WTD, MTD, QTD, YTD). Para solo el período actual, usa «en este».",
  "filters.nullValue": "(nulo)",
  "filters.betweenJoiner": "y",
  "filters.selectValuePlaceholder": "Seleccionar valor",
  "filters.selectPeriodPlaceholder": "Seleccionar período",
  "filters.periodToDate.years": "año hasta la fecha",
  "filters.periodToDate.quarters": "trimestre hasta la fecha",
  "filters.periodToDate.months": "mes hasta la fecha",
  "filters.periodToDate.weeks": "semana hasta la fecha",
  "filters.periodToDate.fallback": "período hasta la fecha",
  "filters.periodToDateSelect.years": "años hasta la fecha",
  "filters.periodToDateSelect.quarters": "trimestres hasta la fecha",
  "filters.periodToDateSelect.months": "meses hasta la fecha",
  "filters.periodToDateSelect.weeks": "semanas hasta la fecha",
  "filters.unitsOfTime.milliseconds.singular": "milisegundo",
  "filters.unitsOfTime.milliseconds.plural": "milisegundos",
  "filters.unitsOfTime.milliseconds.completedSingular": "milisegundo completo",
  "filters.unitsOfTime.milliseconds.completedPlural": "milisegundos completos",
  "filters.unitsOfTime.seconds.singular": "segundo",
  "filters.unitsOfTime.seconds.plural": "segundos",
  "filters.unitsOfTime.seconds.completedSingular": "segundo completo",
  "filters.unitsOfTime.seconds.completedPlural": "segundos completos",
  "filters.unitsOfTime.minutes.singular": "minuto",
  "filters.unitsOfTime.minutes.plural": "minutos",
  "filters.unitsOfTime.minutes.completedSingular": "minuto completo",
  "filters.unitsOfTime.minutes.completedPlural": "minutos completos",
  "filters.unitsOfTime.hours.singular": "hora",
  "filters.unitsOfTime.hours.plural": "horas",
  "filters.unitsOfTime.hours.completedSingular": "hora completa",
  "filters.unitsOfTime.hours.completedPlural": "horas completas",
  "filters.unitsOfTime.days.singular": "día",
  "filters.unitsOfTime.days.plural": "días",
  "filters.unitsOfTime.days.completedSingular": "día completo",
  "filters.unitsOfTime.days.completedPlural": "días completos",
  "filters.unitsOfTime.weeks.singular": "semana",
  "filters.unitsOfTime.weeks.plural": "semanas",
  "filters.unitsOfTime.weeks.completedSingular": "semana completa",
  "filters.unitsOfTime.weeks.completedPlural": "semanas completas",
  "filters.unitsOfTime.months.singular": "mes",
  "filters.unitsOfTime.months.plural": "meses",
  "filters.unitsOfTime.months.completedSingular": "mes completo",
  "filters.unitsOfTime.months.completedPlural": "meses completos",
  "filters.unitsOfTime.quarters.singular": "trimestre",
  "filters.unitsOfTime.quarters.plural": "trimestres",
  "filters.unitsOfTime.quarters.completedSingular": "trimestre completo",
  "filters.unitsOfTime.quarters.completedPlural": "trimestres completos",
  "filters.unitsOfTime.years.singular": "año",
  "filters.unitsOfTime.years.plural": "años",
  "filters.unitsOfTime.years.completedSingular": "año completo",
  "filters.unitsOfTime.years.completedPlural": "años completos",
  "filters.addFilter": "Añadir filtro",
  "filters.apply": "Aplicar",
  "filters.isAnyValue": "es cualquier valor",
  "filters.requiredFilterTooltip": "Este filtro es obligatorio, definido en la configuración del modelo, y no se puede eliminar.",
  "filters.placeholders.anyValue": "cualquier valor",
  "filters.placeholders.enterValue": "Introducir valor",
  "filters.placeholders.enterValues": "Introducir valor(es)",
  "filters.placeholders.startTyping": "Escribe para filtrar resultados",
  "filters.placeholders.selectDate": "Seleccionar una fecha",
  "filters.placeholders.selectDates": "Seleccionar fecha(s)",
  "filters.placeholders.selectValue": "Seleccionar un valor",
  "filters.autocomplete.loading": "Cargando...",
  "filters.autocomplete.noResults": "Sin resultados",
  "filters.autocomplete.addValue": "Añadir \"{value}\"",
  "filters.autocomplete.maxResultsContinue": "Mostrando los primeros {n} resultados. Sigue escribiendo...",
  "filters.autocomplete.maxResultsStart": "Mostrando los primeros {n} resultados. Empieza a escribir...",
  "filters.autocomplete.editValuesTooltip": "Editar valores del filtro",
  "filters.autocomplete.filterNotAvailable": "Filtro no disponible",
  "filters.values.true": "Verdadero",
  "filters.values.false": "Falso",
  "filters.config.filterSettingsTab": "Configuración del filtro",
  "filters.config.filterSettingsTabTooltip": "Selecciona el valor por el que filtrar tu dimensión",
  "filters.config.tilesTab": "Mosaicos",
  "filters.config.tilesTabTooltip": "Selecciona los mosaicos a los que aplicar el filtro y el campo por el que filtrar",
  "filters.config.tabsAndTilesTab": "Pestañas y mosaicos",
  "filters.config.tabsAndTilesTabTooltip": "Selecciona a qué pestañas y mosaicos se aplica este filtro",
  "filters.config.selectField": "Selecciona un campo para filtrar",
  "filters.config.selectFilterPlaceholder": "Selecciona un filtro",
  "filters.config.searchFieldPlaceholder": "Buscar campo...",
  "filters.actions.cancel": "Cancelar",
  "filters.actions.clearAll": "Borrar todo",
  "filters.config.applyRequiredTooltip": "Se requiere campo y valor del filtro",
  "filters.config.applyLockedRequiredTooltip": "Un filtro bloqueado y obligatorio debe tener un valor",
  "filters.config.resetToOriginal": "Restablecer al valor original",
  "filters.config.resetToOriginalAria": "Restablecer el filtro al valor original",
  "filters.config.selectColumn": "Selecciona una columna para filtrar",
  "filters.config.searchColumnPlaceholder": "Buscar columna...",
  "filters.config.noMatchingFields": "No hay campos coincidentes",
  "filters.config.fieldsInThisTab": "Campos en esta pestaña",
  "filters.config.otherAvailableFields": "Otros campos disponibles",
  "filters.config.valueLabel": "Valor",
  "filters.config.clearToAnyValue": "Borrar a cualquier valor",
  "filters.config.alreadyAnyValue": "Ya muestra cualquier valor",
  "filters.config.noValueToClear": "No hay valor que borrar",
  "filters.config.expandTab": "Expandir pestaña",
  "filters.config.collapseTab": "Contraer pestaña",
  "filters.config.noTilesInTab": "No hay mosaicos en esta pestaña",
  "filters.config.noFieldsMatchingType": "No hay campos que coincidan con el tipo de filtro",
  "filters.config.fieldNotAvailableInChart": "El campo seleccionado '{field}' no está disponible en este gráfico",
  "filters.coverage.noMatchingCharts": "Ningún gráfico tiene un campo que coincida con este filtro.",
  "filters.coverage.reviewTileTargets": "Revisar los mosaicos de destino",
  "filters.coverage.wontAffectCurrentTab": "Este filtro no afectará a los gráficos de la pestaña actual.",
  "filters.coverage.appliesAutomaticallyTo": "Se aplica automáticamente a:",
  "filters.coverage.reviewAndChangeTarget": "Revisar los mosaicos de destino y cambiar el destino del filtro",
  "filters.notAppliedToAnyTiles": "Este filtro no se aplica a ningún mosaico",
  "filters.notAppliedToAnyTabs": "Este filtro no se aplica a ninguna pestaña",
  "filters.filterIsLocked": "El filtro está bloqueado",
  "filters.filterIsLockedOnTab": "El filtro está bloqueado en esta pestaña",
  "filters.tableLabel": "Tabla: ",
  "filters.tablesLabel": "Tablas: ",
  "filters.invalidFilter": "Filtro no válido",
  "filters.required.setValueTooltip": "Obligatorio: establece un valor para ejecutar este tablero",
  "filters.required.setValueGroupTooltip": "Obligatorio: establece un valor en este filtro o en uno alternativo para ejecutar este tablero",
  "filters.required.modalTitle": "Establece filtros para cargar este tablero",
  "filters.required.modalDescription": "Los datos se cargan automáticamente cuando se establecen los filtros siguientes.",
  "filters.required.change": "Cambiar",
  "filters.required.setInToolbar": "Establecer los filtros en la barra de herramientas",
  "filters.crossFilter.menuLabel": "Filtrar el tablero por {field} para",
  "filters.crossFilter.showOnly": "Mostrar solo",
  "filters.crossFilter.exclude": "Excluir",
  "filters.inputs.startDate": "Fecha de inicio",
  "filters.inputs.endDate": "Fecha de fin",
  "filters.inputs.minValue": "Valor mínimo",
  "filters.inputs.maxValue": "Valor máximo",
  "filters.inputs.bothValuesRequired": "Ambos valores son obligatorios",
  "filters.inputs.minLessThanMax": "El mínimo debe ser menor que el máximo",
  "filters.inputs.typeToAddValue": "Escribe para añadir el valor del filtro",
  "filters.inputs.selectQuarter": "Seleccionar trimestre",
  "filters.inputs.pasteDetected": "Se detectaron varios valores separados por comas:",
  "filters.inputs.pasteQuestion": "¿Quieres añadirlos como un solo valor o como varios?",
  "filters.inputs.singleValue": "Valor único",
  "filters.inputs.multipleValues": "Varios valores",
  "filters.autocomplete.manageValuesTooltip": "Gestionar valores del filtro",
  "filters.autocomplete.refreshTooltip": "Haz clic para actualizar los valores del filtro",
  "filters.autocomplete.resultsLoadedAt": "Resultados cargados a las {time}",
  "filters.manageValues.title": "Gestionar valores",
  "filters.manageValues.filterValuesTitle": "Gestionar valores del filtro",
  "filters.manageValues.clearAllValues": "Borrar todos los valores",
  "filters.manageValues.importCsv": "Importar CSV",
  "filters.manageValues.importCsvAria": "Importar archivo CSV",
  "filters.manageValues.selectAllShown": "Seleccionar todos los mostrados",
  "filters.manageValues.selections": "Selecciones",
  "filters.manageValues.searchPlaceholder": "Buscar valores…",
  "filters.manageValues.valuesCount": "{n} valores",
  "filters.manageValues.selectedCount": "({n} seleccionados)",
  "filters.manageValues.noValuesYet": "Aún no hay valores",
  "filters.manageValues.noMatches": "Sin coincidencias",
  "filters.manageValues.tryDifferentSearch": "Prueba otra búsqueda.",
  "filters.manageValues.importCsvHint": "Importa un CSV para poblar este filtro; después podrás revisar y eliminar elementos aquí.",
  "filters.resetAll": "Restablecer todos los filtros",
  "filters.unsavedFiltersTooltip": "Los filtros que añadas no se guardan",
  "filters.summary.hideFilters": "Ocultar filtros",
  "filters.summary.hide": "Ocultar",
  "dashboard.exportAllTiles": "Exportar todos los mosaicos",
  "dashboard.printPage": "Imprimir esta página"
}

A quick way to create a new translation: copy one of the examples above and ask an AI agent to translate the values into your target language. Keep the keys and any {token} placeholders unchanged, then review the output before shipping it.

Key rules

• Every key is optional. Partial dictionaries are fine; missing keys render in English.
• Keys are a stable, additive contract. Existing keys are never renamed or removed across SDK versions. New UI may add keys, which fall back to English until you translate them.
• Keep {token} placeholders. Some values contain placeholders that Lightdash fills at runtime, like 'filters.autocomplete.addValue': 'Add "{value}"' or 'filters.crossFilter.menuLabel': 'Filter dashboard on {field} to'. Keep the token, with its exact name in braces, somewhere in the translation. Its position is free. No other syntax is supported (not ICU MessageFormat).
• Plurals are one key per form. Count-dependent strings exist as separate keys, like filters.summary.filterSingular / filters.summary.filterPlural, and units of time with .singular / .plural / .completedSingular / .completedPlural variants. There are no CLDR plural rules, so languages with more than two plural forms can only approximate.

Using uiOverrides with an i18n framework

Because the map is flat JSON, it drops directly into i18next-style resource files. Keep a uiOverrides object per locale and pass the active one:

// locales/fr/translation.json → { "uiOverrides": { "filters.apply": "Appliquer", ... } }
const uiOverrides = i18n.getResourceBundle(i18n.language, 'translation')?.uiOverrides;

<Lightdash.Dashboard ... uiOverrides={uiOverrides} key={i18n.language} />;

Re-mounting the component on language change (the key prop) is the simplest way to re-render every string.

What can be translated

Surface	Translatable with
Dashboard and chart names, descriptions, tile titles, axis labels, series names, markdown content	contentOverrides
Filter operators and inputs, the filter popover, date zoom, tile menus, export and print buttons	uiOverrides

Not translatable:

• Data from your warehouse – string values in charts, dimension values, and raw table data render as they exist in your database
• Field and table names – dimension and metric labels shown on filter pills and in the field picker come from your dbt schema
• Date picker internals – month and weekday names inside calendar popups render in English
• Data formatting – numbers, dates, and currencies render per chart config
• Editor-only UI – dashboard edit mode is not translated

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