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

Interactive Plots with Selections

Edit this page
// Specification of a Single View
  "selection": {  // Key-value mappings between selection names and definitions.
    ...: {"type": "single"},

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. The following properties are available to do so:

Property Type Description
on Vega Event Stream

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

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.

resolve SelectionResolution

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.

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.

For instance, with the on property, a single rectangle in the heatmap below can now be selected on double-click instead.

Interval Selection Marks

Every interval selection also adds a rectangle mark to the visualization, to depict the extents of the selected region. The appearance of this mark can be customized with the following properties, specified under mark.

Property Type Description
fill String

The fill color of the interval mark.

Default value: #333333

fillOpacity Number

The fill opacity of the interval mark (a value between 0 and 1).

Default value: 0.125

stroke String

The stroke color of the interval mark.

Default value: #ffffff

strokeOpacity Number

The stroke opacity of the interval mark (a value between 0 and 1).

strokeWidth Number

The stroke width of the interval mark.

strokeDash Number[]

An array of alternating stroke and space lengths, for creating dashed or dotted lines.

strokeDashOffset Number

The offset (in pixels) with which to begin drawing the stroke dash array.

For example, the spec below imagines two users, Alex and Morgan, who can each drag out an interval selection. To prevent collision between the two selections, Morgan must press the shift key while dragging out their interval (while Alex must not). Morgan’s interval is depicted with the default grey rectangle, and Morgan’s with a customized red rectangle.

Note: the two intervals do not have any effect on the visualization yet (we’ll cover that next!).

Selection Transformations

Vega-Lite provides a number of selection transformations to further customize the behaviour of a selection. These include:

  • For single selections:
    • bind to input elements (also known as dynamic query widgets).
    • nearest to accelerate selecting values.
    • project over fields or encodings to change the inclusion criteria (or data query).
  • For multi selections:
    • toggle to insert or remove data values based on their membership within the selection.
    • nearest to accelerate selecting values.
    • project over fields or encodings to change the inclusion criteria (or data query).
  • For interval selections:
    • bind to scale functions to enable panning & zooming.
    • project over fields or encodings to change the inclusion criteria (or data query).
    • translate to move the selection back-and-forth.
    • zoom to resize the selection.

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.

Resolving Selections in Data-Driven Views

When a selection is defined within a data-driven view (i.e., a view that is part of a facet or repeat), the desired behaviour can be ambiguous. Consider the scatterplot matrix (SPLOM) example below, which has an interval selection named brush. Should there be only one brush across all cells, or should each cell have its own brush? In the latter case, how should points be highlighted in all the other cells?

The aptly named resolve property addresses this ambiguity, and can be set to one of the following values (click to apply it to the SPLOM example, and drag out an interval in different cells):

  • global (default) – only one brush exists for the entire SPLOM. When the user begins to drag, any previous brushes are cleared, and a new one is constructed.

  • union – each cell contains its own brush, and points are highlighted if they lie within any of these individual brushes.

  • intersect – each cell contains its own brush, and points are highlighted only if they fall within all of these individual brushes.

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.