Package Exports

@querypanel/react-sdk
@querypanel/react-sdk/dist/index.css
@querypanel/react-sdk/themes

Readme

@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 your backend wrapper (not QueryPanel API directly from the browser).

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

function CustomerPage() {
  return (
    <QuerypanelEmbedded
      dashboardId="3ed3b98f-..."
      apiBaseUrl="https://customer-api.example.com"
      allowCustomization={true}
    />
  );
}

Notes:

Browser requests go to your backend URL.
Backend handles auth and tenant context server-side.
token prop was removed; migrate to backend-managed auth/session.

`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