Vega-Embed

Vega-Embed makes it easy to embed interactive Vega and Vega-Lite views into web pages. With Vega Embed, you can:

• Load Vega/Vega-Lite specs from source text, parsed JSON, or URLs.
• Patch Vega specs (even ones generated from Vega-Lite) to add additional functionality; for example, see Rotating Earth.
• Add action links such as "View Source" and "Open in Vega Editor".
• Includes Vega Tooltip.
• Includes Vega Themes. Experimental: themes are not stable yet

Vega-Lite works well with Observable. Learn how to use it in our example notebook.

Basic Examples

Directly in the Browser

You can import Vega-Embed from a local copy or (as shown below) from jsDelivr. Please replace [VERSION] with the correct Vega, Vega-Lite, and Vega-Embed versions. We recommend that you specify the major versions (vega@5, vega-lite@5, vega-embed@6).

  
  
  
  
  



<div id="vis"></div>

Look at the example online in the Vega-Embed Block.

JavaScript or TypeScript

The basic example below needs to be transpiled and bundled (using rollup, webpack, etc..) before it can be loaded in a browser.

import embed from 'vega-embed';

const spec = {
  ...
}

const result = await embed('#vis', spec);

console.log(result.view);

In Observable

You can require embed with embed = require('vega-embed@6') and then embed a chart with viewof view = embed(...). Check the our example notebook for more details.

API Reference

When using a script tag, the default export of Vega-Embed is a wrapper function that automatically chooses between embed and container based on the provided arguments. Vega-Embed provides this convenience for imports in interactive environments like Observable. When using the Vega-Embed npm package, the default export is the embed function.

# embed(el, spec[, opt]) <>

Returns a Promise that resolves to a result object. The result object contains:

The embed function accepts the following arguments:

Note: Internet Explorer does not support the ES6 Promise feature. To make it work correctly, please follow the instructions on the Vega website.

# container(spec[, opt]) <>

Returns a Promise* that resolves to an HTML element with the Vega View instance as the value property. The function is designed to work with Observable. The container function accepts the following arguments:

Options

You can configure Vega Embed with an options object. You can pass options as an argument to the embed function or as usermeta.embedOptions as part of the Vega or Vega-Lite specification.

var opt = {
  mode: ...,

  config: ...,
  theme: ...,

  defaultStyle: ...,

  bind: ...,

  // view config options
  renderer: ...,
  loader: ...,
  logLevel: ...,

  tooltip: ...,

  patch: ...,

  width: ...,
  height: ...,
  padding: ...,

  actions: {
    export: ...,
    source: ...,
    compiled: ...,
    editor: ...
  },

  scaleFactor: ...,

  editorUrl: ...,

  sourceHeader: ...,
  sourceFooter: ...,

  hover: {
    hoverSet: ...,
    updateSet: ...,
  },

  downloadFileName: ...,

  formatLocale: ...,
  timeFormatLocale: ...,
  expressionFunctions: ...,

  ast: ...,
  expr: ...,

  i18n: {
    COMPILED_ACTION: ...,
    EDITOR_ACTION: ...,
    PNG_ACTION: ...,
    SOURCE_ACTION: ...,
    SVG_ACTION: ...
  }
}

Common questions

How do I send cookies when loading data?

By default, the Vega loader does not send the credentials of the current page with requests. You can override this behavior by passing {loader: { https: { credentials: 'same-origin' }}} as the embed option.

What CSS should I use to support container sizing?

When using container sizing in Vega-Lite, make sure to set the width of the DOM element you passed to Embed.

Build Process

To build vega-embed.js and view the test examples, you must have Yarn 1 installed.

1. Run yarn in the Vega-Embed folder to install dependencies.
2. Run yarn build. This will create vega-embed.js and the minified vega-embed.min.js.
3. Run a local webserver with yarn start then point your web browser at the test page (e.g., https://localhost:8000/test-vg.html(Vega) or https://localhost:8000/test-vl.html(Vega-Lite)).

Publishing

To make a release, run npm run release.