This website is for Vega-Lite v4. Go to the main Vega-Lite homepage for the latest release.

Interactive Plots with Selections

Edit this page
// A Single View Specification
{
  ...,
  "selection": {  // Key-value mappings between selection names and definitions.
    ...: {"type": "single/multi/interval",  ...},
    ...
  },
  "mark": ...,
  "encoding": ...,
  ...
}

Selections are the basic building block in Vega-Lite’s grammar of interaction. They map user input (e.g., mouse moves and clicks, touch presses, etc.) into data queries, which can subsequently be used to drive conditional encoding rules, filter data points, or determine scale domains.

Documentation Overview

Selection Types

Selections are defined within single views, and their simplest definition consists of a name and a type. The selection type determines the default events that trigger a selection and the resultant data query.

Property Type Description
type String

Required. Determines the default event processing and data query for the selection. Vega-Lite currently supports three selection types:

  • "single" – to select a single discrete data value on click. - "multi" – to select multiple discrete data value; the first value is selected on click and additional values toggled on shift-click. - "interval" – to select a continuous range of data values on drag.

For example, try the different types against the example selection (named pts) below:

.

Selection Properties

While selection types provide useful defaults, it can often be useful to override these properties to customize the interaction design.

Common Selection Properties

All selection types support the following properties:

Property Type Description
clear VegaEventStream | String | Boolean

Clears the selection, emptying it of all values. Can be a Event Stream or false to disable.

Default value: dblclick.

See also: clear documentation.

empty String

By default, all data values are considered to lie within an empty selection. When set to none, empty selections contain no data values.

on VegaEventStream | String

A Vega event stream (object or selector) that triggers the selection. For interval selections, the event stream must specify a start and end.

resolve String

With layered and multi-view displays, a strategy that determines how selections’ data queries are resolved when applied in a filter transform, conditional encoding rule, or scale domain.

See also: resolve documentation.

encodings String[]

An array of encoding channels. The corresponding data field values must match for a data tuple to fall within the selection.

See also: encodings documentation.

fields String[]

An array of field names whose values must match for a data tuple to fall within the selection.

See also: fields documentation.

For instance, with the on property, a single rectangle in the heatmap below can now be selected on mouse hover instead.

Single Selection Properties

In addition to all common selection properties, single selections support the following properties:

Property Type Description
init Object

Initialize the selection with a mapping between projected channels or field names and initial values.

See also: init documentation.

bind Binding | Object | LegendBinding

When set, a selection is populated by input elements (also known as dynamic query widgets) or by interacting with the corresponding legend. Direct manipulation interaction is disabled by default; to re-enable it, set the selection’s on property.

Legend bindings are restricted to selections that only specify a single field or encoding.

Query widget binding takes the form of Vega’s input element binding definition or can be a mapping between projected field/encodings and binding definitions.

See also: bind documentation.

nearest Boolean

When true, an invisible voronoi diagram is computed to accelerate discrete selection. The data value nearest the mouse cursor is added to the selection.

See also: nearest documentation.

Multi Selection Properties

In addition to all common selection properties, multi selections support the following properties:

Property Type Description
init Object[]

Initialize the selection with a mapping between projected channels or field names and an initial value (or array of values).

See also: init documentation.

nearest Boolean

When true, an invisible voronoi diagram is computed to accelerate discrete selection. The data value nearest the mouse cursor is added to the selection.

See also: nearest documentation.

toggle String | Boolean

Controls whether data values should be toggled or only ever inserted into multi selections. Can be true, false (for insertion only), or a Vega expression.

Default value: true, which corresponds to event.shiftKey (i.e., data values are toggled when a user interacts with the shift-key pressed).

Setting the value to the Vega expression "true" will toggle data values without the user pressing the shift-key.

See also: toggle documentation.

Interval Selection Properties

In addition to all common selection properties, interval selections support the following properties:

Property Type Description
bind String

Establishes a two-way binding between the interval selection and the scales used within the same view. This allows a user to interactively pan and zoom the view.

See also: bind documentation.

init Object

Initialize the selection with a mapping between projected channels or field names and arrays of initial values.

See also: init documentation.

mark Mark

An interval selection also adds a rectangle mark to depict the extents of the interval. The mark property can be used to customize the appearance of the mark.

