{"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,"search_vec":"'6.0.0':11 'activ':118 'aim':138 'analysi':35 'api':4,9,16,75,116,153 'applic':108 'base':107 'benefici':98 'browser':106 'browser-bas':105 'centric':49 'chain':90 'chart':111,145 'code':48 'code-centr':47 'common':114 'compat':66,77 'complex':94,144 'construct':19 'creation':96,142 'data':135,152 'declar':89 'defin':39 'develop':37 'differenti':84 'direct':52 'dynam':110 'enabl':36 'ensur':65 'environ':100 'evolv':132 'fluent':15 'generat':112 'grammar':32,71 'high':30 'high-level':29 'interact':40 'javascript':14,146 'json':23,53 'level':31 'like':101 'lite':3,8,22,64,81,126,150 'maintain':119 'major':59 'manipul':54 'manner':50 'notebook':103 'observ':102 'offer':87 'packag':56 'particular':97 'primarili':137 'programmat':18 'provid':12,128 'releas':121 'serv':26 'simplifi':93,140 'specif':24,95 'stabl':130 'structur':45 'syntax':91 'tie':122 'tool':133 'track':57 'under':69 'updat':127 'v6.x':72,82 'vega':2,7,21,63,80,125,147,149 'vega-lit':1,6,20,62,79,124,148 'version':10,60 'visual':34,41,70,136,151","created_at":"2026-04-21T19:19:07.078925+00:00","updated_at":"2026-04-21T19:19:07.078925+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://vega.github.io/vega-lite/","github":"https://github.com/vega/vega-lite-api","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vega-lite-api","openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-20","install_tag":null}}