{"id":16265,"library":"vega-lite-api","title":"Vega-Lite API","description":"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.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/vega/vega-lite-api","tags":["javascript","vega","vega-lite","visualization","data","api"],"install":[{"cmd":"npm install vega-lite-api","lang":"bash","label":"npm"},{"cmd":"yarn add vega-lite-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add vega-lite-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for rendering Vega-Lite specifications generated by the API.","package":"vega","optional":false},{"reason":"The underlying grammar for which this API generates specifications.","package":"vega-lite","optional":false},{"reason":"Provides a robust tooltip handler for interactive visualizations, commonly used with Vega and Vega-Lite.","package":"vega-tooltip","optional":true}],"imports":[{"note":"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.","wrong":"const vl = require('vega-lite-api');","symbol":"vl","correct":"import { vl } from 'vega-lite-api';"},{"note":"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.","symbol":"vl (global)","correct":"/* (after loading CDN scripts) */ vl.markBar();"}],"quickstart":{"code":"import { vl } from 'vega-lite-api';\nimport vega from 'vega';\nimport vegaLite from 'vega-lite';\n\n// In a browser environment, you would typically load vega, vega-lite, and vega-tooltip via CDN.\n// For Node.js or bundlers, you'd import them.\n// For this example, we mock the registration that happens in a browser.\n\nconst options = {\n  config: {\n    // vega-lite default configuration\n  },\n  init: (view) => {\n    // Example: enable horizontal scrolling for large plots\n    // if (view.container()) view.container().style[\"overflow-x\"] = \"auto\";\n  },\n  view: {\n    // view constructor options\n    loader: vega.loader({\n      baseURL: \"https://cdn.jsdelivr.net/npm/vega-datasets@1/\"\n    }),\n    renderer: \"canvas\"\n  }\n};\n\n// Simulate browser registration for demonstration\nconst mockGlobalVega = vega;\nconst mockGlobalVegaLite = vegaLite;\nif (typeof globalThis !== 'undefined') {\n  globalThis.vega = mockGlobalVega;\n  globalThis.vegaLite = mockGlobalVegaLite;\n}\n\nvl.register(mockGlobalVega, mockGlobalVegaLite, options);\n\nconst chartSpec = vl.markBar({ tooltip: true })\n  .data([\n    { a: \"A\", b: 28 },\n    { a: \"B\", b: 55 },\n    { a: \"C\", b: 43 },\n    { a: \"D\", b: 91 },\n    { a: \"E\", b: 81 }\n  ])\n  .encode(\n    vl.x().fieldQ(\"b\"),\n    vl.y().fieldN(\"a\"),\n    vl.tooltip([vl.fieldQ(\"b\"), vl.fieldN(\"a\")])\n  )\n  .toJSON();\n\n// In a real browser scenario, you would call .render().then(chart => document.body.appendChild(chart));\n// For a Node.js context, you would typically work with the JSON specification.\n\nconsole.log(JSON.stringify(chartSpec, null, 2));\n","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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).","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: require is not defined"},{"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`.","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.","error":"TypeError: vl.register is not a function"},{"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.","cause":"Using the deprecated `selection.empty()` method with a string argument, or applying it incorrectly, especially after the v5.0.0 breaking changes.","error":"TypeError: Cannot read properties of undefined (reading 'empty')"}],"ecosystem":"npm"}