SQLRooms

Appearance

@sqlrooms/vega ​

Vega-Lite chart components and AI chart tool integration for SQLRooms.

Installation ​

bash
npm install @sqlrooms/vega @sqlrooms/duckdb @sqlrooms/ui

Main exports ​

  • VegaLiteChart (simple + compound component API)
  • createVegaChartTool() for AI tool workflows
  • createChartImageForMarkdownTool() for AI-generated Markdown document image assets
  • VegaChartToolResult
  • editor utilities/hooks (useVegaChartEditor, useVegaEditorContext)

Quick start (simple chart) ​

tsx
import {VegaLiteChart} from '@sqlrooms/vega';

export function SalesChart() {
  return (
    <VegaLiteChart
      sqlQuery="SELECT category, SUM(amount) AS total FROM sales GROUP BY category"
      spec={{
        mark: 'bar',
        encoding: {
          x: {field: 'category', type: 'nominal'},
          y: {field: 'total', type: 'quantitative'},
        },
      }}
      aspectRatio={16 / 9}
    />
  );
}

Compound component API (editable chart workflow) ​

tsx
import {VegaLiteChart, type VisualizationSpec} from '@sqlrooms/vega';

const initialSpec: VisualizationSpec = {
  mark: 'line',
  encoding: {
    x: {field: 'date', type: 'temporal'},
    y: {field: 'value', type: 'quantitative'},
  },
};

export function CompoundVegaChart() {
  return (
    <VegaLiteChart.Container
      spec={initialSpec}
      sqlQuery="SELECT date, value FROM metrics"
      editable
      onSpecChange={(spec) => console.log('next spec', spec)}
      onSqlChange={(sql) => console.log('next sql', sql)}
    >
      <VegaLiteChart.Actions />
      <VegaLiteChart.Chart />
      <VegaLiteChart.SpecEditor />
      <VegaLiteChart.SqlEditor />
    </VegaLiteChart.Container>
  );
}

AI integration (createVegaChartTool) ​

tsx
import {
  createAiSlice,
  createDefaultAiInstructions,
  createDefaultAiTools,
} from '@sqlrooms/ai';
import {
  createVegaChartTool,
  VegaChartToolResult,
  type VegaChartToolResultProps,
} from '@sqlrooms/vega';

// inside your createRoomStore composer
createAiSlice({
  tools: {
    ...createDefaultAiTools(store),
    chart: createVegaChartTool({
      editable: true,
      editorMode: 'both',
    }),
  },
  getInstructions: () => createDefaultAiInstructions(store),
})(set, get, store);

createVegaChartTool constructor options:

  • editable: whether users can edit SQL/spec in the chart UI
  • editorMode: which editors to render ('none' | 'sql' | 'vega' | 'both')

AI chart result sizing ​

VegaChartToolResult retains its default 16:9 layout when no sizing props are provided. Use height="auto" to opt into data-driven sizing for category-dense horizontal bar charts:

tsx
const CategoryAwareChartResult = (props: VegaChartToolResultProps) => (
  <VegaChartToolResult {...props} height="auto" />
);

createAiSlice({
  toolRenderers: {
    chart: CategoryAwareChartResult,
  },
  tools: {
    chart: createVegaChartTool(),
  },
});

The automatic policy inspects the parsed Vega-Lite encoding and counts distinct values in the loaded Arrow data. Horizontal bar charts with at least 12 categories use clamp(280, 48 + categoryCount * 22, 800) pixels; other charts continue to use aspectRatio (16:9 by default). Transformed and concatenated multi-view specs also use the aspect ratio because raw Arrow rows do not reflect their rendered data or panel layout. A numeric height fixes the outer chart viewport while preserving responsive width. Applications can also provide getHeight={({spec, arrowTable}) => ...} for a custom sizing policy; returning 'auto' delegates to the built-in category-aware policy.

Sizing is based on loaded query data rather than an LLM-provided row count, so it stays accurate when SQL results or application filters change. The Vega-Lite spec remains responsible for visualization semantics, not React layout.

LLM invocation / Zod schema fields ​

At runtime, the tool call payload is validated by a Zod schema.
These fields are supplied by the LLM when invoking the tool (not passed into createVegaChartTool(...)):

  • sqlQuery: SQL used to fetch chart data
  • vegaLiteSpec: Vega-Lite JSON string
  • reasoning: explanation shown to users for why this chart/spec was chosen

Markdown document image assets ​

createChartImageForMarkdownTool(store) creates an AI-only companion tool that renders a Vega chart to SVG or PNG, stores it as an asset on a @sqlrooms/documents Markdown artifact, and returns a ready-to-insert Markdown image link such as:

md
![Revenue by week](asset://chart-revenue-week)

Use this alongside the existing document commands when the assistant needs a portable conversation summary with static chart images instead of live SQL-backed charts.

Chart images default to the light Vega theme with an explicit background so exported Markdown renders predictably in GitHub, Obsidian, PDF exports, and other document surfaces. When the requested static theme matches the current app theme, the background is resolved from the app's Tailwind --background token and written into the SVG/PNG as a concrete color. The tool also accepts renderTheme: "dark" and background for explicit dark/static export requests.

Example apps ​

Interfaces ​

Type Aliases ​

Variables ​

Functions ​

References ​

ChartImageForMarkdownToolParametersType ​

Renames and re-exports ChartImageForMarkdownToolParameters

Copyright OpenJS Foundation and vis.gl contributors. All rights reserved. The OpenJS Foundation has registered trademarks and uses trademarks. For a list of trademarks of the OpenJS Foundation, please see our Trademark Policy and Trademark List. Trademarks and logos not indicated on the list of OpenJS Foundation trademarks are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

The OpenJS Foundation | Terms of Use | Privacy Policy | Bylaws | Code of Conduct | Trademark Policy | Trademark List | Cookie Policy