See also: mark documentation.

translate String | Boolean

When truthy, allows a user to interactively move an interval selection back-and-forth. Can be true, false (to disable panning), or a Vega event stream definition which must include a start and end event to trigger continuous panning.

Default value: true, which corresponds to [mousedown, window:mouseup] > window:mousemove! which corresponds to clicks and dragging within an interval selection to reposition it.

See also: translate documentation.

zoom String | Boolean

When truthy, allows a user to interactively resize an interval selection. Can be true, false (to disable zooming), or a Vega event stream definition. Currently, only wheel events are supported.

Default value: true, which corresponds to wheel!.

See also: zoom documentation.

Using Selections

Conditional Encodings

Selections can be used to conditionally specify visual encodings – encode data values one way if they fall within the selection, and another if they do not. For instance, in the first two examples on this page, rectangles are colored based on whether or not their data values fall within the pts selection. If they do, they are colored by the number of records; and, if they do not, they are left grey.

In this example, a selection (named paintbrush) is used to resize the points in the scatterplot on hover. This example is also useful for understanding the difference when empty selections are set to contain of the data values.

See the condition documentation for more information.

Filtering Data

Selections in one view can also be used to filter input data to another view. In the example below, two scatterplots are concatenated vertically. An interval selection (named brush) is defined in the first plot and is used to filter the points in the second. Thus, the Acceleration x Displacement scatterplot only visualizes points that fall within the brushed region.

Scale Domains

With multiview displays, selections can also be used to determine the domains of scales in other views. For example, in the specification below, the bottom plot contains an interval selection named brush. We use this brush selection to parameterize the domain of the top plot’s x-scale to make it show only the selected interval. This technique is called an overview+detail display.

An alternate way to construct this technique would be to filter out the input data to the top (detail) view like so:

{
  "vconcat": [{
    "transform": [{"filter": {"selection": "brush"}}],
    ...
  }]
}

However, setting the scale domains (rather than filtering data out) yields superior interactive performance. Rather than testing whether each data value falls within the selection or not, the scale domains are changed directly to the brush extents.

If the selection is projected over multiple fields or encodings, one must be given as part of the scale domain definition. Vega-Lite automatically infers this property if the selection is only projected over a single field or encoding. Thus, with the above example, the scale domain can be specified more explicitly as:

  • "scale": {"domain": {"selection": "brush", "encoding": "x"}} or
  • "scale": {"domain": {"selection": "brush", "field": "date"}}

Note: For a selection to manipulate the scales of its own view, use the bind operator instead.

Composing Multiple Selections

So far, we have only considered how to use one selection at a time. Vega-Lite also supports combining multiple selections using the not, or, and and logical composition operators.

For example, we had previously seen how we could setup two interval selections for our users Alex and Morgan. Now, we color the rectangles when they fall within Alex’s Morgan’s selections.

With these operators, selections can be combined in arbitrary ways:

  • "selection": {"not": {"and": ["alex", "morgan"]}}
  • "selection": {"or": ["alex", {"not": "morgan"}]}

When using selections with filter operators, logical composition can be used to mix selections with other filter operators. For example, as shown below, the Displacement x Acceleration scatterplot now visualizes points that lie within the brushed region and have a Weight_in_lbs > 3000.

Note: Logical composition is not supported when selections are used to drive scale domains.

Selection Configuration

// Top-level View Specification
{
  ...,
  "config": {          // Configuration Object
    "selection": { ... },   // - Selection Configuration
    ...
  }
}

The selection property of the config object determines the default properties and transformations applied to different types of selections. The selection config can contain the following properties:

Property Type Description
single Selection

The default definition for a single selection. All properties and transformations for a single selection definition (except type) may be specified here.

For instance, setting single to {"on": "dblclick"} populates single selections on double-click by default.

multi Selection

The default definition for a multi selection. All properties and transformations for a multi selection definition (except type) may be specified here.

For instance, setting multi to {"toggle": "event.altKey"} adds additional values to multi selections when clicking with the alt-key pressed by default.

interval Selection

The default definition for an interval selection. All properties and transformations for an interval selection definition (except type) may be specified here.

For instance, setting interval to {"translate": false} disables the ability to move interval selections by default.