Embed Vega Web Components - nyurik/vega GitHub Wiki

Vega-Embed documentation for the latest version is at https://github.com/vega/vega-embed

This wiki documents Vega version 2. For Vega 3 documentation, see vega.github.io/vega.

Wiki ▸ Documentation ▸ Embed Vega Web Components

The vega-embed module provides advanced support for embedding interactive Vega views into web pages. The primary features include:

• Load Vega specs from source text, parsed JSON, or URLs.
• Add action links such as "View Source" and "Open in Vega Editor".
• Parameterize visualizations with auto-generated dynamic query widgets.

This last feature provides a powerful and convenient way to interact with a visualization by adding interactive widgets such as sliders, text fields, dropdown menus, and radio boxes. For Vega specifications without interactive signals defined, vega-embed provides rewriting rules for injecting interactivity into an existing spec.

For examples of vega-embed in action, take a look at the "Parameterized" specs in the Vega Editor, including the interactive job voyager and configurable force layout.

To use the Vega embedding functionality, you'll need to load the corresponding JavaScript library. For development and debugging, import vega-embed.js in your HTML file. For production use, import vega-embed.min.js. Note that you should import vega-embed after you import Vega proper.

<script src="http://vega.github.io/vega-editor/vendor/d3.min.js" charset="utf-8"></script>
<script src="http://vega.github.io/vega-editor/vendor/vega.js" charset="utf-8"></script>
<script src="http://vega.github.io/vega-editor/vendor/vega-embed.js" charset="utf-8"></script>

As a result, the function vg.embed will be added to the top-level Vega (vg) object.

Similar to standard Vega specifications, Vega embedding descriptions use a JSON format. Here is a basic example that adds an interactive slider to a map view, allowing users to rotate a globe.

{
  "parameters": [
    { 
      "signal": "rotate", "type": "range",
      "value": 0, "min": -360, "max": 360,
      "rewrite": ["data[0].transform[0].rotate"]
    }
  ],
  "spec": {
    "width": 800,
    "height": 500,
    "padding": 0,
    "data": [
      {
        "name": "world",
        "url": "data/world-110m.json",
        "format": {"type": "topojson", "feature": "countries"},
        "transform": [{
          "type": "geopath",
          "projection": "winkel3",
          "scale": 170,
          "translate": [400, 250]
        }]
      }
    ],
    "marks": [
      {
        "type": "path",
        "from": {"data": "world"},
        "properties": {
          "enter": {
            "stroke": {"value": "#fff"}
          },
          "update": {
            "path": {"field": "layout_path"},
            "fill": {"value": "#ccc"}
          },
          "hover": {
            "fill": {"value": "pink"}
          }
        }
      }
    ]
  }
}

The spec property contains a standard Vega specification, in this case defining a world map visualization. The parameters property contains an array of parameter definitions. Here, we define a single parameter for the rotate signal, with a type of range (specifying a slider control), and provide min, max, and initial value settings for the range.

At this point you may have noticed an important detail: the visualization specification has no signals defined, and the geopath transform doesn't even have a rotation parameter defined! (Note that geopath does support a rotate option, which defaults to 0 and was omitted from the original spec.) To address these issues, our parameter definition includes a rewrite rule.

Each re-write rule is a JSON access path string that points to a place in the Vega specification we would like to parameterize. Here we include a single rewrite rule of data[0].transform[0].rotate, which says to add a rotate parameter to the first transform of the first data source.

Based on the provided parameter definitions, the vega-embed module will first check to see if the signals modified by the parameters exist in the spec. If not, it will add them in a modified spec. It will then process the rewrite rules, either overwriting existing properties or adding new ones to reference the appropriate signal.

The end result is a new, extended Vega specification that is then parsed and used to instantiate a Vega View instance. In addition, the vega-embed module will generate a set of appropriate HTML input elements (sliders, radio buttons, etc), complete with two-way data binding to the signal values of the view.

Once you have your embedding specification defined, you can add an embedded view to a web page using the vg.embed function. The embed function accepts the following arguments:

<script>
vg.embed('#vis', embed_spec, function(error, result) {
  // Callback receiving the View instance and parsed Vega spec
  // result.view is the View, which resides under the '#vis' element
  // result.spec is the parsed spec
});
</script>

By default, the parameter input widgets are included in the web page under the same parent DOM element. However, you can specify an alternative container for the widgets by using the parameter_el property of the embedding specification. All generated widgets are standard HTML form elements which you can style using CSS. To see an example (including the various class names used for the embedded widgets), check out the vega-embed test CSS file.

Here is the complete vega-embed specification definition, broken down by category.

See how to set these parameters here.

Each parameter definition describes the signal to manipulate, interactive widget settings, and an optional set of rewrite rules for injecting signal references into a Vega specification.

Finally, parameter definitions for the "text" type may include additional properties so long as they are legal attributes of an HTML input tag. For example, "placeholder" (to set default prompt text) and "autocomplete" (to toggle browser-driven text autocomplete) are valid properties to include.

The vg.embed function can be configured to change the behavior of the action links. The following configuration properties can be set on the vg.embed.config object.

Re-writing rules provide a straightforward means of adding interactivity to specifications that were not initially designed to include it. However, there is one common pitfall you should always keep in mind: interactive updates require that any dynamic visual properties are defined within an update block. If instead all the property encodings reside in an enter block, they will not update in response to signal changes. So, if you add parameter widgets and the view is unresponsive, always check to make sure the necessary properties are included in update blocks!