Signals

Signals are dynamic variables that parameterize a visualization and can drive interactive behaviors. Signals can be used throughout a Vega specification, for example to define a mark property or data transform parameter.

Signal values are reactive: they can update in response to input event streams, external API calls, or changes to upstream signals. Event streams capture and sequence input events, such as mousedown or touchmove. When an event occurs, signals with associated event handlers are re-evaluated in their specification order. Updated signal values then propagate to the rest of the specification, and the visualization is re-rendered automatically.

A signal definition, and its use in the rest of a specification, looks something like this:

{
  "signals": [
    {
      "name": "indexDate",
      "description": "A date value that updates in response to mousemove.",
      "update": "datetime(2005, 0, 1)",
      "on": [{"events": "mousemove", "update": "invert('xscale', x())"}]
    }
  ],
  "data": [
    { "name": "stocks", ... },
    {
      "name": "index",
      "source": "stocks",
      "transform": [
        {
          "type": "filter",
          "expr": "month(datum.date) === month(indexDate)"
        }
      ]
    }
  ],
  "scales": [
    { "name": "x", "type": "time", ... }
  ],
  "marks": [
    {
      "type": "rule",
      "encode": {
        "update": {
          "x": {"scale": "x", "signal": "indexDate"}
        }
      }
    }
  ]
}

Signal Properties

Signal definitions may use the following properties.

Built-in signals

A few signal names are automatically processed and/or reserved:

• Signals for the specification width, height, padding, autosize, and (for version ≥ 5.10) background properties are automatically defined. Specifications may include definitions for these signals in the top-level signals array, in which case the definitions will be merged with any top-level specification property values, with precedence given to properties defined in the signals array.
• Group mark instances automatically include a parent signal bound to the data object for that group. Specifications may not define a signal named parent.
• The signal names datum, item, and event are reserved for top-level variables within expressions. Specifications may not define signals named datum, item or event.
• If you define a signal named cursor, its value will automatically drive the CSS mouse cursor for the Vega view. For more, see the cursor signal documentation below.

The cursor Signal

By default, Vega will style the mouse pointer when it is over a mark with a defined cursor property. However, in some interactive use cases, the cursor style should persist for the entire duration of an interaction (e.g., while dragging, regardless if the cursor remains over the item where the drag initiated). For more control, Vega provides a dedicated cursor signal. When the value of this signal is set, Vega uses it in lieu of any cursor properties set on marks. If the value is set to "default", Vega resumes using the mark-based cursor property.

Nested Signals

Signals can be defined either in the top-level scope of a specification or within a group mark definition. If a signal is defined within a nested group, it is accessible only within the scope of that group; any marks, axes, legends, etc. that reference the signal must be contained within the group. If a nested signal has the same name as a signal defined in an outer scope, the new signal will override the previously defined signal.

In addition to new signal definitions, nested group marks may contain signal updates that target a signal defined in an outer scope. The "push": "outer" property indicates that, rather than create a new signal, updates should explicitly target an existing signal. Nested signal updates may not include value or update properties. The supported properties for signal updates are:

Event Handlers

An event handler object includes an event stream definition indicating which events to respond to, and either an update expression for setting a new signal value, or an encode set for updating the mark being interacted with.

This signal definition increments its value upon mouseover of rect items:

{
  "name": "count",
  "value": 0,
  "on": [
    {"events": "rect:mouseover", "update": "count + 1"}
  ]
}

This signal definition invokes a custom encoding set upon mousedown and mouseup on mark items. The mark definition must include properties named "select" and "release" under the mark "encode" property.

{
  "name": "clickEncode",
  "on": [
    {"events": "*:mousedown", "encode": "select"},
    {"events": "*:mouseup", "encode": "release"}
  ]
}

Input Element Binding

The bind property binds a signal to an input element defined outside of the visualization. Vega will generate new HTML form elements and set up a two-way binding: changes to the input element will update the signal, and vice versa. Vega includes dedicated support for checkbox (single boolean value), radio (group of radio buttons), select (drop-down menu), and range (slider) input types. Alternatively, Vega can also bind directly to externally-defined input elements.

Radio and Select Input Properties

Range Input Properties

Other Input Types

In addition, any valid HTML input type may be used as the value of the input property. Examples include "text" (for single-line text entry), "color" (for a color picker), and "date" (for entering year, month and day). In these cases, any extra properties defined (e.g., placeholder for "text" input) will be added as attributes of the generated HTML form element.

Binding Directly to External Elements

Rather than generate its own input elements, Vega also supports binding directly to an existing element defined externally. To do so, the input property must be undefined, and the element property must reference an existing, externally defined element.