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

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:

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:

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.


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"}}.