React SDK reference | QueryPanel docs

React SDK

Ship customer-facing analytics in React: the main product story is the embedded dashboard — a single component that loads a published workspace with AI editing, charts, and optional tenant customization. Your workspace private key stays on the server; you mint a short-lived tenant JWT there, and the embed calls the QueryPanel API at apiBaseUrl with Authorization: Bearer — no secrets in the browser.

Package: @querypanel/react-sdk

Fastest path: embed a dashboard. JWT setup is on mint a tenant JWT. This page is the full React SDK reference.

Embedded dashboard — one component

QuerypanelEmbedded is the fastest path to a full analytics experience: pass a dashboard id, the QueryPanel API base URL (the same host you use with the Node SDK, e.g. your cloud region or self-hosted deployment), and a JWT you generate for the end user. The component issues authenticated requests to that API. Optional allowCustomization enables copy-on-write forks; darkMode, colorPreset, theme, and branding cover look-and-feel and white-label copy.

On the server, use the Node SDK to sign a tenant-scoped token (e.g. createJwt with tenantId, userId, and scopes). Pass the resulting JWT to the browser; the embed sends it to QueryPanel — not a copy of your workspace private key.

Server: mint JWT, then client: one embed

// Your API route (Node) — e.g. matches /demo/embed “Run embed” flow
import { QueryPanelSdkAPI } from "@querypanel/node-sdk";

const qp = new QueryPanelSdkAPI(apiBaseUrl, privateKeyPem, organizationId);

const jwt = await qp.createJwt({
  tenantId: "tenant_abc",
  userId: "user_123",
  scopes: ["dashboards:read", "charts:read"],
});

// In your customer-facing React app:
import { QuerypanelEmbedded } from "@querypanel/react-sdk";

export function CustomerAnalytics() {
  return (
    <QuerypanelEmbedded
      dashboardId="YOUR_DASHBOARD_UUID"
      apiBaseUrl="https://api.querypanel.io" // same QueryPanel API base URL as the Node SDK
      jwt={jwt}
      allowCustomization
      darkMode
    />
  );
}

The live demo at /demo/embed pairs this with a session generator and a full-screen preview so you can validate the end-to-end flow in minutes.

Callbacks: onLoad, onError, onCustomize (when a customer forks). See the TypeScript QuerypanelEmbeddedProps type in the package for the full list.

Installation

npm install @querypanel/react-sdk
# or
pnpm add @querypanel/react-sdk
# or
yarn add @querypanel/react-sdk

Import the distributed CSS from the package when your bundler requires an explicit stylesheet entry (see package exports and README).

Custom NL-to-chart UI (provider)

If you are building a bespoke experience instead of the full embed, use QueryPanelProvider and wire your own /api/ask routes. This path gives you QueryInput, QueryResult, and loading/empty/error states.

QueryPanelProvider + useQueryPanel

import {
  QueryPanelProvider,
  QueryInput,
  QueryResult,
  LoadingState,
  EmptyState,
  ErrorState,
  useQueryPanel,
} from "@querypanel/react-sdk";

function App() {
  return (
    <QueryPanelProvider
      config={{
        askEndpoint: "/api/demo/ask",
        modifyEndpoint: "/api/demo/modify",
        colorPreset: "default",
      }}
    >
      <Dashboard />
    </QueryPanelProvider>
  );
}

function Dashboard() {
  const { query, result, isLoading, error, ask, modify, colorPreset } = useQueryPanel();
  // ... QueryInput, QueryResult, state components
}

Composable building blocks

Mix and match lower-level pieces — VegaChart, DataTable, ChartControls — for screens that you fully control. Same theming entry points as the provider.

import { VegaChart, DataTable, ChartControls } from "@querypanel/react-sdk";
import { getColorsByPreset } from "@querypanel/react-sdk/themes";

const colors = getColorsByPreset("ocean");
// <ChartControls ... /> <VegaChart spec={...} colors={colors} /> <DataTable ... />

Theming

Presets: default, sunset, emerald, ocean.

import { getColorsByPreset, createTheme } from "@querypanel/react-sdk/themes";

const customTheme = createTheme({
  colors: { primary: "#FF6B6B", secondary: "#4ECDC4" },
  borderRadius: "1rem",
  fontFamily: "Inter, sans-serif",
});

White-labeling

Components accept a colors prop; embeds support branding for toolbar and AI copy.

<VegaChart
  spec={spec}
  colors={{
    primary: "#YOUR_BRAND_COLOR",
    text: "#ffffff",
    muted: "#888888",
  }}
/>

Types

interface QueryResult {
  success: boolean;
  sql?: string;
  rows?: Array<Record<string, unknown>>;
  fields?: string[];
  chart?: {
    vegaLiteSpec?: Record<string, unknown>;
  };
}

More components & live examples

Beyond the embed and provider stack, the React SDK includes dashboard editors, AI chart flows, and many composable details. This page is a high-level map; for every prop, story, and edge case, use the interactive catalog.

Open Storybook — all components, controls, and docs

Start with the QuerypanelEmbedded and QueryPanelProvider stories, then explore inputs, states, and layout pieces as you need them.

License

MIT (per package README).