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

Area

Edit this page 
// Single View Specification
{
  "data": ... ,
  "mark": "area",
  "encoding": ... ,
  ...
}

area represent multiple data element as a single area shape. Area marks are often used to show change over time, using either a single area or stacked areas.

Documentation Overview

Area Mark Properties

// Single View Specification
{
  ...
  "mark": {
    "type": "area",
    ...
  },
  "encoding": ... ,
  ...
}

An area mark definition can contain any standard mark properties and the following line interpolation as well as line and point overlay properties:

Property Type Description
orient String

The orientation of a non-stacked bar, tick, area, and line charts. The value is either horizontal (default) or vertical.

  • For bar, rule and tick, this determines whether the size of the bar and tick should be applied to x or y dimension.
  • For area, this property determines the orient property of the Vega output.
  • For line and trail marks, this property determines the sort order of the points in the line if config.sortLineBy is not specified. For stacked charts, this is always determined by the orientation of the stack; therefore explicitly specified value will be ignored.
interpolate String

The line interpolation method to use for line and area marks. One of the following:

  • "linear": piecewise linear segments, as in a polyline.
  • "linear-closed": close the linear segments to form a polygon.
  • "step": alternate between horizontal and vertical segments, as in a step function.
  • "step-before": alternate between vertical and horizontal segments, as in a step function.
  • "step-after": alternate between horizontal and vertical segments, as in a step function.
  • "basis": a B-spline, with control point duplication on the ends.
  • "basis-open": an open B-spline; may not intersect the start or end.
  • "basis-closed": a closed B-spline, as in a loop.
  • "cardinal": a Cardinal spline, with control point duplication on the ends.
  • "cardinal-open": an open Cardinal spline; may not intersect the start or end, but will intersect other control points.
  • "cardinal-closed": a closed Cardinal spline, as in a loop.
  • "bundle": equivalent to basis, except the tension parameter is used to straighten the spline.
  • "monotone": cubic interpolation that preserves monotonicity in y.
tension Number

Depending on the interpolation type, sets the tension parameter (for line and area marks).
line Boolean | OverlayMarkDef

A flag for overlaying line on top of area marks, or an object defining the properties of the overlayed lines.

  • If this value is an empty object ({}) or true, lines with default properties will be used.

  • If this value is false, no lines would be automatically added to area marks.

Default value: false.
point Boolean | OverlayMarkDef | String

A flag for overlaying points on top of line or area marks, or an object defining the properties of the overlayed points.

  • If this property is "transparent", transparent points will be used (for enhancing tooltips and selections).

  • If this property is an empty object ({}) or true, filled points with default properties will be used.

  • If this property is false, no points would be automatically added to line or area marks.

Default value: false.

Examples

Area Chart

Using area mark with one temporal or ordinal field (typically on x) and one quantitative field (typically on y) produces an area chart. For example, the following area chart shows a number of unemployment people in the US over time.

Area Chart with Overlaying Lines and Point Markers

By setting the line and point properties of the mark definition to true or an object defining a property of the overlaying point marks, we can overlay line and point markers on top of area.

Stacked Area Chart

Adding a color field to area chart creates stacked area chart by default. For example, here we split the area chart by industry.

Normalized Stacked Area Chart

You can also create a normalized stacked area chart by setting "stack" to "normalize" in the encoding channel. Here we can easily see the percentage of unemployment across industries.

Streamgraph

We can also shift the stacked area chart’s baseline to center and produces a streamgraph by setting "stack" to "center" in the encoding channel.

Ranged Area

Specifying x2 or y2 for the quantitative axis of area marks produce ranged areas. For example, we can use ranged area with the ci0 and ci0 aggregation operators to highlight 95% confidence interval of a line chart that shows mean values over time.

Area Config

// Top-level View Specification
{
  ...
  "config": {
    "area": ...,
    ...
  }
}

The area property of the top-level config object sets the default properties for all area marks. If mark property encoding channels are specified for marks, these config values will be overridden.

The area config can contain any area mark properties (except type, style, clip, and orient).