Edit this page

To stack fields in Vega-Lite, users can either use the stack property of an encoding field definition or a stack transform inside the transform array.

Documentation Overview

Stack in Encoding Field Definition

// A Single View or a Layer Specification
  "mark/layer": ...,
  "encoding": {     // Encoding
    "x" or "y": {
      "field": ...,
      "type": "quantitative",
      "stack": ..., // Stack

The stack property of a position field definition determines type of stacking offset if the field should be stacked.

Property Type Description
stack String | Null | Boolean

Type of stacking offset if the field should be stacked. stack is only applicable for x, y, theta, and radius channels with continuous domains. For example, stack of y can be used to customize stacking for a vertical bar chart.

stack can be one of the following values:

Default value: zero for plots with all of the following conditions are true: (1) the mark is bar, area, or arc; (2) the stacked measure channel (x or y) has a linear scale; (3) At least one of non-position channels mapped to an unaggregated field that is different from x and y. Otherwise, null by default.

See also: stack documentation.

Stack Bar Chart

Adding a color field to a bar chart also creates stacked bar chart by default.

Stack Area Chart

Similarly, adding a color field to area chart also creates stacked area chart by default.

Normalized Stacked Bar and Area Charts

You can set stack to "normalize" to create normalized (or percentage) stacked bar and area charts.


Setting stack to "center" for a stacked area chart creates a streamgraph:

Layered Bar Chart

If stack is null, the marks will be layered on top of each other. In this example, setting the mark’s opacity to be semi-transparent (0.6) creates a layered bar chart.

Diverging Stacked Bar Chart (Stacked with negative values)

The stack transform can also handle negative values by creating a diverging stacked bar chart.

Note: that the stack transform cannot handle if there should be items stacked in the middle like in the “Diverging Stacked Bar Chart with Neutral Parts” example.

Sorting Stack Order

You can use the order channel to sort the order of stacked marks.

For example, given a stacked bar chart for the barley dataset:

By default, the stacked bar are sorted by the stack grouping fields (color in this example).

Mapping the sum of yield to order channel will sort the layer of stacked bar by the sum of yield instead.

Here we can see that site with higher yields for each type of barley are put on the top of the stack (rightmost).

If you want to define custom sort order, you can derive a new field using the calculate transform and sort by that field instead. For example, the following plot makes “University Farm” and “Grand Rapids” be the first (0) and second values in the stack order:

Note: we plan to have a better syntax for customized sort order in the future.

Layering Lines on top of Stacked Area Chart

Since line marks are not stacked by default, to layer lines on top of stacked area charts, you have to manually set the stack offset for the lines.

Stack Transform

// Any View Specification
  "transform": [
    // Stack Transform
      "stack": ...,
      "groupby": ...,
      "offset": ...,
      "sort": ...,
      "as": ...

For example, here is the same normalized stacked bar chart of the "population", grouped by "age" and colored by "gender", but this time using the stack property of transform.

The stack transform in the transform array has the following properties:

Property Type Description
stack String

Required. The field which is stacked.

groupby String[]

Required. The data fields to group by.

offset String

Mode for stacking marks. One of "zero" (default), "center", or "normalize". The "zero" offset will stack starting at 0. The "center" offset will center the stacks. The "normalize" offset will compute percentage values for each stack point, with output values in the range [0,1].

Default value: "zero"

sort SortField[]

Field that determines the order of leaves in the stacked charts.

as String | String[]

Required. Output field names. This can be either a string or an array of strings with two elements denoting the name for the fields for stack start and stack end respectively. If a single string(e.g., "val") is provided, the end field will be "val_end".

We can use stack transform in conjunction with other transforms to create more complicated charts.

Diverging Bar Chart

Here we initially stack by "question" and then use window transform to offset each stack.

Mosaic Chart

To create a mosaic chart we stack twice, once in each direction along with window transform.

To add labels to this chart, consult this example.