@querypanel/react-sdk

React components for QueryPanel - AI-powered data visualization.

Installation

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

Quick Start

Using the Provider (Recommended)

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

  return (
    <div>
      <QueryInput
        value={query}
        onSubmit={ask}
        isLoading={isLoading}
        chips={[
          { key: "sales", text: "Show sales by month", emoji: "📈" },
          { key: "top", text: "Top 10 products", emoji: "🏆" },
        ]}
      />

      {isLoading && !result && <LoadingState />}
      {error && <ErrorState message={error} />}
      {!isLoading && !error && !result && <EmptyState />}
      {result && (
        <QueryResult
          result={result}
          query={query}
          isLoading={isLoading}
          colorPreset={colorPreset}
          onModify={modify}
        />
      )}
    </div>
  );
}

Using Individual Components

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

function MyChart({ spec, data, fields }) {
  const colors = getColorsByPreset("ocean");

  return (
    <div>
      <ChartControls
        fields={fields}
        onApply={(options) => console.log(options)}
      />
      <VegaChart spec={spec} colors={colors} />
      <DataTable rows={data} fields={fields} />
    </div>
  );
}

Components

QuerypanelEmbedded

Embeds a deployed dashboard by calling the QueryPanel API from the browser. Set apiBaseUrl to the same QueryPanel API base URL you use with the Node SDK (e.g. https://api.querypanel.io or your region/self-hosted host). Authenticate with a JWT you mint on your server (RS256) — never ship your workspace private key to the client.

import { QuerypanelEmbedded } from "@querypanel/react-sdk";

function CustomerPage() {
  return (
    <QuerypanelEmbedded
      dashboardId="3ed3b98f-..."
      apiBaseUrl="https://api.querypanel.io"
      jwt={tenantJwtFromYourServer}
      allowCustomization={true}
    />
  );
}

Notes:

• The embed sends Authorization: Bearer <jwt> to apiBaseUrl (QueryPanel API).
• Mint the JWT with the Node SDK (createJwt, etc.) on your server; pass only the JWT to the client.
• The old token prop was removed in favor of jwt.

QueryInput

Search input with prompt chips for quick queries.

VegaChart

Renders Vega-Lite specifications with automatic theming.

DataTable

Displays query results in a styled table.

ChartControls

Controls for modifying chart type, axes, time granularity, and colors.

QueryResult

Combined display of chart, SQL, and data table.

LoadingState, ErrorState, EmptyState

UI states for loading, errors, and empty results.

Theming

Color Presets

Built-in presets: default, sunset, emerald, ocean

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

const colors = getColorsByPreset("sunset");

Custom Theme

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

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

White-Labeling

All components accept a colors prop for custom styling:

<VegaChart
  spec={spec}
  colors={{
    primary: "#YOUR_BRAND_COLOR",
    range: ["#color1", "#color2", "#color3"],
    text: "#ffffff",
    muted: "#888888",
    // ...
  }}
/>

Types

interface ThemeColors {
  primary: string;
  secondary: string;
  tertiary: string;
  accent: string;
  range: string[];
  text: string;
  muted: string;
  grid: string;
  background: string;
  surface: string;
  border: string;
  error: string;
}

interface QueryResult {
  success: boolean;
  sql?: string;
  rows?: Array<Record<string, unknown>>;
  fields?: string[];
  chart?: {
    vegaLiteSpec?: Record<string, unknown>;
    specType: "vega-lite" | "vizspec";
  };
}

License

MIT