Selection Parameters

Edit this page
// A Single View Specification
{
  ...,
  "params": [  // An array of named parameters.
    {
      "name": ...,
      "select": { // Selection
        "type": ...,
        ...
      }
    }
  ],
  "mark": ...,
  "encoding": ...,
  ...
}

Selection parameters define data queries that are driven by direct manipulation user input (e.g., mouse clicks or drags). A parameter becomes a selection when the select property is specified. This page discusses different properties of a selection.

Documentation Overview

Common Selection Properties

For both selection types, the select object can take the following properties:

Property Type Description
type String

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

  • "point" – to select multiple discrete data values; 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.
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: The projection with encodings and fields section in the documentation.

fields String[]

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

See also: The projection with encodings and fields section in the documentation.

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.

See also: on examples in the documentation.

clear VegaEventStream | String | Boolean

Clears the selection, emptying it of all values. This property can be a Event Stream or false to disable clear.

Default value: dblclick.

See also: clear examples in the documentation.

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.

One of:

  • "global" – 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.

Default value: global.

See also: resolve examples in the documentation.

type

A selection’s type determines which data values fall within it by default:

  • For point selections, only values that have been directly interacted with (e.g., those that have been clicked on) are considered to be “selected.”
  • For interval selections, values that fall within both the horizontal (x) and vertical (y) extents are considered to be “selected.”

Selection Projection with encodings and fields

In the scatterplot example below, highlight : .

With interval selections, we can use the projection to restrict the region to just the and/or dimensions.

Current Limitations

  • Selections projected over aggregated fields/encodings can only be used within the same view they are defined in.
  • Interval selections can only be projected using encodings.
  • Interval selections projected over binned or timeUnit fields remain continuous selections. Thus, if the visual encoding discretizes them, conditional encodings will no longer work. Instead, use a layered view as shown in the example below. The bar mark discretizes the binned Acceleration field. As a result, to highlight selected bars, we use a second layered view rather than a conditional color encoding within the same view.

on

The on property modifies the event that triggers the selection.

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

clear

The clear property identifies which events must fire to empty a selection of all selected values (the empty property can be used to further determine the behavior of empty selections).

The following visualization demonstrates the default clearing behavior: select a square on click and clear out the selection on double click.

The following example clears the brush when the mouse button is released.

Note, in the above example, clearing out the selection does not reset it to its initial value. Instead, when the mouse button is released, the selection is emptied of all values. This behavior is subtly different to when the selection is bound to scales – clearing the selection out now resets the view to use the initial scale domains. Try it out below: pan and zoom the plot, and then double click.

resolve

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.

Point Selection Properties

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

Property Type Description
toggle String | Boolean

Controls whether data values should be toggled (inserted or removed from a point selection) or only ever inserted into multi selections.

One of:

  • true – the default behavior, which corresponds to "event.shiftKey". As a result, data values are toggled when the user interacts with the shift-key pressed.
  • false – disables toggling behaviour; as the user interacts, data values are only inserted into the multi selection and never removed.
  • A Vega expression which is re-evaluated as the user interacts. If the expression evaluates to true, the data value is toggled into or out of the multi selection. If the expression evaluates to false, the multi selection is first clear, and the data value is then inserted. For example, setting the value to the Vega expression "true" will toggle data values without the user pressing the shift-key.

Default value: true

See also: toggle examples in the 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.

Default value: false, which means that data values must be interacted with directly (e.g., clicked on) to be added to the selection.

See also: nearest examples documentation.

toggle

The toggle property customizes how user interaction can insert or remove data values from a point selection if they are or are not already members of the selection, respectively.

For example, you can highlight points in the scatterplot below by into the paintbrush selection when clicking with:
.

Nearest

The nearest propery accelerates user selection with an invisible voronoi diagram.

For example, in the scatterplot below, points the mouse cursor are highlighted as it moves.

The nearest transform also respects any position encoding projections applied to the selection. For instance, in the example below, moving the mouse cursor back-and-forth snaps the vertical rule and label to the nearest date value.

Current Limitations

  • The nearest property is not supported for multi-element mark types (i.e., line and area). For these mark types, consider layering a discrete mark type (e.g., point) with a 0-value opacity as in the last example above.

Interval Selection Properties

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

Property Type Description
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 examples in the 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. Discrete panning (e.g., pressing the left/right arrow keys) will be supported in future versions.

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

See also: translate examples in the 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, but custom event streams can still be used to specify filters, debouncing, and throttling. Future versions will expand the set of events that can trigger this transformation.

Default value: true, which corresponds to wheel!. This default allows users to use the mouse wheel to resize an interval selection.

See also: zoom examples in the documentation.

mark

Every interval selection also adds a rectangle mark to the visualization, to depict the extents of the selected region.

The selection’s mark property can include the folloiwing properties to customize the appearance of this rectangle mark.

Property Type Description
cursor String

The mouse cursor used over the interval mark. Any valid CSS cursor type can be used.

fill Color

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 Color

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.

translate

The translate property allows a user to interactively move an interval selection back-and-forth.

For example, try to pan the on .

zoom

The zoom property allows a user to interactively resize an interval selection.

For example, you can zoom the on .