Layering views

Edit this page

Sometimes, it’s useful to superimpose one chart on top of another. You can accomplish this by using the layer operator. This operator is one of Vega-Lite’s view composition operators. To define a layered chart, put multiple specifications into an array under the layer property.

{
  "layer": [
    ...  // Single or layered view specifications
  ]
}

In addition to common properties of a view specification, a layer specification has the following properties:

Property	Type	Description
layer	LayerSpec[] \| UnitSpec[]	*Required.* Layer or single view specifications to be layered. Note: Specifications inside `layer` cannot use `row` and `column` channels as layering facet specifications is not allowed. Instead, use the facet operator and place a layer inside a facet.
width	Number	The width of a visualization. Default value: This will be determined by the following rules: If a view’s `autosize` type is `"fit"` or its x-channel has a continuous scale, the width will be the value of `config.view.width`. For x-axis with a band or point scale: if `rangeStep` is a numeric value or unspecified, the width is determined by the range step, paddings, and the cardinality of the field mapped to x-channel. Otherwise, if the `rangeStep` is `null`, the width will be the value of `config.view.width`. If no field is mapped to `x` channel, the `width` will be the value of `config.scale.textXRangeStep` for `text` mark and the value of `rangeStep` for other marks. Note: For plots with `row` and `column` channels, this represents the width of a single view. See also: The documentation for width and height contains more examples.
height	Number	The height of a visualization. Default value: If a view’s `autosize` type is `"fit"` or its y-channel has a continuous scale, the height will be the value of `config.view.height`. For y-axis with a band or point scale: if `rangeStep` is a numeric value or unspecified, the height is determined by the range step, paddings, and the cardinality of the field mapped to y-channel. Otherwise, if the `rangeStep` is `null`, the height will be the value of `config.view.height`. If no field is mapped to `y` channel, the `height` will be the value of `rangeStep`. Note: For plots with `row` and `column` channels, this represents the height of a single view. See also: The documentation for width and height contains more examples.
view	spec.html#view-background	An object defining the view background’s fill and stroke. Default value: none (transparent)
encoding	Encoding	A shared key-value mapping between encoding channels and definition of fields in the underlying layers.
projection	Projection	An object defining properties of the geographic projection shared by underlying layers.
resolve	Resolve	Scale, axis, and legend resolutions for view composition specifications.

Please note that you can only layer single or layered views to guarantee that the combined views have a compatible layout. For instance, it is not clear how a composed view with two views side-by-side could be layered on top of a single view.

Example

A layered chart consistent of multiple charts that are drawn on top of each other. We will start by creating specifications for the individual layers and eventually combine them in a single layer spec.

The first chart is a line chart that shows the stock price of different stocks over time.

The second chart shows the mean price of individual stocks with a rule mark. The rule mark is a special mark that can span the whole width/height of a single view specification.

To layer these two charts on top of each other, we have to put the two specifications in the same layer array. Note that we can leave data at the top level as both layers use the same data.

See the example gallery for more layering examples.

Combined Scales and Guides

When you have different scales in different layers, the scale domains are unioned so that all layers can use the same scale. In the example above, Vega-Lite automatically uses a common y-axis and color legend. We can disable this by setting the resolve property.

The default resolutions for layer are shared scales, axes, and legends.

In the chart below, we set the y-scales of the different layers to be independent with "resolve": {"scale": {"y": "independent"}}.