Bind a Selection

Using the bind property, selections can be bound in the following ways:

• Single selections can be bound to input elements also known as dynamic query widgets.
• Interval selections can be bound to their own view’s scales to enable panning & zooming.
• Single and multi selections can be bound to legends.

Input Element Binding

With single selections, the bind property follows the form of Vega’s input element binding definition to establish a two-way binding between input elements and the selection. One input element per projection is generated and can be used to manipulate the selection; any direct manipulation interactions (e.g., clicking on the visualization) will similarly update the input element.

For instance, in the example below, org selects a single Origin data value, and is bound to a dropdown menu with three options to choose from.

If multiple projections are specified, customized bindings can be specified by mapping the projected field/encoding to a binding definition. For example, the scatterplot below projects over both the Cylinders and Year fields, and uses a customize range slider for each one.

Note: When a single selection is bound to input widgets, direct manipulation interaction (e.g., clicking or double clicking the visualization) is disabled by default. Such interaction can be re-enabled by explicitly specifying the on and clear properties.

Scale Binding

With interval selections, the bind property can be set to the value "scales" to enable a two-way binding between the selection and the scales used within the same view. This binding first populates the interval selection with the scale domains, and then uses the selection to drive the scale domains. As a result, the view now functions like an interval selection and can be panned and zoomed.

In multi-view displays, binding shared scales will keep the views synchronized. For example, below we explicitly share the x scale between the two vertically concatenated views. Panning/zooming the bound interval selection in the first view also updates the second view.

A similar setup can be used to pan and zoom the cells of a scatterplot matrix:

Legend Binding

When a single or multi selection is projected over only one field or encoding channel, the bind property can be set to legend to populate the selection by interacting with the corresponding legend.

To customize the events that trigger legend interaction, expand the bind property to an object, with a single legend property that maps to a Vega event stream.

Note: When a selection is bound to legends, direct manipulation interaction (e.g., clicking or double clicking the visualization) is disabled by default. Such interaction can be re-enabled by explicitly specifying the on and clear properties.

Limitations: Currently, only binding to symbol legends are supported.