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 \| String \| Object	The width of a visualization. For a plot with a continuous x-field, width should be a number. For a plot with either a discrete x-field or no x-field, width can be either a number indicating a fixed width or an object in the form of `{step: number}` defining the width per discrete step. (No x-field is equivalent to having one discrete step.) To enable responsive sizing on width, it should be set to `"container"`. Default value: Based on `config.view.continuousWidth` for a plot with a continuous x-field and `config.view.discreteWidth` otherwise. Note: For plots with `row` and `column` channels, this represents the width of a single view and the `"container"` option cannot be used. See also: `width` documentation.
height	Number \| String \| Object	The height of a visualization. For a plot with a continuous y-field, height should be a number. For a plot with either a discrete y-field or no y-field, height can be either a number indicating a fixed height or an object in the form of `{step: number}` defining the height per discrete step. (No y-field is equivalent to having one discrete step.) To enable responsive sizing on height, it should be set to `"container"`. Default value: Based on `config.view.continuousHeight` for a plot with a continuous y-field and `config.view.discreteHeight` otherwise. Note: For plots with `row` and `column` channels, this represents the height of a single view and the `"container"` option cannot be used. See also: `height` documentation.
view	ViewBackground	An object defining the view background’s fill and stroke. Default value: none (transparent)
encoding	SharedEncoding	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"}}.