Vega-Lite API

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` to import `vega-lite-api` in a Node.js or bundled environment after version 6.0.0, which is ESM-only.
  fix Change your import statement to `import { vl } from 'vega-lite-api';`. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions for Node.js.

• TypeError: vl.register is not a function

  cause The `vega-lite-api` script might be loaded but the `vl.register` method is called without `vega` and `vegaLite` being available globally or passed correctly in a module context.
  fix In a browser, ensure `<script src="https://cdn.jsdelivr.net/npm/vega"></script>` and `<script src="https://cdn.jsdelivr.net/npm/vega-lite"></script>` are loaded before `<script src="https://cdn.jsdelivr.net/npm/vega-lite-api"></script>`, and `vl.register(vega, vegaLite, options)` is called. In a module environment, ensure `vega` and `vegaLite` are correctly imported and passed to `vl.register`.

• TypeError: Cannot read properties of undefined (reading 'empty')

  cause Using the deprecated `selection.empty()` method with a string argument, or applying it incorrectly, especially after the v5.0.0 breaking changes.
  fix Review your selection definitions. The `empty` method now takes a boolean (`true`/`false`) and should be applied to a predicate reference (e.g., `vl.selection().empty(false)`), not directly to the selection definition object. Refer to Vega-Lite v5+ documentation on parameters and selections.

Warnings

• breaking Version 6.0.0 of `vega-lite-api` switched to being an ESM-only package. This means it can no longer be `require()`-d in CommonJS environments (e.g., Node.js scripts without `--experimental-modules` or older bundler configurations).
  Fix: Migrate your project to use ES modules (`import`/`export`) or ensure your build tools/Node.js environment are configured to handle ESM. If running Node.js, ensure your package.json has `"type": "module"` or use the `.mjs` extension. For older Node.js, consider `--experimental-modules`.
• breaking Version 5.0.0 significantly revised the `selection` abstraction into a more general `parameters` abstraction. Specifically, the `selection.empty` method now expects a boolean argument instead of a string, and should be applied to a predicate reference to a selection, not directly to a selection definition.
  Fix: Review existing uses of `selection.empty`. Replace string arguments with `true` or `false`, and ensure it's applied to the correct part of the selection definition. Consult the Vega-Lite v5 documentation for the updated parameters API.
• gotcha When using `vega-lite-api` in a browser environment (e.g., via CDN), you must explicitly register the `vl` object with the `vega` and `vegaLite` global objects using `vl.register(vega, vegaLite, options)` before creating any charts.
  Fix: Ensure `vega.js` and `vega-lite.js` scripts are loaded *before* `vega-lite-api.js`, and call `vl.register(vega, vegaLite, options)` at the beginning of your charting script.
• gotcha The major version of `vega-lite-api` tracks the major version of `vega-lite`. Therefore, upgrading `vega-lite-api` to a new major version often implies that you should also upgrade `vega-lite` to the corresponding major version to maintain compatibility.
  Fix: Always check the `vega-lite-api` release notes for its compatible `vega-lite` version when performing a major version upgrade. Upgrade both packages concurrently to avoid compatibility issues.

Install

• npm install vega-lite-api npm
• yarn add vega-lite-api yarn
• pnpm add vega-lite-api pnpm

Imports

• vl
  wrong:

  const vl = require('vega-lite-api');

  correct:

  import { vl } from 'vega-lite-api';

  Since v6.0.0, vega-lite-api is an ESM-only package. CommonJS `require` is not supported. For browser environments, `vl` is also available globally after loading via CDN.
• vl (global)

  /* (after loading CDN scripts) */ vl.markBar();

  When used in a browser via CDN, the `vl` object is exposed globally. No explicit import statement is needed, but `vega` and `vegaLite` must also be loaded and registered.

Quickstart

This quickstart demonstrates how to create a simple bar chart using the Vega-Lite API. It includes the necessary imports and the critical `vl.register` step for browser or bundled environments, then builds a chart specification and outputs its JSON representation.

import { vl } from 'vega-lite-api';
import vega from 'vega';
import vegaLite from 'vega-lite';

// In a browser environment, you would typically load vega, vega-lite, and vega-tooltip via CDN.
// For Node.js or bundlers, you'd import them.
// For this example, we mock the registration that happens in a browser.

const options = {
  config: {
    // vega-lite default configuration
  },
  init: (view) => {
    // Example: enable horizontal scrolling for large plots
    // if (view.container()) view.container().style["overflow-x"] = "auto";
  },
  view: {
    // view constructor options
    loader: vega.loader({
      baseURL: "https://cdn.jsdelivr.net/npm/vega-datasets@1/"
    }),
    renderer: "canvas"
  }
};

// Simulate browser registration for demonstration
const mockGlobalVega = vega;
const mockGlobalVegaLite = vegaLite;
if (typeof globalThis !== 'undefined') {
  globalThis.vega = mockGlobalVega;
  globalThis.vegaLite = mockGlobalVegaLite;
}

vl.register(mockGlobalVega, mockGlobalVegaLite, options);

const chartSpec = vl.markBar({ tooltip: true })
  .data([
    { a: "A", b: 28 },
    { a: "B", b: 55 },
    { a: "C", b: 43 },
    { a: "D", b: 91 },
    { a: "E", b: 81 }
  ])
  .encode(
    vl.x().fieldQ("b"),
    vl.y().fieldN("a"),
    vl.tooltip([vl.fieldQ("b"), vl.fieldN("a")])
  )
  .toJSON();

// In a real browser scenario, you would call .render().then(chart => document.body.appendChild(chart));
// For a Node.js context, you would typically work with the JSON specification.

console.log(JSON.stringify(chartSpec, null, 2));