Registry / data / vega-lite-api

vega-lite-api

JSON →
library6.0.0jsnpmunverified

The Vega-Lite API (version 6.0.0) provides a JavaScript fluent API for programmatically constructing Vega-Lite JSON specifications. It serves as a high-level grammar for visual analysis, enabling developers to define interactive visualizations in a more structured and code-centric manner than direct JSON manipulation. The package tracks the major version of Vega-Lite, ensuring compatibility with the underlying visualization grammar; v6.x of this API is compatible with Vega-Lite v6.x. It differentiates itself by offering a declarative chaining syntax that simplifies complex specification creation, particularly beneficial in environments like Observable notebooks or browser-based applications where dynamic chart generation is common. The API is actively maintained with releases tied to Vega-Lite updates, providing a stable and evolving tool for data visualization, primarily aimed at simplifying the creation of complex charts.

npm install vega-lite-api
INSTALL
IMPORT
SIG · VEGA-LITE-API
V
vega-lite-api
datajavascriptv6.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

vl
import { vl } from 'vega-lite-api';
const vl = require('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.

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));
Debug
Known issues
breakingVersion 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`.
affects: >=6.0.0
breakingVersion 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.
affects: >=5.0.0
gotchaWhen 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.
affects: >=4.0.0
gotchaThe 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.
affects: >=4.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
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
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')
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.
Upgrade
Version history
6.0.0latest on npm
Audit
Dependencies
vegarequiredRequired for rendering Vega-Lite specifications generated by the API.
vega-literequiredThe underlying grammar for which this API generates specifications.
vega-tooltipoptionalProvides a robust tooltip handler for interactive visualizations, commonly used with Vega and Vega-Lite.
Agent activity
26 hits · last 30 days
node
22
Amazon
1
OpenAI (training)
1
Resources