React Wrapper for Vega/Vega-Lite Visualizations

Common errors

• Error: "spec.data" is not a function

  cause Attempting to update data directly on the `spec` object passed to `VegaEmbed` or `useVegaEmbed` after initial render.
  fix Data in Vega/Vega-Lite is updated via the View API. Use the `useVegaEmbed` hook to get the `view` object and call `view.data('source_name').change(...)`.

• TypeError: Cannot read properties of null (reading 'view')

  cause Attempting to access the `view` property from the `useVegaEmbed` result before the embedding process is complete, when `result` is still `null`.
  fix Conditionally render or access `result.view` only when `result` is not `null`. The `useVegaEmbed` hook returns `null` initially and then the `Result` object once `vega-embed` resolves.

• TS2307: Cannot find module 'react-vega' or its corresponding type declarations.

  cause The `react-vega` package is not installed, or TypeScript cannot locate its declaration files (e.g., missing `@types/react` or misconfigured `tsconfig.json`).
  fix Ensure `react-vega`, `vega-embed`, `vega-lite` (and optionally `vega`) are installed via `npm i react-vega vega-embed vega-lite` (and `npm i vega`), and `react` types are present if using TypeScript (`npm i -D @types/react @types/react-dom`). Verify `tsconfig.json` includes `"jsx": "react"` or `"react-jsx"`.

Warnings

• breaking The `data` prop was removed in v8.0.0. Direct data updates via `spec.data` will no longer re-render the view without re-embedding. Use the Vega View API for dynamic data updates.
  Fix: Migrate to using the `useVegaEmbed` hook to access the Vega View API and update data using `view.data('source_name').insert/remove/change()`. Refer to the 'Dynamic data' recipe in the documentation.
• breaking The `height` and `width` props were removed in v8.0.0. Changing `spec.width` or `spec.height` will not resize the view without re-embedding. Use the Vega View API for programmatic resizing.
  Fix: Utilize the `useVegaEmbed` hook to obtain the Vega View API and call `view.resize()` or `view.width()/height()` directly. See the 'Programmatically changing width & height' recipe.
• breaking The `signalListeners` prop was removed in v8.0.0. Subscribing to signal events must now be done via the Vega View API.
  Fix: With the `useVegaEmbed` hook, get the `view` object from the result and use `view.addSignalListener('signalName', handlerFunction)` to subscribe to signals. Check the 'Subscribe to signal events' recipe.
• breaking Vega embed `options` are no longer flattened as direct props on the `<VegaEmbed />` component since v8.0.0. They must now be passed as a single object to the `options` prop.
  Fix: Consolidate all `vega-embed` specific options into a single object and pass it to the `options` prop: `<VegaEmbed spec={mySpec} options={{ actions: false, renderer: 'svg' }} />`.
• gotcha Any changes to the `spec` or `options` props of `<VegaEmbed />` (or `useVegaEmbed` params) will cause the entire Vega view to be torn down and re-embedded, leading to a full re-render and loss of interactive state.
  Fix: For dynamic updates to data, dimensions, or signal listeners that should preserve interaction state, use the Vega View API obtained via the `useVegaEmbed` hook. Only change `spec` or `options` when a complete re-initialization of the visualization is desired.

Install

• npm install react-vega npm
• yarn add react-vega yarn
• pnpm add react-vega pnpm

Imports

• VegaEmbed
  wrong:

  const VegaEmbed = require('react-vega').VegaEmbed;

  correct:

  import { VegaEmbed } from 'react-vega';

  Primary component for embedding. CommonJS `require` is not officially supported and may lead to issues with modern build setups. The library primarily targets ESM.
• useVegaEmbed
  wrong:

  const useVegaEmbed = require('react-vega').useVegaEmbed;

  correct:

  import { useVegaEmbed } from 'react-vega';

  React hook for more granular control over the Vega view, especially for dynamic updates. Like `VegaEmbed`, it's designed for ESM.
• VisualizationSpec
  wrong:

  import { VisualizationSpec } from 'react-vega';

  correct:

  import type { VisualizationSpec } from 'react-vega';

  This is a TypeScript type import. Attempting to import it as a value will result in a runtime error or build failure in strict environments. It is re-exported from `vega-embed`.

Quickstart

This example demonstrates embedding a static Vega-Lite bar chart using the `VegaEmbed` component.

import React from 'react';
import { VegaEmbed } from 'react-vega';

const spec = {
  $schema: 'https://vega.github.io/schema/vega-lite/v5.json',
  description: 'A simple bar chart with embedded data.',
  data: { values: [
    {a: 'A', b: 28},
    {a: 'B', b: 55},
    {a: 'C', b: 43},
    {a: 'D', b: 91},
    {a: 'E', b: 81},
    {a: 'F', b: 53},
    {a: 'G', b: 19},
    {a: 'H', b: 87},
    {a: 'I', b: 12}
  ]},
  mark: 'bar',
  encoding: {
    x: {field: 'a', type: 'nominal', axis: {labelAngle: 0}},
    y: {field: 'b', type: 'quantitative'}
  }
};

const options = {
  actions: false // Disable default actions like 'Export as SVG/PNG'
};

function MyVegaChart() {
  return (
    <div>
      <h1>My Interactive Chart</h1>
      <VegaEmbed spec={spec} options={options} />
    </div>
  );
}

export default MyVegaChart;