2c:null 2d:["$","title",null,{"children":"Vega-Lite API v6 | John Alexis Guerra Gómez | Observable"}] 32:T45c,md`The [Vega-Lite JavaScript API](https://github.com/vega/vega-lite-api/) provides a convenient way to write [Vega-Lite](https://vega.github.io/vega-lite) specifications in a programmatic fashion. Scroll down for some usage examples, or browse the [Vega-Lite API example collection](https://observablehq.com/collection/@vega/vega-lite-api)! _This notebook uses **version 6** of Vega-Lite and the corresponding Vega-Lite API v6._ To see what's new in version 6, [have a look at the changelog](https://github.com/vega/vega-lite/releases/tag/v6.0.0). To use Vega-Lite version 5, see the [Vega-Lite API v5 notebook](https://observablehq.com/@vega/vega-lite-api-v5) instead. To use Vega-Lite version 4, see the [Vega-Lite API v4 notebook](https://observablehq.com/@vega/vega-lite-api) instead. Want to learn more about data visualization and how to use the Vega-Lite API? Read the [introduction to Vega-Lite](https://observablehq.com/@uwdata/introduction-to-vega-lite) and the [data visualization curriculum](https://observablehq.com/@uwdata/data-visualization-curriculum?collection=@uwdata/visualization-curriculum).`33:T403,vl = { const [vega, vegalite, api, tooltip] = await Promise.all([ `https://cdn.jsdelivr.net/npm/vega@${vegaVersion}/+esm`, `https://cdn.jsdelivr.net/npm/vega-lite@${vlVersion}/+esm`, `https://cdn.jsdelivr.net/npm/vega-lite-api@${apiVersion}/+esm`, `https://cdn.jsdelivr.net/npm/vega-tooltip@${tooltipVersion}/+esm` ].map(module => import(module))); const options = { config: { // vega-lite default configuration config: { view: {continuousWidth: 400, continuousHeight: 300}, mark: {tooltip: null} } }, init: view => { // initialize tooltip handler view.tooltip(new tooltip.Handler().call); // 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@2/'}), renderer: 'canvas' } }; return api.register(vega, vegalite, options); }34:T53c,{ const brush = vl.selectInterval().encodings('x'); const click = vl.selectPoint().encodings('color'); const scale = { domain: ['sun', 'fog', 'drizzle', 'rain', 'snow'], range: ['#e7ba52', '#a7a7a7', '#aec7e8', '#1f77b4', '#9467bd'] }; const plot1 = vl.markPoint({filled: true}) .encode( vl.color().value('lightgray') .if(brush, vl.color().fieldN('weather').scale(scale).title('Weather')), vl.size().fieldQ('precipitation').scale({domain: [-1, 50], range: [10, 500]}).title('Precipitation'), vl.order().fieldQ('precipitation').sort('descending'), vl.x().timeMD('date').axis({title: 'Date', format: '%b'}), vl.y().fieldQ('temp_max').scale({domain: [-5, 40]}).axis({title: 'Maximum Daily Temperature (°C)'}) ) .width(width) .height(300) .params(brush) .transform(vl.filter(click)); const plot2 = vl.markBar() .encode( vl.color().if(click, vl.color().fieldN('weather')).value('lightgray') .scale(scale).title('Weather'), vl.x().count(), vl.y().fieldN('weather').scale({domain: scale.domain}).title('Weather') ) .width(width) .params(click) .transform(vl.filter(brush)); return vl.vconcat(plot1, plot2) .data('data/seattle-weather.csv') .autosize({type: 'fit-x', contains: 'padding'}) .render(); }35:T677,{ const domain = [ 'Beak Length (mm)', 'Beak Depth (mm)', 'Flipper Length (mm)', 'Body Mass (g)' ]; const scale = { type: 'point', padding: 0 }; const axis = { domain: false, ticks: false, title: false, grid: true, gridColor: '#888', labelAngle: 0, labelPadding: 8, labelFontWeight: 'bold' }; const lines = vl.markLine({ strokeWidth: 1.5, opacity: 0.5 }) .encode( vl.color().fieldN('Species').sort('descending'), vl.detail().fieldN('index'), vl.x().fieldO('key').scale(scale).axis(axis), vl.y().fieldQ('fraction').axis(null) ); const labels = vl.markText({ dx: -2, align: 'right', baseline: 'middle' }) .transform( vl.groupby('key').aggregate(vl.min('value').as('min'), vl.max('value').as('max')), vl.fold('min', 'max').as('op', 'value'), vl.groupby('key').window(vl.percent_rank('value').as('fraction')) ) .encode( vl.x().fieldN('key'), vl.y().fieldQ('fraction').axis(null), vl.text().field('value').format(',') ); const plot = vl.layer(lines, labels) .data('data/penguins.json') .transform( vl.filter('datum["Beak Length (mm)"] != null'), vl.window(vl.row_number().as('index')), vl.fold(domain).as('key', 'value'), vl.groupby('key').join(vl.min('value').as('min'), vl.max('value').as('max')), vl.calculate('(datum.value - datum.min) / (datum.max - datum.min)').as('fraction') ) .width(width) .height(300) .autosize({type: 'fit-x', contains: 'padding'}) return plot.render({renderer: 'svg'}); }36:T867,standalone_use = md`

## Stand-Alone Usage in a Web Browser To use the Vega-Lite API in the browser outside of Observable, you need to include all the dependencies, set the default configuration, and then register the Vega libraries. Here is some starting code to build from: ~~~html

~~~`37:[] 30:{"id":"12a304c114eacf25","slug":"vega-lite-api-v6","title":"Vega-Lite API v6","thumbnail":"42ea32ae977b774c3708dcabc05b9a3c3cc3ab7d59acb79e387f8a48493e9f5b","access_level":"public","create_time":"$D2025-11-02T09:39:29.914Z","update_time":"$D2025-11-05T12:44:15.979Z","view_time":null,"first_public_time":"$D2025-11-02T09:47:29.132Z","has_unpublished_edits":null,"fork":{"id":"cc6863a92d3c907e","slug":"vega-lite-api-v6","title":"Vega-Lite API v6","owner":{"id":"faa3d64559fbe807","login":"vega","name":"Vega"}},"stars":0,"starred":false,"owner":{"type":"team","id":"cd3c1e49fc84d010","login":"john-guerra","name":"John Alexis Guerra Gómez","avatar_url":"https://avatars-next.observableusercontent.com/21638cee44bb0ea70798da725b57111a5d3e2acebcd14524565992f7d1594aed","tier":"starter_2024"},"version":248,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"be0076fec73aa550","login":"john-guerra","name":"John Alexis Guerra Gómez","avatar_url":"https://avatars-next.observableusercontent.com/21638cee44bb0ea70798da725b57111a5d3e2acebcd14524565992f7d1594aed","tier":null}],"members":[{"type":"individual","id":"be0076fec73aa550","login":"john-guerra","name":"John Alexis Guerra Gómez","avatar_url":"https://avatars-next.observableusercontent.com/21638cee44bb0ea70798da725b57111a5d3e2acebcd14524565992f7d1594aed","tier":null,"role":"editor"},{"type":"team","id":"cd3c1e49fc84d010","login":"john-guerra","name":"John Alexis Guerra Gómez","avatar_url":"https://avatars-next.observableusercontent.com/21638cee44bb0ea70798da725b57111a5d3e2acebcd14524565992f7d1594aed","tier":"starter_2024","role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"titling":"auto","title":"Vega-Lite API v6","cells":[{"id":0,"value":"md`# Vega-Lite API v6`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":5,"value":"$32","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":10,"value":"md`\nThe cell below imports the Vega-Lite API and registers the desired versions of Vega and Vega-Lite, along with default [Vega View options](https://vega.github.io/vega/docs/api/view/#view) and [Vega-Lite configuration](https://vega.github.io/vega-lite/docs/config.html):\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":13,"value":"$33","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":46,"value":"apiVersion = '6.0.0'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":190,"value":"vlVersion = '6.4.1'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":193,"value":"vegaVersion = '6.2.0'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":196,"value":"tooltipVersion = '1.1.0'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":218,"value":"To use the same setup in your own notebooks, add a cell with the following code:\n~~~ js\nimport {vl} from '@vega/vega-lite-api-v6'\n~~~\nThis notebook also exports a `render(spec)` method, a convenience method for rendering Vega-Lite JSON specs with the same configuration as the JS API.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":210,"value":"function render(spec) {\n return vl.render({ spec });\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":215,"value":"To use the API outside of Observable, see the [stand-alone usage instructions](#standalone_use) below.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":21,"value":"zip_codes = md`

\n## Zip Codes\n\nA dot for each zip code in the United States, colored by the first digit.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":24,"value":"vl.markSquare({size: 2, opacity: 1})\n .data('data/zipcodes.csv')\n .transform(vl.calculate('substring(datum.zip_code, 0, 1)').as('digit'))\n .project(\n vl.projection('albersUsa')\n )\n .encode(\n vl.longitude().fieldQ('longitude'),\n vl.latitude().fieldQ('latitude'),\n vl.color().fieldN('digit'),\n )\n .width(width)\n .height(Math.floor(width / 1.75))\n .autosize({type: 'fit-x', contains: 'padding'})\n .config({view: {stroke: null}})\n .render()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":26,"value":"interactive_weather = md`

\n## Interactive Seattle Weather 2012-2015\n\nA scatter plot and summary histogram with linked selections between plots to perform cross-filtering and configure conditional color encodings.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":29,"value":"$34","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":119,"value":"population_pyramid = md`

\n## Population Pyramid\n\nA [population pyramid](https://en.wikipedia.org/wiki/Population_pyramid) shows the distribution of age groups in a population. Drag the slider to see the U.S. change over time, but watch out for [missing data in 1890!](https://www.census.gov/history/www/faqs/genealogy_faqs/why_cant_i_find_1890_census_records.html) The slider is generated internally by binding the \\`Year\\` parameter using \\`vl.slider()\\`.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":86,"value":"vl.markBar({ opacity: 0.4 })\n .params(\n vl.param('Year').value(2000).bind(vl.slider(1850, 2000, 10))\n )\n .data('data/population.json')\n .transform(\n vl.calculate('datum.sex === 1 ? \"Male\" : \"Female\"').as('sex'),\n vl.filter('datum.year === Year')\n )\n .encode(\n vl.x().sum('people').scale({ domain: [0, 12e6] }).stack(null).title('People'),\n vl.y().fieldO('age').sort('descending').title('Age'),\n vl.color().fieldN('sex').scale({ range: ['#675193', '#ca8861'] }).title('Sex')\n )\n .height(300) // fix the height to keep stability over missing data\n .render()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":153,"value":"bind_external = md`### Bind Parameters to External Inputs\n\nAs an alternative to having Vega-Lite generate its own input widgets (as with \\`vl.slider()\\` above), we can also directly bind a Vega-Lite parameter to an existing widget, such as Observable's \\`Range\\` component:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":141,"value":"import {Range} from '@observablehq/inputs'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":146,"value":"viewof year = Range([1850, 2000], { step: 10, value: 2000 })","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":144,"value":"vl.markBar({ opacity: 0.4 })\n .params(\n // use viewof to bind to the input element (the view), not the numeric year value\n vl.param('Year').bind(viewof year)\n )\n .data('data/population.json')\n .transform(\n vl.calculate('datum.sex === 1 ? \"Male\" : \"Female\"').as('sex'),\n vl.filter('datum.year === Year')\n )\n .encode(\n vl.x().sum('people').scale({ domain: [0, 12e6] }).stack(null).title('People'),\n vl.y().fieldO('age').sort('descending').title('Age'),\n vl.color().fieldN('sex').scale({ range: ['#675193', '#ca8861'] }).title('Sex')\n )\n .height(300)\n .render()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":69,"value":"dynamic_scatter = md`

\n## Dynamic Query Scatter Plot\n\nA scatter plot of automobile mileage and horsepower. (Shift-)Click the legend and drag the slider to filter by Origin and Year.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":53,"value":"{\n const isOrigin = vl.selectPoint('isOrigin')\n .fields('Origin')\n .bind('legend'); // bind to legend interactions\n \n const isYear = vl.selectPoint('isYear')\n .fields('Year').value(1970)\n .bind(vl.slider(1970, 1980, 1).name('Year')); // bind to slider\n \n const show = vl.and(isOrigin, isYear); // combine selections\n\n return vl.markCircle()\n .data('data/cars.json')\n .transform(\n vl.calculate('year(datum.Year)').as('Year')\n )\n .params(isOrigin, isYear) // add selections to plot\n .encode(\n vl.x().fieldQ('Horsepower'),\n vl.y().fieldQ('Miles_per_Gallon'),\n vl.color().if(show, vl.color().fieldN('Origin')).value('grey'),\n vl.opacity().if(show, vl.value(1.0)).value(0.2)\n )\n .render();\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":36,"value":"parallel_coordinats = md`

\n## Parallel Coordinates\n\nA [parallel coordinates plot](https://en.wikipedia.org/wiki/Parallel_coordinates) that uses \\`window\\` and \\`fold\\` transforms to convert the four dimensions of penguin measurements into normalized coordinates that can be visualized as \\`line\\` marks. The graphic includes an additional layer with custom \\`text\\` mark labels for the parallel axis grid lines. We render the plot as SVG by passing \\`{renderer:'svg'}\\` to the \\`render\\` method.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":39,"value":"$35","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":42,"value":"$36","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":242,"value":"vl.markBar({ tooltip: true })\n .data([\n { a: \"A\", b: 28 }, { a: \"B\", b: 55 }, { a: \"C\", b: 43 },\n { a: \"D\", b: 91 }, { a: \"E\", b: 81 }, { a: \"F\", b: 53 },\n { a: \"G\", b: 19 }, { a: \"H\", b: 87 }, { a: \"I\", b: 52 },\n ])\n .encode(\n vl.x().fieldQ(\"b\"),\n vl.y().fieldN(\"a\"),\n vl.tooltip([vl.fieldQ(\"b\"), vl.fieldN(\"a\")])\n )\n .render()\n ","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W37","stdlib":"1"}} 31:"$30:body"