vega-lib-embed

Publish Vega visualizations as embedded web components.

Usage no npm install needed!

<script type="module">
  import vegaLibEmbed from 'https://cdn.skypack.dev/vega-lib-embed';
</script>

README

Vega-Embed

npm version

The Vega-Embed module provides advanced support for embedding interactive Vega views into web pages. Current version supports only Vega 3 / Vega-Lite 2. The primary features include:

  • Load Vega/Vega-Lite specs from source text, parsed JSON, or URLs.
  • Add action links such as "View Source" and "Open in Vega Editor".

As Vega 3's signal supports bind, the parameter property from the older version of Vega-Embed is now deprecated.

Basic Example

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.

<!DOCTYPE html>
<html>
<head>
  <!-- Import Vega 3 & Vega-Lite 2 (does not have to be from CDN) -->
  <script src="https://cdn.jsdelivr.net/npm/vega@[VERSION]"></script>
  <script src="https://cdn.jsdelivr.net/npm/vega-lite@[VERSION]"></script>
  <!-- Import vega-embed -->
  <script src="https://cdn.jsdelivr.net/npm/vega-embed@[VERSION]"></script>
</head>
<body>

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

<script type="text/javascript">
  var spec = "https://raw.githubusercontent.com/vega/vega/master/docs/examples/bar-chart.vg.json";
  vegaEmbed('#vis', spec).then(function(result) {
    // access view as result.view
  }).catch(console.error);
</script>
</body>
</html>

Look at an example online at Vega-Embed Block.

API Reference

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

Returns a Promise* that resolves to the instantiated Vega View instance and a copy of the parsed JSON Vega spec. The embed function accepts the following arguments:

Property Type Description
el String A DOM element or CSS selector indicating the element on the page in which to add the embedded view.
spec String / Object String : A URL string** from which to load the Vega specification.
Object : The Vega/Vega-Lite specification as a parsed JSON object.
opt     Object   (Optional) A JavaScript object containing options for embedding.

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

**This URL will be subject to standard browser security restrictions. Typically this URL will point to a file on the same host and port number as the web page itself.

Vega Embed opt Specification Reference

var opt = {
  "mode": ...,

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

  "onBeforeParse" : ...,

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

  "actions" : ...,

  "config"  : ...,

  "editorUrl": ...,

  "sourceHeader" : ...,
  "sourceFooter": ...
}
Property Type Description
mode String If specified, tells Vega-Embed to parse the spec as vega or vega-lite. Vega-Embed will parse the $schema url if the mode is not specified. Vega-Embed will default to vega if neither mode, nor $schema are specified.
renderer String The renderer to use for the view. One of "canvas" (default) or "svg". See Vega docs for details.
logLevel Level Sets the current log level. See Vega docs for details.
loader Loader Sets a custom Vega loader. See Vega docs for details.
onBeforeParse Function Modifies the spec before it is being parsed.
width Number Sets the view width in pixels. See Vega docs for details. Note that Vega-Lite overrides this option.
height Number Sets the view height in pixels. See Vega docs for details. Note that Vega-Lite overrides this option.
padding Object Sets the view padding in pixels. See Vega docs for details.
actions Boolean / Object Determines if action links ("Export as PNG/SVG", "View Source", "Open in Vega Editor") are included with the embedded view. If the value is true (default), all action links will be shown and none if the value is false. This property can take a key-value mapping object that maps keys (export, source, editor) to boolean values for determining if each action link should be shown. Unspecified keys will be true by default. For example, if actions is {export: false, source: true}, the embedded visualization will have two links – "View Source" and "Open in Vega Editor".
config String / Object String : A URL string** from which to load a Vega/Vega-Lite configuration file.
Object : A Vega/Vega-Lite configuration as a parsed JSON object to override the default configuration options or specify a theme.
editorUrl String The URL at which to open embedded Vega specs in a Vega editor. Defaults to "http://vega.github.io/editor/". Internally, Vega-Embed uses HTML5 postMessage to pass the specification information to the editor.
sourceHeader String HTML to inject into the `` tag of the page generated by the "View Source" action link. For example, this can be used to add code for syntax highlighting.
sourceFooter String HTML to inject into the end of the page generated by the "View Source" action link. The text will be added immediately before the closing `` tag.

**This URL will be subject to standard browser security restrictions. Typically this URL will point to a file on the same host and port number as the web page itself.

Build Process

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

  1. Run npm install in the Vega-Embed folder to install dependencies.
  2. Run npm run build. This will invoke browserify with tsify to bundle the source files into vega-embed.js, and then uglify-js to create the minified vega-embed.min.js.
  3. Run a local webserver (e.g., python -m SimpleHTTPServer 8000) in the Vega-Embed folder and then point your web browser at the test page (e.g., http://localhost:8000/test.html).

Usage in Observable

Check out this example.